cgraphx 2.0.1 → 2.0.3

package/dist/core/code/shared/integrations/circuit-breaker.js

@@ -0,0 +1,242 @@
+"use strict";
+/**
+ * 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()`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CircuitBreaker = exports.CircuitOpenError = void 0;
+exports.getBreaker = getBreaker;
+exports.__resetBreakerRegistry__ = __resetBreakerRegistry__;
+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;
+    }
+}
+exports.CircuitOpenError = CircuitOpenError;
+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;
+    }
+}
+exports.CircuitBreaker = CircuitBreaker;
+// ─── 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();
+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.
+ */
+function __resetBreakerRegistry__() {
+    registry.clear();
+}

package/dist/core/code/shared/integrations/resilient-fetch.js

@@ -0,0 +1,224 @@
+"use strict";
+/**
+ * `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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ResilientFetchExhaustedError = exports.RETRY_AFTER_CAP_MS = exports.CircuitOpenError = void 0;
+exports.parseRetryAfter = parseRetryAfter;
+exports.isTerminalNetworkError = isTerminalNetworkError;
+exports.classifyOutcome = classifyOutcome;
+exports.resilientFetch = resilientFetch;
+const circuit_breaker_js_1 = require("./circuit-breaker.js");
+Object.defineProperty(exports, "CircuitOpenError", { enumerable: true, get: function () { return circuit_breaker_js_1.CircuitOpenError; } });
+const retry_js_1 = require("./retry.js");
+/** Cap on any single Retry-After wait — protects CLI from a buggy registry. */
+exports.RETRY_AFTER_CAP_MS = 30_000;
+const DEFAULT_RETRY = {
+    maxAttempts: 3,
+    baseDelayMs: 500,
+    capDelayMs: 5_000,
+};
+/**
+ * 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.
+ */
+function parseRetryAfter(value, now = Date.now) {
+    if (!value)
+        return null;
+    const trimmed = value.trim();
+    if (trimmed === '')
+        return null;
+    if (/^[0-9]+$/.test(trimmed)) {
+        const seconds = parseInt(trimmed, 10);
+        if (Number.isNaN(seconds) || seconds < 0)
+            return null;
+        return seconds * 1000;
+    }
+    const target = Date.parse(trimmed);
+    if (Number.isNaN(target))
+        return null;
+    const delta = target - now();
+    return delta >= 0 ? delta : 0;
+}
+/**
+ * The network errors `resilientFetch` treats as terminal — never retried, and
+ * routed through the breaker's neutral path.
+ *
+ * Both timer-fired aborts (`AbortSignal.timeout()` → `TimeoutError`) and
+ * caller-driven aborts (`AbortController.abort()` → `AbortError`) qualify:
+ * retrying against an already-aborted signal would fail again immediately, and
+ * neither outcome reflects backend health.
+ *
+ * Exported because callers that hook into the retry loop (a `fetchImpl` that
+ * inspects or re-wraps its own throws) have to agree with {@link
+ * classifyOutcome} about which errors are terminal. Sharing this predicate is
+ * what makes that agreement structural instead of a hand-copied condition that
+ * can drift.
+ */
+function isTerminalNetworkError(err) {
+    return err instanceof DOMException && (err.name === 'TimeoutError' || err.name === 'AbortError');
+}
+/** Exported for unit tests. */
+function classifyOutcome(result, now, retryAfterCapMs = exports.RETRY_AFTER_CAP_MS) {
+    if (result.kind === 'error') {
+        if (isTerminalNetworkError(result.err)) {
+            return { kind: 'terminal-network', err: result.err };
+        }
+        return { kind: 'retryable-network', err: result.err };
+    }
+    const resp = result.resp;
+    if (resp.status >= 200 && resp.status < 400)
+        return { kind: 'success', resp };
+    if (resp.status === 429) {
+        // `resp.headers` is always present on a real `Response`, but tests
+        // sometimes stub `fetch` with a plain `{ ok, status }` object. Be
+        // defensive — a missing `Retry-After` falls through to exponential
+        // backoff, which is the correct behaviour anyway.
+        const retryAfterHeader = typeof resp.headers?.get === 'function' ? resp.headers.get('Retry-After') : null;
+        const parsed = parseRetryAfter(retryAfterHeader, now);
+        return {
+            kind: 'retryable-status',
+            resp,
+            afterMs: parsed !== null ? Math.min(parsed, retryAfterCapMs) : undefined,
+        };
+    }
+    if (resp.status >= 500)
+        return { kind: 'retryable-status', resp, afterMs: undefined };
+    return { kind: 'terminal-client', resp };
+}
+const defaultSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+function defaultBreakerKey(input) {
+    try {
+        const url = typeof input === 'string' ? new URL(input) : input;
+        return `${url.host}${url.pathname}`;
+    }
+    catch {
+        return String(input);
+    }
+}
+/** Final error thrown when retries are exhausted on a 5xx / 429. */
+class ResilientFetchExhaustedError extends Error {
+    response;
+    name = 'ResilientFetchExhaustedError';
+    constructor(response) {
+        super(`Request failed after retries (HTTP ${response.status})`);
+        this.response = response;
+    }
+}
+exports.ResilientFetchExhaustedError = ResilientFetchExhaustedError;
+/**
+ * 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()`.
+ */
+async function resilientFetch(input, init, opts = {}) {
+    const fetchImpl = opts.fetchImpl ?? globalThis.fetch;
+    const now = opts.now ?? (() => Date.now());
+    const breaker = opts.breaker ?? (0, circuit_breaker_js_1.getBreaker)(opts.breakerKey ?? defaultBreakerKey(input), opts.breakerOptions);
+    const retryConfig = {
+        maxAttempts: opts.retry?.maxAttempts ?? DEFAULT_RETRY.maxAttempts,
+        baseDelayMs: opts.retry?.baseDelayMs ?? DEFAULT_RETRY.baseDelayMs,
+        capDelayMs: opts.retry?.capDelayMs ?? DEFAULT_RETRY.capDelayMs,
+        retryAfterCapMs: opts.retry?.retryAfterCapMs ?? exports.RETRY_AFTER_CAP_MS,
+    };
+    const sleep = opts.retry?.sleep ?? defaultSleep;
+    const random = opts.retry?.random ?? Math.random;
+    // Fail fast on an open breaker, before invoking fetch.
+    breaker.check();
+    for (let attempt = 0; attempt < retryConfig.maxAttempts; attempt++) {
+        let result;
+        try {
+            // CodeQL js/server-side-request-forgery — flagged because `input`
+            // is caller-supplied. Suppressed: every concrete caller passes
+            // either a hardcoded URL constant (UNDERSTAND_QUICKLY_DISPATCH_URL,
+            // OpenRouter base URL) or a value derived from configuration
+            // (env vars, saved settings, the local backend URL). User-input
+            // request fields (e.g. PR title, repo name) never flow into
+            // `input`. Validating URL shape here would push false-positive
+            // rejection onto every caller — wrong layer for the check.
+            // lgtm[js/server-side-request-forgery]
+            // codeql[js/server-side-request-forgery]
+            const resp = await fetchImpl(input, init);
+            result = { kind: 'response', resp };
+        }
+        catch (err) {
+            result = { kind: 'error', err };
+        }
+        const outcome = classifyOutcome(result, now, retryConfig.retryAfterCapMs);
+        switch (outcome.kind) {
+            case 'success':
+                breaker.recordSuccess();
+                return outcome.resp;
+            case 'terminal-client':
+                // 4xx: do not count as breaker failure (the server is healthy
+                // and rejecting our request — auth, scope, or routing). But
+                // also do NOT call recordSuccess: a 401 sandwiched between
+                // 5xx responses would otherwise erase the running outage
+                // signal. The breaker's neutral path leaves state untouched.
+                breaker.recordNeutral();
+                return outcome.resp;
+            case 'terminal-network':
+                // Either `AbortSignal.timeout()` fired locally OR an external
+                // caller cancelled the request via AbortController. The server
+                // never had a chance to answer; this reflects the user's
+                // network or an explicit cancel, not registry health. Don't
+                // punish the breaker AND don't reset its outage signal.
+                breaker.recordNeutral();
+                throw outcome.err;
+            case 'retryable-status':
+                if (attempt + 1 >= retryConfig.maxAttempts) {
+                    breaker.recordFailure();
+                    throw new ResilientFetchExhaustedError(outcome.resp);
+                }
+                await sleep((0, retry_js_1.computeBackoffMs)(attempt, retryConfig.baseDelayMs, retryConfig.capDelayMs, outcome.afterMs, random));
+                break;
+            case 'retryable-network':
+                if (attempt + 1 >= retryConfig.maxAttempts) {
+                    breaker.recordFailure();
+                    throw outcome.err;
+                }
+                await sleep((0, retry_js_1.computeBackoffMs)(attempt, retryConfig.baseDelayMs, retryConfig.capDelayMs, undefined, random));
+                break;
+            default: {
+                // Exhaustiveness guard. If a sixth `Outcome` kind is added in
+                // future, TypeScript will refuse to assign it to `never` and
+                // this line forces the maintainer to add an explicit arm
+                // rather than silently fall through to retry/no-retry behaviour.
+                const _exhaustive = outcome;
+                throw new Error(`resilientFetch: unhandled outcome ${JSON.stringify(_exhaustive)}`);
+            }
+        }
+    }
+    // Unreachable: every iteration of the loop either returns (success
+    // / terminal-client) or throws (terminal-network / retry exhaustion).
+    // The throw is here purely so TypeScript's control-flow analysis sees
+    // the function never falls off the end without producing `Promise<Response>`.
+    /* c8 ignore next 2 */
+    throw new Error('resilientFetch: retry loop terminated unexpectedly');
+}

package/dist/core/code/shared/integrations/retry.js

@@ -0,0 +1,70 @@
+"use strict";
+/**
+ * Bounded retry helper with full-jitter exponential backoff.
+ *
+ * Runtime-agnostic: depends only on `setTimeout`, `Math.random`, and the
+ * Promise machinery — no Node-only imports. Safe to consume from CLI,
+ * server, or browser callers.
+ *
+ * Pattern reference: cgraph/src/core/embeddings/http-client.ts. This
+ * helper is the upgraded form: classification is caller-supplied (so
+ * 4xx-vs-5xx-vs-timeout decisions live with the protocol that knows
+ * them), backoff is exponential with full jitter, and an optional
+ * `afterMs` lets callers honor `Retry-After` headers.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.computeBackoffMs = computeBackoffMs;
+exports.withRetry = withRetry;
+const defaultSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+/**
+ * Compute the delay before the next retry attempt.
+ *
+ * - When the caller specifies `afterMs` (e.g., from `Retry-After`), use
+ *   `min(afterMs, capDelayMs)` so a misbehaving server can't pin the
+ *   client for an arbitrarily long wait.
+ * - Otherwise compute full-jitter exponential backoff:
+ *   `random() * min(cap, base * 2^attempt)`. Full jitter (rather than
+ *   "equal jitter") avoids retry-storm thundering herd, per AWS
+ *   guidance on backoff strategies.
+ */
+function computeBackoffMs(attempt, baseDelayMs, capDelayMs, afterMs, random) {
+    if (afterMs !== undefined) {
+        return Math.min(Math.max(0, afterMs), capDelayMs);
+    }
+    const exponential = baseDelayMs * Math.pow(2, attempt);
+    const upper = Math.min(capDelayMs, exponential);
+    return Math.floor(random() * upper);
+}
+/**
+ * Execute `fn` with bounded retries.
+ *
+ * The classification of "retryable" is the caller's responsibility — see
+ * `resilient-fetch.ts` for the GitHub-dispatch-specific rules. This
+ * helper is the mechanical retry loop only.
+ */
+async function withRetry(fn, opts) {
+    if (opts.maxAttempts < 1) {
+        throw new Error(`withRetry: maxAttempts must be >= 1, got ${opts.maxAttempts}`);
+    }
+    const sleep = opts.sleep ?? defaultSleep;
+    const random = opts.random ?? Math.random;
+    let lastError;
+    for (let attempt = 0; attempt < opts.maxAttempts; attempt++) {
+        try {
+            return await fn(attempt);
+        }
+        catch (err) {
+            lastError = err;
+            const decision = opts.isRetryable(err, attempt);
+            if (!decision.retry)
+                throw err;
+            // Don't sleep after the final attempt.
+            if (attempt + 1 >= opts.maxAttempts)
+                break;
+            const delayMs = computeBackoffMs(attempt, opts.baseDelayMs, opts.capDelayMs, decision.afterMs, random);
+            if (delayMs > 0)
+                await sleep(delayMs);
+        }
+    }
+    throw lastError;
+}

package/dist/core/code/shared/integrations/understand-quickly.js

@@ -0,0 +1,145 @@
+"use strict";
+/**
+ * Understand-Quickly registry integration helpers.
+ *
+ * Pure, runtime-agnostic logic for opting in to publishing a GitNexus
+ * index to the [`looptech-ai/understand-quickly`](https://github.com/looptech-ai/understand-quickly)
+ * registry. Lives in `cgraph-shared` so both the Node CLI and any
+ * future browser-side surface can construct identical dispatch payloads.
+ *
+ * Network I/O lives in the CLI command (`cgraph/src/cli/publish.ts`)
+ * to keep this module free of Node-only imports — see the comment at
+ * the top of `cgraph-shared/src/graph/types.ts`.
+ *
+ * The protocol contract (single dispatch event, no graph upload) is
+ * documented at:
+ *   https://github.com/looptech-ai/understand-quickly/blob/main/docs/integrations/protocol.md
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UNDERSTAND_QUICKLY_TOKEN_ENV = exports.UNDERSTAND_QUICKLY_EVENT_TYPE = exports.UNDERSTAND_QUICKLY_DISPATCH_URL = void 0;
+exports.buildUqDispatchPayload = buildUqDispatchPayload;
+exports.isValidOwnerRepo = isValidOwnerRepo;
+exports.stripGitSuffix = stripGitSuffix;
+exports.parseOwnerRepoFromRemote = parseOwnerRepoFromRemote;
+/**
+ * URL of the registry repo's repository_dispatch endpoint. Hardcoded
+ * because the registry is the canonical home for this integration —
+ * users who want a private registry can fork and patch.
+ */
+exports.UNDERSTAND_QUICKLY_DISPATCH_URL = 'https://api.github.com/repos/looptech-ai/understand-quickly/dispatches';
+/**
+ * Event type the registry's sync workflow listens for.
+ * See `looptech-ai/understand-quickly/.github/workflows/sync.yml`.
+ */
+exports.UNDERSTAND_QUICKLY_EVENT_TYPE = 'sync-entry';
+/** Environment variable that gates the dispatch. */
+exports.UNDERSTAND_QUICKLY_TOKEN_ENV = 'UNDERSTAND_QUICKLY_TOKEN';
+/**
+ * Build the JSON body for the `repository_dispatch` ping. Pure — no
+ * env reads, no network. Validates that `id` looks like `owner/repo`
+ * (one slash, no whitespace, both halves non-empty) so a misconfigured
+ * caller fails loudly before the round-trip.
+ */
+function buildUqDispatchPayload(id) {
+    if (!isValidOwnerRepo(id)) {
+        throw new Error(`[understand-quickly] expected id of the form "owner/repo", got "${id}". ` +
+            `The registry uses this string to look up your entry in registry.json — ` +
+            `it must match the GitHub owner/repo of the source code, not a local path.`);
+    }
+    return {
+        event_type: exports.UNDERSTAND_QUICKLY_EVENT_TYPE,
+        client_payload: { id },
+    };
+}
+/**
+ * `owner/repo` validation. Conservative on purpose: GitHub's actual
+ * naming rules are looser, but we want to catch local paths
+ * (`/Users/...`), bare slugs (`my-repo`), and accidental whitespace.
+ *
+ * Matches GitHub's published slug rules:
+ *   owner: starts with alnum, then alnum/hyphen only, must end with
+ *          alnum (no trailing hyphen — GitHub rejects this at account
+ *          creation, so a `my-org-/repo` input would otherwise pass us
+ *          and 422 from GitHub). No underscore, no dot. Length cap 39.
+ *   repo:  any of alnum/dot/hyphen/underscore. Length cap 100.
+ */
+function isValidOwnerRepo(id) {
+    return /^[A-Za-z0-9](?:[A-Za-z0-9-]{0,37}[A-Za-z0-9])?\/[A-Za-z0-9._-]{1,100}$/.test(id);
+}
+/**
+ * Strip a single trailing `.git` (case-insensitive) and any trailing
+ * slashes from a URL-ish string. Bounded linear: each character is
+ * visited at most twice, no backtracking.
+ *
+ * Replaces `s.replace(/\.git\/*$/i, '').replace(/\/+$/, '')` which
+ * CodeQL's polynomial-regex check (codeql/js/polynomial-redos) flags as
+ * a worst-case O(n²) on adversarial input like "////.../x".
+ */
+function stripGitSuffix(input) {
+    let end = input.length;
+    // Trim trailing '/'.
+    while (end > 0 && input.charCodeAt(end - 1) === 0x2f)
+        end--;
+    // Drop one trailing '.git' (case-insensitive).
+    if (end >= 4) {
+        const tail = input.slice(end - 4, end).toLowerCase();
+        if (tail === '.git')
+            end -= 4;
+    }
+    // Trim trailing '/' that may have sat between '.git' and the rest.
+    while (end > 0 && input.charCodeAt(end - 1) === 0x2f)
+        end--;
+    return input.slice(0, end);
+}
+/**
+ * Parse `owner/repo` out of a git remote URL. Mirrors the heuristic in
+ * `cgraph/src/storage/git.ts:parseRepoNameFromUrl` but keeps both
+ * halves so we can build a registry id. Returns `null` on shapes we
+ * don't recognise.
+ *
+ * Examples:
+ *   git@github.com:looptech-ai/understand-quickly.git
+ *   https://github.com/looptech-ai/understand-quickly
+ *   ssh://git@github.com/looptech-ai/understand-quickly.git
+ */
+function parseOwnerRepoFromRemote(url) {
+    if (!url)
+        return null;
+    const trimmed = url.trim();
+    if (!trimmed)
+        return null;
+    // Strip a trailing `.git` (case-insensitive) and any trailing slashes
+    // so https://h/o/r and https://h/o/r.git collapse to the same id.
+    // Bounded-linear helper avoids the polynomial-regex CodeQL alert.
+    const stripped = stripGitSuffix(trimmed);
+    // SCP-form SSH (`git@host:owner/repo`). Capture host so we can reject
+    // non-GitHub remotes — a GitLab origin like
+    // `https://gitlab.example.com/group/sub/project.git` would otherwise
+    // silently dispatch the wrong id (LOW 9).
+    const ssh = stripped.match(/^[^@]+@([^:]+):([^/]+)\/([^/]+)$/);
+    if (ssh) {
+        const host = ssh[1].toLowerCase();
+        if (host !== 'github.com' && host !== 'www.github.com')
+            return null;
+        return `${ssh[2]}/${ssh[3]}`;
+    }
+    // URL forms (https://, ssh://, git://, file://) — last two path segments.
+    const url2 = stripped.match(/^[a-zA-Z][a-zA-Z0-9+.-]*:\/\/([^/]+)\/(.+)$/);
+    if (url2) {
+        // Strip optional `userinfo@` (e.g. `ssh://git@github.com/...`).
+        const authority = url2[1];
+        const atIdx = authority.lastIndexOf('@');
+        const hostAndPort = atIdx >= 0 ? authority.slice(atIdx + 1) : authority;
+        // Strip `:port` suffix if present.
+        const colonIdx = hostAndPort.indexOf(':');
+        const host = (colonIdx >= 0 ? hostAndPort.slice(0, colonIdx) : hostAndPort).toLowerCase();
+        if (host !== 'github.com' && host !== 'www.github.com')
+            return null;
+        const segments = url2[2].split('/').filter(Boolean);
+        if (segments.length >= 2) {
+            const [owner, repo] = segments.slice(-2);
+            return `${owner}/${repo}`;
+        }
+    }
+    return null;
+}