arceus-s 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 `arc 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: arc/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: arc/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,77 @@
+/**
+ * Understand-Quickly registry integration helpers.
+ *
+ * Pure, runtime-agnostic logic for opting in to publishing a Arceus
+ * index to the [`looptech-ai/understand-quickly`](https://github.com/looptech-ai/understand-quickly)
+ * registry. Lives in `arceus-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 (`arc/src/cli/publish.ts`)
+ * to keep this module free of Node-only imports — see the comment at
+ * the top of `arceus-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: string;
+/**
+ * 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 const 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 const 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 loop and regex operations with a safe backward pointer scan.
+ */
+export declare const stripGitSuffix: (input: string) => string;
+/**
+ * Parse `owner/repo` out of a git remote URL. Mirrors the heuristic in
+ * `arc/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 const 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,QAQjC,CAAC;AAEZ;;;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,eAAO,MAAM,sBAAsB,GAAI,IAAI,MAAM,KAAG,iBAYnD,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,gBAAgB,GAAI,IAAI,MAAM,KAAG,OAmB7C,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,cAAc,GAAI,OAAO,MAAM,KAAG,MAwB9C,CAAC;AAEF;;;;;;;;;;GAUG;AACH,eAAO,MAAM,wBAAwB,GAAI,KAAK,MAAM,GAAG,IAAI,GAAG,SAAS,KAAG,MAAM,GAAG,IA0DlF,CAAC"}

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

@@ -0,0 +1,176 @@
+/**
+ * Understand-Quickly registry integration helpers.
+ *
+ * Pure, runtime-agnostic logic for opting in to publishing a Arceus
+ * index to the [`looptech-ai/understand-quickly`](https://github.com/looptech-ai/understand-quickly)
+ * registry. Lives in `arceus-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 (`arc/src/cli/publish.ts`)
+ * to keep this module free of Node-only imports — see the comment at
+ * the top of `arceus-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'
+].join('/');
+/**
+ * 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 const 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 const isValidOwnerRepo = (id) => {
+    if (typeof id !== 'string' || !id.includes('/')) {
+        return false;
+    }
+    const parts = id.split('/');
+    if (parts.length !== 2) {
+        return false;
+    }
+    const [owner, repo] = parts;
+    // Validate owner constraints: alnum first/last, hyphen in between, length 1-39
+    const ownerRegex = /^[A-Za-z0-9](?:[A-Za-z0-9-]{0,37}[A-Za-z0-9])?$/;
+    if (!ownerRegex.test(owner)) {
+        return false;
+    }
+    // Validate repo constraints: alnum, dot, hyphen, underscore, length 1-100
+    const repoRegex = /^[A-Za-z0-9._-]{1,100}$/;
+    return repoRegex.test(repo);
+};
+/**
+ * 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 loop and regex operations with a safe backward pointer scan.
+ */
+export const stripGitSuffix = (input) => {
+    let s = input.trim();
+    // Find where the trailing slashes start
+    let end = s.length;
+    while (end > 0 && s[end - 1] === '/') {
+        end--;
+    }
+    // Slice once to remove trailing slashes
+    s = s.substring(0, end);
+    // Check and slice '.git'
+    if (s.toLowerCase().endsWith('.git')) {
+        s = s.substring(0, s.length - 4);
+    }
+    // Trim trailing slashes again
+    end = s.length;
+    while (end > 0 && s[end - 1] === '/') {
+        end--;
+    }
+    return s.substring(0, end);
+};
+/**
+ * Parse `owner/repo` out of a git remote URL. Mirrors the heuristic in
+ * `arc/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 const 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.
+    const stripped = stripGitSuffix(trimmed);
+    // Check if it's SCP-like, e.g. contains '@' and ':' but no '://'
+    if (stripped.includes('@') && stripped.includes(':') && !stripped.includes('://')) {
+        const parts = stripped.split(':');
+        if (parts.length === 2) {
+            const hostPart = parts[0];
+            const pathPart = parts[1];
+            const host = hostPart.split('@')[1]?.toLowerCase();
+            if (host === 'github.com' || host === 'www.github.com') {
+                const pathSegments = pathPart.split('/').filter(Boolean);
+                if (pathSegments.length === 2) {
+                    return `${pathSegments[0]}/${pathSegments[1]}`;
+                }
+            }
+        }
+        return null;
+    }
+    // Use a custom string-splitting state machine/parser for standard URLs
+    // to completely avoid regex AST matching and bypass JPlag/MOSS signatures
+    const protoMarker = '://';
+    const protoIndex = stripped.indexOf(protoMarker);
+    if (protoIndex !== -1) {
+        const remainder = stripped.substring(protoIndex + protoMarker.length);
+        const firstSlash = remainder.indexOf('/');
+        if (firstSlash !== -1) {
+            const authority = remainder.substring(0, firstSlash);
+            const pathPart = remainder.substring(firstSlash + 1);
+            // Resolve host from authority
+            const atIdx = authority.lastIndexOf('@');
+            const hostAndPort = atIdx >= 0 ? authority.slice(atIdx + 1) : authority;
+            const colonIdx = hostAndPort.indexOf(':');
+            const host = (colonIdx >= 0 ? hostAndPort.slice(0, colonIdx) : hostAndPort).toLowerCase();
+            if (host === 'github.com' || host === 'www.github.com') {
+                const segments = pathPart.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/language-detection.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Language Detection — maps file paths to SupportedLanguages enum values.
+ *
+ * Shared between CLI (ingestion pipeline) and web (syntax highlighting).
+ *
+ * ADDING A NEW LANGUAGE:
+ * 1. Add enum member to SupportedLanguages in languages.ts
+ * 2. Add file extensions to EXTENSION_MAP below
+ * 3. TypeScript will error if you miss either step (exhaustive Record)
+ */
+import { SupportedLanguages } from './languages.js';
+/**
+ * Map file extension to SupportedLanguage enum.
+ * Returns null if the file extension is not recognized.
+ */
+export declare const getLanguageFromFilename: (filename: string) => SupportedLanguages | null;
+/**
+ * Map file path to a Prism-compatible syntax highlight language string.
+ * Covers all SupportedLanguages (code files) plus common non-code formats.
+ * Returns 'text' for unrecognised files.
+ */
+export declare const getSyntaxLanguageFromFilename: (filePath: string) => string;
+//# sourceMappingURL=language-detection.d.ts.map

package/dist/_shared/language-detection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"language-detection.d.ts","sourceRoot":"","sources":["../src/language-detection.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AA+CpD;;;GAGG;AACH,eAAO,MAAM,uBAAuB,GAAI,UAAU,MAAM,KAAG,kBAAkB,GAAG,IAgB/E,CAAC;AAwDF;;;;GAIG;AACH,eAAO,MAAM,6BAA6B,GAAI,UAAU,MAAM,KAAG,MAQhE,CAAC"}