gitnexus 1.6.4-rc.99 → 1.6.4

package/dist/_shared/integrations/resilient-fetch.js

@@ -0,0 +1,204 @@
+/**
+ * `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 { CircuitOpenError, getBreaker, } from './circuit-breaker.js';
+import { computeBackoffMs } from './retry.js';
+export { CircuitOpenError };
+/** Cap on any single Retry-After wait — protects CLI from a buggy registry. */
+export const 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.
+ */
+export 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;
+}
+/** Exported for unit tests. */
+export function classifyOutcome(result, now) {
+    if (result.kind === 'error') {
+        // Both timer-fired aborts (`AbortSignal.timeout()` → `TimeoutError`)
+        // and caller-driven aborts (`AbortController.abort()` → `AbortError`)
+        // are terminal: retrying against an already-aborted signal would
+        // fail again immediately, and neither outcome reflects backend
+        // health. They route through the breaker's neutral path.
+        if (result.err instanceof DOMException &&
+            (result.err.name === 'TimeoutError' || result.err.name === 'AbortError')) {
+            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, RETRY_AFTER_CAP_MS) : 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. */
+export class ResilientFetchExhaustedError extends Error {
+    response;
+    name = 'ResilientFetchExhaustedError';
+    constructor(response) {
+        super(`Request failed after retries (HTTP ${response.status})`);
+        this.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 async function resilientFetch(input, init, opts = {}) {
+    const fetchImpl = opts.fetchImpl ?? globalThis.fetch;
+    const now = opts.now ?? (() => Date.now());
+    const breaker = opts.breaker ?? 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,
+    };
+    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);
+        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(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(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');
+}
+//# sourceMappingURL=resilient-fetch.js.map

package/dist/_shared/integrations/resilient-fetch.js.map

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

package/dist/_shared/integrations/retry.d.ts

@@ -0,0 +1,60 @@
+/**
+ * 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: gitnexus/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.
+ */
+export interface RetryOptions {
+    /** Initial delay before the first retry attempt, in milliseconds. */
+    baseDelayMs: number;
+    /** Upper bound on any single delay, in milliseconds. */
+    capDelayMs: number;
+    /** Total attempts including the first call. Must be >= 1. */
+    maxAttempts: number;
+    /**
+     * Decide whether to retry after a thrown error.
+     * Return `{retry:false}` to terminate immediately and rethrow.
+     * Return `{retry:true}` to retry with exponential-backoff jitter.
+     * Return `{retry:true, afterMs}` to wait at least `afterMs` (still
+     * subject to `capDelayMs`) — used by callers parsing `Retry-After`.
+     */
+    isRetryable: (err: unknown, attempt: number) => RetryDecision;
+    /** Sleep override — defaults to `setTimeout`. Tests inject fake timers. */
+    sleep?: (ms: number) => Promise<void>;
+    /** Random override — defaults to `Math.random`. Tests inject seeded values. */
+    random?: () => number;
+}
+export type RetryDecision = {
+    retry: false;
+} | {
+    retry: true;
+    afterMs?: number;
+};
+/**
+ * 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.
+ */
+export declare function computeBackoffMs(attempt: number, baseDelayMs: number, capDelayMs: number, afterMs: number | undefined, random: () => number): number;
+/**
+ * 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.
+ */
+export declare function withRetry<T>(fn: (attempt: number) => Promise<T>, opts: RetryOptions): Promise<T>;
+//# sourceMappingURL=retry.d.ts.map

package/dist/_shared/integrations/retry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry.d.ts","sourceRoot":"","sources":["../../src/integrations/retry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,MAAM,WAAW,YAAY;IAC3B,qEAAqE;IACrE,WAAW,EAAE,MAAM,CAAC;IACpB,wDAAwD;IACxD,UAAU,EAAE,MAAM,CAAC;IACnB,6DAA6D;IAC7D,WAAW,EAAE,MAAM,CAAC;IACpB;;;;;;OAMG;IACH,WAAW,EAAE,CAAC,GAAG,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,KAAK,aAAa,CAAC;IAC9D,2EAA2E;IAC3E,KAAK,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACtC,+EAA+E;IAC/E,MAAM,CAAC,EAAE,MAAM,MAAM,CAAC;CACvB;AAED,MAAM,MAAM,aAAa,GAAG;IAAE,KAAK,EAAE,KAAK,CAAA;CAAE,GAAG;IAAE,KAAK,EAAE,IAAI,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAKjF;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,MAAM,EACf,WAAW,EAAE,MAAM,EACnB,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,MAAM,GAAG,SAAS,EAC3B,MAAM,EAAE,MAAM,MAAM,GACnB,MAAM,CAOR;AAED;;;;;;GAMG;AACH,wBAAsB,SAAS,CAAC,CAAC,EAC/B,EAAE,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,EACnC,IAAI,EAAE,YAAY,GACjB,OAAO,CAAC,CAAC,CAAC,CA4BZ"}

package/dist/_shared/integrations/retry.js

@@ -0,0 +1,67 @@
+/**
+ * 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: gitnexus/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.
+ */
+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.
+ */
+export 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.
+ */
+export 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;
+}
+//# sourceMappingURL=retry.js.map

package/dist/_shared/integrations/retry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry.js","sourceRoot":"","sources":["../../src/integrations/retry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAyBH,MAAM,YAAY,GAAG,CAAC,EAAU,EAAiB,EAAE,CACjD,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,CAAC;AAEpD;;;;;;;;;;GAUG;AACH,MAAM,UAAU,gBAAgB,CAC9B,OAAe,EACf,WAAmB,EACnB,UAAkB,EAClB,OAA2B,EAC3B,MAAoB;IAEpB,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;QAC1B,OAAO,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,OAAO,CAAC,EAAE,UAAU,CAAC,CAAC;IACpD,CAAC;IACD,MAAM,WAAW,GAAG,WAAW,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC;IACvD,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,UAAU,EAAE,WAAW,CAAC,CAAC;IAChD,OAAO,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,GAAG,KAAK,CAAC,CAAC;AACtC,CAAC;AAED;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,SAAS,CAC7B,EAAmC,EACnC,IAAkB;IAElB,IAAI,IAAI,CAAC,WAAW,GAAG,CAAC,EAAE,CAAC;QACzB,MAAM,IAAI,KAAK,CAAC,4CAA4C,IAAI,CAAC,WAAW,EAAE,CAAC,CAAC;IAClF,CAAC;IACD,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,IAAI,YAAY,CAAC;IACzC,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,IAAI,IAAI,CAAC,MAAM,CAAC;IAE1C,IAAI,SAAkB,CAAC;IACvB,KAAK,IAAI,OAAO,GAAG,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC,WAAW,EAAE,OAAO,EAAE,EAAE,CAAC;QAC5D,IAAI,CAAC;YACH,OAAO,MAAM,EAAE,CAAC,OAAO,CAAC,CAAC;QAC3B,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,SAAS,GAAG,GAAG,CAAC;YAChB,MAAM,QAAQ,GAAG,IAAI,CAAC,WAAW,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;YAChD,IAAI,CAAC,QAAQ,CAAC,KAAK;gBAAE,MAAM,GAAG,CAAC;YAC/B,uCAAuC;YACvC,IAAI,OAAO,GAAG,CAAC,IAAI,IAAI,CAAC,WAAW;gBAAE,MAAM;YAC3C,MAAM,OAAO,GAAG,gBAAgB,CAC9B,OAAO,EACP,IAAI,CAAC,WAAW,EAChB,IAAI,CAAC,UAAU,EACf,QAAQ,CAAC,OAAO,EAChB,MAAM,CACP,CAAC;YACF,IAAI,OAAO,GAAG,CAAC;gBAAE,MAAM,KAAK,CAAC,OAAO,CAAC,CAAC;QACxC,CAAC;IACH,CAAC;IACD,MAAM,SAAS,CAAC;AAClB,CAAC"}

package/dist/_shared/integrations/understand-quickly.d.ts

@@ -0,0 +1,79 @@
+/**
+ * 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 `gitnexus-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 (`gitnexus/src/cli/publish.ts`)
+ * to keep this module free of Node-only imports — see the comment at
+ * the top of `gitnexus-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
+ */
+/**
+ * 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.
+ */
+export declare const 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`.
+ */
+export declare const UNDERSTAND_QUICKLY_EVENT_TYPE = "sync-entry";
+/** Environment variable that gates the dispatch. */
+export declare const UNDERSTAND_QUICKLY_TOKEN_ENV = "UNDERSTAND_QUICKLY_TOKEN";
+export interface UqDispatchPayload {
+    event_type: typeof UNDERSTAND_QUICKLY_EVENT_TYPE;
+    client_payload: {
+        /** `<owner>/<repo>` shape — must match the registered entry. */
+        id: string;
+    };
+}
+/**
+ * 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.
+ */
+export declare function buildUqDispatchPayload(id: string): UqDispatchPayload;
+/**
+ * `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.
+ */
+export declare function isValidOwnerRepo(id: string): boolean;
+/**
+ * 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".
+ */
+export declare function stripGitSuffix(input: string): string;
+/**
+ * Parse `owner/repo` out of a git remote URL. Mirrors the heuristic in
+ * `gitnexus/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
+ */
+export declare function parseOwnerRepoFromRemote(url: string | null | undefined): string | null;
+//# sourceMappingURL=understand-quickly.d.ts.map

package/dist/_shared/integrations/understand-quickly.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"understand-quickly.d.ts","sourceRoot":"","sources":["../../src/integrations/understand-quickly.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH;;;;GAIG;AACH,eAAO,MAAM,+BAA+B,2EAC8B,CAAC;AAE3E;;;GAGG;AACH,eAAO,MAAM,6BAA6B,eAAe,CAAC;AAE1D,oDAAoD;AACpD,eAAO,MAAM,4BAA4B,6BAA6B,CAAC;AAEvE,MAAM,WAAW,iBAAiB;IAChC,UAAU,EAAE,OAAO,6BAA6B,CAAC;IACjD,cAAc,EAAE;QACd,gEAAgE;QAChE,EAAE,EAAE,MAAM,CAAC;KACZ,CAAC;CACH;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,EAAE,EAAE,MAAM,GAAG,iBAAiB,CAYpE;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,gBAAgB,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAEpD;AAED;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAYpD;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,wBAAwB,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,GAAG,IAAI,CAsCtF"}

package/dist/_shared/integrations/understand-quickly.js

@@ -0,0 +1,139 @@
+/**
+ * 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 `gitnexus-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 (`gitnexus/src/cli/publish.ts`)
+ * to keep this module free of Node-only imports — see the comment at
+ * the top of `gitnexus-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
+ */
+/**
+ * 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.
+ */
+export const 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`.
+ */
+export const UNDERSTAND_QUICKLY_EVENT_TYPE = 'sync-entry';
+/** Environment variable that gates the dispatch. */
+export const 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.
+ */
+export 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: 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.
+ */
+export 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".
+ */
+export 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
+ * `gitnexus/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
+ */
+export 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;
+}
+//# sourceMappingURL=understand-quickly.js.map

package/dist/_shared/integrations/understand-quickly.js.map

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

package/dist/_shared/test-helpers.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Test-only helpers.
+ *
+ * Symbols here are reachable from `gitnexus-shared/test-helpers` so test
+ * suites can reset shared registries or exercise internal classifiers,
+ * but they are deliberately NOT re-exported from the main `gitnexus-shared`
+ * barrel. Production consumers should never import this module — calling
+ * `__resetBreakerRegistry__()` from a tool implementation would silently
+ * nuke every circuit breaker process-wide.
+ */
+export { __resetBreakerRegistry__ } from './integrations/circuit-breaker.js';
+export { classifyOutcome } from './integrations/resilient-fetch.js';
+//# sourceMappingURL=test-helpers.d.ts.map

package/dist/_shared/test-helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"test-helpers.d.ts","sourceRoot":"","sources":["../src/test-helpers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,wBAAwB,EAAE,MAAM,mCAAmC,CAAC;AAC7E,OAAO,EAAE,eAAe,EAAE,MAAM,mCAAmC,CAAC"}

package/dist/_shared/test-helpers.js

@@ -0,0 +1,13 @@
+/**
+ * Test-only helpers.
+ *
+ * Symbols here are reachable from `gitnexus-shared/test-helpers` so test
+ * suites can reset shared registries or exercise internal classifiers,
+ * but they are deliberately NOT re-exported from the main `gitnexus-shared`
+ * barrel. Production consumers should never import this module — calling
+ * `__resetBreakerRegistry__()` from a tool implementation would silently
+ * nuke every circuit breaker process-wide.
+ */
+export { __resetBreakerRegistry__ } from './integrations/circuit-breaker.js';
+export { classifyOutcome } from './integrations/resilient-fetch.js';
+//# sourceMappingURL=test-helpers.js.map

package/dist/_shared/test-helpers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"test-helpers.js","sourceRoot":"","sources":["../src/test-helpers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,wBAAwB,EAAE,MAAM,mCAAmC,CAAC;AAC7E,OAAO,EAAE,eAAe,EAAE,MAAM,mCAAmC,CAAC"}

package/dist/cli/index.js

@@ -106,6 +106,15 @@ program
     .command('augment <pattern>')
     .description('Augment a search pattern with knowledge graph context (used by hooks)')
     .action(createLazyAction(() => import('./augment.js'), 'augmentCommand'));
+program
+    .command('publish [path]')
+    .description('Notify the understand-quickly registry that this repo has a fresh GitNexus index. ' +
+    'Opt-in: requires UNDERSTAND_QUICKLY_TOKEN (fine-grained PAT with ' +
+    '`Repository dispatches: write` on looptech-ai/understand-quickly). ' +
+    'No-op without the token. See https://github.com/looptech-ai/understand-quickly.')
+    .option('--id <owner/repo>', 'Override the registry id (defaults to the origin remote)')
+    .option('--skip-git', 'Treat cwd as the repo root and skip parent git-root discovery')
+    .action(createLazyAction(() => import('./publish.js'), 'publishCommand'));
 // ─── Direct Tool Commands (no MCP overhead) ────────────────────────
 // These invoke LocalBackend directly for use in eval, scripts, and CI.
 program