ghagga-forge 3.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 JNZader & Gentleman Programming Community
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,3 @@
+# ghagga-forge
+
+`ghagga-forge` is GHAGGA's forge-agnostic port layer: the canonical, provider-neutral domain types and abstract ports (forge adapter, CI runner, credential provider, webhook codec, adapter registry) that the core review engine and the server talk to instead of any concrete forge SDK. It keeps GHAGGA decoupled from GitHub, GitLab, or Gitea specifics so the same review pipeline can target any forge. The package depends on `ghagga-core` in TYPE position only, and `ghagga-core` must never depend on it (R-AGNOSTIC).

package/dist/adapters/github/github-app-credential-provider.d.ts

@@ -0,0 +1,102 @@
+/**
+ * GitHubAppCredentialProvider — the REAL P2 {@link ForgeCredentialProvider} for
+ * the GitHub App installation-token flow (SDD forge-agnostic task 2.1).
+ *
+ * Replaces P1's `TemporaryGitHubTokenSource` (which minted a fresh token on every
+ * `getToken()` call, no cache). This provider delivers the R-TOKEN contract:
+ *
+ *   - TTL CACHE: a minted token is reused until `expiresAtMs - SKEW_SECONDS`.
+ *   - BUDGET VALIDITY: `getToken()` returns a token valid for >= `BUDGET_SECONDS`
+ *     of REMAINING life. If the cached token would expire within that budget, it
+ *     is re-minted PROACTIVELY (never "wait for a 401"). This is what makes the
+ *     ~11-min fetch+dispatch+poll phase reuse one token AND guarantees the
+ *     postback token outlives the postback.
+ *   - SINGLEFLIGHT: concurrent `getToken()` calls with no valid cached token
+ *     share ONE in-flight mint promise (no duplicate concurrent mints).
+ *   - 401/403 FORCE-REFRESH: {@link GitHubAppCredentialProvider.invalidate}
+ *     drops the cache so the next `getToken()` re-mints. The caller signals an
+ *     auth failure (401/403) by calling `invalidate()`.
+ *   - HARD-FAIL: if the mint POST fails HARD (non-401, e.g. 500/network), the
+ *     in-flight promise rejects and `getToken()` REJECTS — NO stale/empty token
+ *     is returned, so the job fails fast.
+ *
+ * DEPENDENCY INVERSION (R-AGNOSTIC): like the adapter, this class does NOT import
+ * `apps/server`. The real expiry-carrying mint is injected as
+ * {@link GitHubInstallationTokenMintWithExpiry}; the composition root in
+ * apps/server adapts `client.getInstallationToken` to also surface `expires_at`.
+ *
+ * DETERMINISTIC CLOCK: time is read through an injected `now()` (defaults to
+ * {@link Date.now}). `Date.now` is not otherwise controllable in tests; injecting
+ * it lets the fake-clock tests (task 2.4) drive TTL/budget/expiry decisions
+ * deterministically.
+ */
+import type { ForgeCredentialProvider } from '../../ports/credential-provider.js';
+import type { GitHubInstallationTokenMintWithExpiry } from './github-client-port.js';
+/**
+ * Early-refresh margin (seconds). The cached token is treated as expired this
+ * many seconds BEFORE its real `expiresAtMs`, absorbing clock skew between this
+ * process and GitHub so a token never gets USED in the moments around its true
+ * expiry. (Design Open Question resolved: a fixed value is enough for P1–P4.)
+ */
+export declare const SKEW_SECONDS = 60;
+/**
+ * Required remaining validity (seconds). `getToken()` guarantees the returned
+ * token has at least this much life left; otherwise it re-mints PROACTIVELY.
+ * This is the "token must OUTLIVE the postback" budget — sized so a token handed
+ * out just before the comment postback cannot expire mid-postback.
+ */
+export declare const BUDGET_SECONDS = 120;
+/** Construction options for {@link GitHubAppCredentialProvider}. */
+export interface GitHubAppCredentialProviderDeps {
+    /**
+     * Injected expiry-carrying installation-token mint. Real impl = the apps/server
+     * composition root adapting `client.getInstallationToken` to surface
+     * `expires_at`. MUST reject on a HARD failure (non-401) — the provider relies
+     * on that rejection to fail fast.
+     */
+    mint: GitHubInstallationTokenMintWithExpiry;
+    /** GitHub App installation id. */
+    installationId: number;
+    /** GitHub App id. */
+    appId: string;
+    /** GitHub App private key (PEM). */
+    privateKey: string;
+    /** Optional repository-id scoping for the minted token. */
+    repositoryIds?: number[];
+    /**
+     * Injected clock — epoch millis. Defaults to {@link Date.now}. Override in
+     * tests to make TTL/budget/expiry decisions deterministic.
+     */
+    now?: () => number;
+}
+/**
+ * TTL-cached, single-flight, budget-valid GitHub installation-token provider.
+ *
+ * @see {@link ForgeCredentialProvider} — the port it implements.
+ */
+export declare class GitHubAppCredentialProvider implements ForgeCredentialProvider {
+    #private;
+    constructor(deps: GitHubAppCredentialProviderDeps);
+    /**
+     * Resolve a budget-valid installation token.
+     *
+     * Returns the cached token when it still has >= `BUDGET_SECONDS` of life
+     * (minus `SKEW_SECONDS` margin). Otherwise mints a fresh one — coalescing
+     * concurrent callers onto a single in-flight mint. Rejects (no stale token) if
+     * the mint fails hard.
+     */
+    getToken(): Promise<string>;
+    /**
+     * Drop the cached token so the NEXT `getToken()` re-mints. The caller invokes
+     * this on a 401/403 auth failure (the token was revoked/rotated server-side
+     * before its advertised expiry).
+     *
+     * FIX 4 (in-flight fence): a mint that was ALREADY in flight when this is
+     * called will still RESOLVE (its awaiter gets that token), but it will NOT be
+     * re-cached — it belongs to a pre-invalidation generation and could be the very
+     * token that was just revoked. The next fresh `getToken()` therefore mints
+     * anew rather than reusing a possibly-revoked in-flight result.
+     */
+    invalidate(): void;
+}
+//# sourceMappingURL=github-app-credential-provider.d.ts.map

package/dist/adapters/github/github-app-credential-provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"github-app-credential-provider.d.ts","sourceRoot":"","sources":["../../../src/adapters/github/github-app-credential-provider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,oCAAoC,CAAC;AAClF,OAAO,KAAK,EACV,qCAAqC,EAEtC,MAAM,yBAAyB,CAAC;AAEjC;;;;;GAKG;AACH,eAAO,MAAM,YAAY,KAAK,CAAC;AAE/B;;;;;GAKG;AACH,eAAO,MAAM,cAAc,MAAM,CAAC;AAElC,oEAAoE;AACpE,MAAM,WAAW,+BAA+B;IAC9C;;;;;OAKG;IACH,IAAI,EAAE,qCAAqC,CAAC;IAC5C,kCAAkC;IAClC,cAAc,EAAE,MAAM,CAAC;IACvB,qBAAqB;IACrB,KAAK,EAAE,MAAM,CAAC;IACd,oCAAoC;IACpC,UAAU,EAAE,MAAM,CAAC;IACnB,2DAA2D;IAC3D,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IACzB;;;OAGG;IACH,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACpB;AAED;;;;GAIG;AACH,qBAAa,2BAA4B,YAAW,uBAAuB;;gBA4B7D,IAAI,EAAE,+BAA+B;IASjD;;;;;;;OAOG;IACG,QAAQ,IAAI,OAAO,CAAC,MAAM,CAAC;IAoDjC;;;;;;;;;;OAUG;IACH,UAAU,IAAI,IAAI;CAoBnB"}

package/dist/adapters/github/github-app-credential-provider.js

@@ -0,0 +1,166 @@
+/**
+ * GitHubAppCredentialProvider — the REAL P2 {@link ForgeCredentialProvider} for
+ * the GitHub App installation-token flow (SDD forge-agnostic task 2.1).
+ *
+ * Replaces P1's `TemporaryGitHubTokenSource` (which minted a fresh token on every
+ * `getToken()` call, no cache). This provider delivers the R-TOKEN contract:
+ *
+ *   - TTL CACHE: a minted token is reused until `expiresAtMs - SKEW_SECONDS`.
+ *   - BUDGET VALIDITY: `getToken()` returns a token valid for >= `BUDGET_SECONDS`
+ *     of REMAINING life. If the cached token would expire within that budget, it
+ *     is re-minted PROACTIVELY (never "wait for a 401"). This is what makes the
+ *     ~11-min fetch+dispatch+poll phase reuse one token AND guarantees the
+ *     postback token outlives the postback.
+ *   - SINGLEFLIGHT: concurrent `getToken()` calls with no valid cached token
+ *     share ONE in-flight mint promise (no duplicate concurrent mints).
+ *   - 401/403 FORCE-REFRESH: {@link GitHubAppCredentialProvider.invalidate}
+ *     drops the cache so the next `getToken()` re-mints. The caller signals an
+ *     auth failure (401/403) by calling `invalidate()`.
+ *   - HARD-FAIL: if the mint POST fails HARD (non-401, e.g. 500/network), the
+ *     in-flight promise rejects and `getToken()` REJECTS — NO stale/empty token
+ *     is returned, so the job fails fast.
+ *
+ * DEPENDENCY INVERSION (R-AGNOSTIC): like the adapter, this class does NOT import
+ * `apps/server`. The real expiry-carrying mint is injected as
+ * {@link GitHubInstallationTokenMintWithExpiry}; the composition root in
+ * apps/server adapts `client.getInstallationToken` to also surface `expires_at`.
+ *
+ * DETERMINISTIC CLOCK: time is read through an injected `now()` (defaults to
+ * {@link Date.now}). `Date.now` is not otherwise controllable in tests; injecting
+ * it lets the fake-clock tests (task 2.4) drive TTL/budget/expiry decisions
+ * deterministically.
+ */
+/**
+ * Early-refresh margin (seconds). The cached token is treated as expired this
+ * many seconds BEFORE its real `expiresAtMs`, absorbing clock skew between this
+ * process and GitHub so a token never gets USED in the moments around its true
+ * expiry. (Design Open Question resolved: a fixed value is enough for P1–P4.)
+ */
+export const SKEW_SECONDS = 60;
+/**
+ * Required remaining validity (seconds). `getToken()` guarantees the returned
+ * token has at least this much life left; otherwise it re-mints PROACTIVELY.
+ * This is the "token must OUTLIVE the postback" budget — sized so a token handed
+ * out just before the comment postback cannot expire mid-postback.
+ */
+export const BUDGET_SECONDS = 120;
+/**
+ * TTL-cached, single-flight, budget-valid GitHub installation-token provider.
+ *
+ * @see {@link ForgeCredentialProvider} — the port it implements.
+ */
+export class GitHubAppCredentialProvider {
+    #mint;
+    #installationId;
+    #appId;
+    #privateKey;
+    #repositoryIds;
+    #now;
+    /** The last successfully minted token + its expiry, or null when uncached. */
+    #cached = null;
+    /**
+     * The in-flight mint promise, or null when no mint is running. SINGLEFLIGHT:
+     * concurrent callers that find no valid cached token await THIS shared promise
+     * instead of each starting their own mint.
+     */
+    #inFlight = null;
+    /**
+     * Monotonic generation counter, bumped on every {@link invalidate}. FIX 4
+     * (in-flight fence): a mint that STARTED before an `invalidate()` must NOT
+     * repopulate the cache when it resolves afterwards — its token belongs to a
+     * pre-invalidation generation (it may be the very token that just got revoked).
+     * Each `getToken` snapshots the generation at mint-start; on resolution it
+     * caches ONLY if the snapshot still matches the current generation.
+     */
+    #generation = 0;
+    constructor(deps) {
+        this.#mint = deps.mint;
+        this.#installationId = deps.installationId;
+        this.#appId = deps.appId;
+        this.#privateKey = deps.privateKey;
+        this.#repositoryIds = deps.repositoryIds;
+        this.#now = deps.now ?? Date.now;
+    }
+    /**
+     * Resolve a budget-valid installation token.
+     *
+     * Returns the cached token when it still has >= `BUDGET_SECONDS` of life
+     * (minus `SKEW_SECONDS` margin). Otherwise mints a fresh one — coalescing
+     * concurrent callers onto a single in-flight mint. Rejects (no stale token) if
+     * the mint fails hard.
+     */
+    async getToken() {
+        const cached = this.#cached;
+        if (cached !== null && this.#isUsable(cached)) {
+            return cached.token;
+        }
+        // SINGLEFLIGHT: if a mint is already running, await it instead of starting
+        // a second one. All concurrent callers share the same promise + result.
+        if (this.#inFlight !== null) {
+            const minted = await this.#inFlight;
+            return minted.token;
+        }
+        // FIX 4: snapshot the generation at mint-START. If invalidate() bumps the
+        // generation while this mint is in flight, the resolution below will see a
+        // mismatch and DISCARD the result (a token from a pre-invalidation generation
+        // must not be re-cached). The token is still RETURNED to this caller (it is a
+        // fresh acquisition for them); it just isn't promoted to the shared cache.
+        const startGeneration = this.#generation;
+        const inFlight = this.#mint(this.#installationId, this.#appId, this.#privateKey, this.#repositoryIds && this.#repositoryIds.length > 0
+            ? { repositoryIds: this.#repositoryIds }
+            : undefined);
+        this.#inFlight = inFlight;
+        try {
+            const minted = await inFlight;
+            // HARD-FAIL safety: only cache on success. On rejection we fall through to
+            // the finally + the throw below — the cache is NEVER populated with a
+            // stale/empty token, so the job fails fast.
+            //
+            // FIX 4 fence: only cache if no invalidate() happened during this mint.
+            // Otherwise discard (do not re-cache) — but still return the token to the
+            // caller who awaited this specific mint.
+            if (this.#generation === startGeneration) {
+                this.#cached = minted;
+            }
+            return minted.token;
+        }
+        finally {
+            // Clear the in-flight slot whether the mint resolved or rejected, so a
+            // failed mint does not wedge every future caller onto a rejected promise.
+            if (this.#inFlight === inFlight) {
+                this.#inFlight = null;
+            }
+        }
+    }
+    /**
+     * Drop the cached token so the NEXT `getToken()` re-mints. The caller invokes
+     * this on a 401/403 auth failure (the token was revoked/rotated server-side
+     * before its advertised expiry).
+     *
+     * FIX 4 (in-flight fence): a mint that was ALREADY in flight when this is
+     * called will still RESOLVE (its awaiter gets that token), but it will NOT be
+     * re-cached — it belongs to a pre-invalidation generation and could be the very
+     * token that was just revoked. The next fresh `getToken()` therefore mints
+     * anew rather than reusing a possibly-revoked in-flight result.
+     */
+    invalidate() {
+        this.#cached = null;
+        // FIX 4: bump the generation so any mint already IN FLIGHT (started before
+        // this call) will NOT repopulate the cache when it resolves — its token
+        // belongs to a now-superseded generation (possibly the just-revoked token).
+        this.#generation += 1;
+    }
+    /**
+     * A cached token is usable when its remaining life (with the skew margin
+     * applied) still covers the required budget. i.e.
+     *   expiresAtMs - SKEW*1000  >=  now + BUDGET*1000
+     * Equivalently: the skew-adjusted expiry is at least `BUDGET_SECONDS` in the
+     * future. Otherwise it must be re-minted PROACTIVELY (not via a 401).
+     */
+    #isUsable(token) {
+        const skewAdjustedExpiry = token.expiresAtMs - SKEW_SECONDS * 1000;
+        const budgetDeadline = this.#now() + BUDGET_SECONDS * 1000;
+        return skewAdjustedExpiry >= budgetDeadline;
+    }
+}
+//# sourceMappingURL=github-app-credential-provider.js.map

package/dist/adapters/github/github-app-credential-provider.js.map

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

package/dist/adapters/github/github-client-port.d.ts

@@ -0,0 +1,92 @@
+/**
+ * GitHub client PORT (dependency inversion seam for the GitHub adapter).
+ *
+ * R-AGNOSTIC / boundary rule: `packages/forge` MUST NOT import `apps/server`
+ * (the boundary lint forbids it). The concrete GitHub HTTP client lives in
+ * `apps/server/src/github/client.ts`. To wrap it WITHOUT importing it, the
+ * adapter declares — here — the exact function-set it depends on, and the caller
+ * (review.ts, task 1.4) injects the real `client.ts` functions at construction.
+ *
+ * This interface mirrors the SIGNATURES of the client.ts functions the adapter
+ * folds over (owner/repo/token positional style). It is intentionally
+ * GitHub-native (numeric ids, GitHub-shaped returns): the adapter is the layer
+ * that maps GitHub-native shapes ↔ canonical forge types. Comment ids cross THIS
+ * seam as PLAIN numbers (GitHub-native) — boxing into `CommentId` happens
+ * review.ts-LOCAL in 1.4, not here.
+ *
+ * Graph return types are kept structural (`unknown`-validated downstream is done
+ * inside client.ts itself) so this port does NOT need a value/type import of
+ * core; client.ts already returns the validated `DependencyGraph | null` /
+ * `GraphMetadata | null`. We re-state those as type-only imports from core,
+ * which the boundary lint explicitly permits (`import type` from core).
+ */
+import type { DependencyGraph, GraphMetadata } from 'ghagga-core';
+/** Reaction emojis the underlying GitHub client accepts. */
+export type GitHubReactionContent = '+1' | '-1' | 'laugh' | 'confused' | 'heart' | 'hooray' | 'rocket' | 'eyes';
+/**
+ * The set of GitHub client functions the {@link GitHubForgeAdapter} depends on.
+ *
+ * Each member matches the corresponding `apps/server/src/github/client.ts`
+ * export by signature. The adapter receives an implementation of this port via
+ * its constructor (dependency inversion) so the forge package never imports the
+ * server.
+ */
+export interface GitHubClientPort {
+    /** Fetch the unified diff text for a PR. */
+    fetchPRDiff(owner: string, repo: string, prNumber: number, token: string): Promise<string>;
+    /** Fetch PR details (head SHA, base branch, author login). */
+    fetchPRDetails(owner: string, repo: string, prNumber: number, token: string): Promise<{
+        headSha: string;
+        baseBranch: string;
+        prAuthor: string;
+    }>;
+    /** Fetch the list of changed file paths for a PR. */
+    getPRFileList(owner: string, repo: string, prNumber: number, token: string): Promise<string[]>;
+    /** Fetch commit messages for a PR. */
+    getPRCommitMessages(owner: string, repo: string, prNumber: number, token: string): Promise<string[]>;
+    /** Post a fresh comment; returns the GitHub-native numeric id. */
+    postComment(owner: string, repo: string, prNumber: number, body: string, token: string): Promise<{
+        id: number;
+    }>;
+    /** Find existing GHAGGA comments; returns latest + stale numeric ids, or null. */
+    findExistingComment(owner: string, repo: string, prNumber: number, token: string): Promise<{
+        latestId: number;
+        staleIds: number[];
+    } | null>;
+    /** Delete a comment by its GitHub-native numeric id. */
+    deleteComment(owner: string, repo: string, commentId: number, token: string): Promise<void>;
+    /** Update a comment in place by its GitHub-native numeric id. */
+    updateComment(owner: string, repo: string, commentId: number, body: string, token: string): Promise<void>;
+    /** Add a reaction to an issue comment (best-effort in client.ts). */
+    addCommentReaction(owner: string, repo: string, commentId: number, reaction: GitHubReactionContent, token: string): Promise<void>;
+    /** Read the dependency graph from the `ghagga/graph` orphan branch, or null. */
+    fetchGraphFromBranch(owner: string, repo: string, token: string): Promise<DependencyGraph | null>;
+    /** Read graph metadata from the `ghagga/graph` orphan branch, or null. */
+    fetchGraphMetadata(owner: string, repo: string, token: string): Promise<GraphMetadata | null>;
+}
+/**
+ * A minted installation token plus its absolute expiry.
+ *
+ * `expiresAtMs` is the token's expiry as an epoch-millis timestamp (comparable to
+ * `Date.now()`), derived by the composition root from the GitHub access-token
+ * response `expires_at` (an ISO-8601 string the REST API already returns).
+ */
+export interface MintedInstallationToken {
+    /** The installation access token string. */
+    token: string;
+    /** Absolute expiry, epoch millis (comparable to {@link Date.now}). */
+    expiresAtMs: number;
+}
+/**
+ * Mints a GitHub installation access token AND reports its expiry (P2).
+ *
+ * This is the expiry-carrying mint the {@link GitHubAppCredentialProvider} TTL
+ * cache requires. The underlying `client.getInstallationToken` returns ONLY the
+ * token string today (it discards the GitHub `expires_at`); the composition root
+ * (apps/server) adapts it to ALSO surface the expiry so the forge package can
+ * cache without importing apps/server (dependency inversion, R-AGNOSTIC).
+ */
+export type GitHubInstallationTokenMintWithExpiry = (installationId: number, appId: string, privateKey: string, options?: {
+    repositoryIds?: number[];
+}) => Promise<MintedInstallationToken>;
+//# sourceMappingURL=github-client-port.d.ts.map

package/dist/adapters/github/github-client-port.d.ts.map

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

package/dist/adapters/github/github-client-port.js

@@ -0,0 +1,24 @@
+/**
+ * GitHub client PORT (dependency inversion seam for the GitHub adapter).
+ *
+ * R-AGNOSTIC / boundary rule: `packages/forge` MUST NOT import `apps/server`
+ * (the boundary lint forbids it). The concrete GitHub HTTP client lives in
+ * `apps/server/src/github/client.ts`. To wrap it WITHOUT importing it, the
+ * adapter declares — here — the exact function-set it depends on, and the caller
+ * (review.ts, task 1.4) injects the real `client.ts` functions at construction.
+ *
+ * This interface mirrors the SIGNATURES of the client.ts functions the adapter
+ * folds over (owner/repo/token positional style). It is intentionally
+ * GitHub-native (numeric ids, GitHub-shaped returns): the adapter is the layer
+ * that maps GitHub-native shapes ↔ canonical forge types. Comment ids cross THIS
+ * seam as PLAIN numbers (GitHub-native) — boxing into `CommentId` happens
+ * review.ts-LOCAL in 1.4, not here.
+ *
+ * Graph return types are kept structural (`unknown`-validated downstream is done
+ * inside client.ts itself) so this port does NOT need a value/type import of
+ * core; client.ts already returns the validated `DependencyGraph | null` /
+ * `GraphMetadata | null`. We re-state those as type-only imports from core,
+ * which the boundary lint explicitly permits (`import type` from core).
+ */
+export {};
+//# sourceMappingURL=github-client-port.js.map

package/dist/adapters/github/github-client-port.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"github-client-port.js","sourceRoot":"","sources":["../../../src/adapters/github/github-client-port.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG"}

package/dist/adapters/github/github-forge-adapter.d.ts

@@ -0,0 +1,105 @@
+/**
+ * GitHubForgeAdapter — wraps the GitHub HTTP client behind the forge-agnostic
+ * {@link ForgeAdapterBase} + {@link ReactionCapable} + {@link GraphReadCapable}
+ * surfaces.
+ *
+ * DEPENDENCY INVERSION (boundary rule R-AGNOSTIC):
+ * `packages/forge` MUST NOT import `apps/server`. The concrete GitHub client
+ * lives in `apps/server/src/github/client.ts`. So this adapter NEVER imports
+ * that client directly — it depends on the injected {@link GitHubClientPort}
+ * (declared inside the forge package). Task 1.4 (review.ts) constructs the
+ * adapter passing the real `client.ts` functions as the port implementation:
+ *
+ *   new GitHubForgeAdapter({ client, token, owner, repo })
+ *
+ * CAPABILITIES: reactions ✅, graphRead ✅ (both methods co-present),
+ * inlineComments ❌ (GitHub inline review is deferred — no `publishInline`).
+ * The `capabilities` field is a HINT only (R-CAPABILITY): callers guard optional
+ * methods by method-presence, never by these flags.
+ *
+ * COMMENT IDs: this adapter returns PLAIN GitHub-native numeric ids (number /
+ * number[]). Boxing into {@link CommentId} happens caller-LOCAL in review.ts.
+ * The adapter accepts a boxed {@link CommentId} in `addReaction` (port contract)
+ * and unwraps `raw` to the GitHub-native number internally.
+ */
+import type { DependencyGraph, GraphMetadata } from 'ghagga-core';
+import type { ForgeAdapterBase, GraphReadCapable, ReactionCapable, ReactionKind } from '../../ports/forge-adapter.js';
+import { REACTION_KIND } from '../../ports/forge-adapter.js';
+import type { ChangedFile, ChangeRequest, ChangeRequestRef, CommentId, CommentMarker, Commit, ForgeCapabilities, RepoRef, UnifiedDiff, UpsertSummaryResult } from '../../types.js';
+import type { GitHubClientPort } from './github-client-port.js';
+/** Construction options for {@link GitHubForgeAdapter}. */
+export interface GitHubForgeAdapterDeps {
+    /** Injected GitHub client function-set (real impl = apps/server client.ts). */
+    client: GitHubClientPort;
+    /** Installation access token used for all calls. */
+    token: string;
+    /** Repository owner (login). */
+    owner: string;
+    /** Repository name. */
+    repo: string;
+}
+/**
+ * GitHub implementation of the forge adapter.
+ *
+ * Implements the mandatory base plus the reaction and graph-read capabilities.
+ * Deliberately does NOT implement {@link InlineCapable} (GitHub inline review
+ * deferred), so `publishInline` is ABSENT — callers guarding by method-presence
+ * will skip inline publishing cleanly.
+ */
+export declare class GitHubForgeAdapter implements ForgeAdapterBase, ReactionCapable, GraphReadCapable {
+    #private;
+    readonly capabilities: ForgeCapabilities;
+    constructor(deps: GitHubForgeAdapterDeps);
+    fetchDiff(ref: ChangeRequestRef): Promise<UnifiedDiff>;
+    fetchChangeRequest(ref: ChangeRequestRef): Promise<ChangeRequest>;
+    fetchFileList(ref: ChangeRequestRef): Promise<ChangedFile[]>;
+    fetchCommits(ref: ChangeRequestRef): Promise<Commit[]>;
+    /**
+     * Idempotently upsert the single GHAGGA summary comment.
+     *
+     * Behavior (preserves the review.ts baseline exactly):
+     * 1. find existing GHAGGA comments (latest + stale).
+     * 2. delete ALL of them in the order `[latestId, ...staleIds]` — BEST-EFFORT:
+     *    each delete is wrapped in try/catch so BOTH 404 (already gone) AND any
+     *    non-404 failure are tolerated and do NOT block the repost. Only ids that
+     *    actually deleted (no throw) are reported in `deleted`.
+     * 3. post a FRESH comment at the bottom — this is the ONLY failure that
+     *    propagates (a failed post means no summary exists, which is fatal).
+     *
+     * Returns GitHub-native numeric ids (boxing happens caller-local).
+     *
+     * NOTE: `marker` is accepted for the port contract but is NOT threaded into
+     * the client. The GitHub adapter currently matches the FIXED
+     * `REVIEW_COMMENT_MARKER` (`<!-- ghagga-review -->`) hard-coded inside
+     * client.findExistingComment (a "stale ghagga comment" = any comment whose body
+     * contains that marker; author/bot status is NOT inspected). This is
+     * baseline-faithful: threading `marker` into
+     * GitHubClientPort.findExistingComment is DEFERRED (would change the port
+     * signature). Consequently, if review.ts (1.4) passes a `marker`, it MUST equal
+     * the existing `REVIEW_COMMENT_MARKER` — any other value is silently ignored.
+     */
+    upsertSummaryComment(ref: ChangeRequestRef, body: string, _marker: CommentMarker): Promise<UpsertSummaryResult>;
+    /**
+     * Add a reaction to a comment (R-5).
+     *
+     * CRITICAL: the trigger-comment reaction MUST live in the adapter — it was
+     * accidentally dropped once before. It is preserved here, wrapping
+     * client.addCommentReaction (which is itself best-effort / non-throwing).
+     */
+    addReaction(commentId: CommentId, reaction: ReactionKind): Promise<void>;
+    /**
+     * Read the dependency graph from the `ghagga/graph` orphan branch.
+     *
+     * The orphan-branch ref (`?ref=ghagga/graph`), the 404→null behavior, and the
+     * typed JSON validation all live INSIDE client.fetchGraphFromBranch — this
+     * adapter preserves them by delegating, returning `null` for "no graph".
+     */
+    fetchGraph(_repo: RepoRef): Promise<DependencyGraph | null>;
+    /**
+     * Read graph metadata from the `ghagga/graph` orphan branch (orphan-ref +
+     * 404→null + validation handled inside client.fetchGraphMetadata).
+     */
+    fetchGraphMetadata(_repo: RepoRef): Promise<GraphMetadata | null>;
+}
+export { REACTION_KIND };
+//# sourceMappingURL=github-forge-adapter.d.ts.map

package/dist/adapters/github/github-forge-adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"github-forge-adapter.d.ts","sourceRoot":"","sources":["../../../src/adapters/github/github-forge-adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAElE,OAAO,KAAK,EACV,gBAAgB,EAChB,gBAAgB,EAChB,eAAe,EACf,YAAY,EACb,MAAM,8BAA8B,CAAC;AACtC,OAAO,EAAE,aAAa,EAAE,MAAM,8BAA8B,CAAC;AAC7D,OAAO,KAAK,EACV,WAAW,EACX,aAAa,EACb,gBAAgB,EAChB,SAAS,EACT,aAAa,EACb,MAAM,EACN,iBAAiB,EACjB,OAAO,EACP,WAAW,EACX,mBAAmB,EACpB,MAAM,gBAAgB,CAAC;AAExB,OAAO,KAAK,EAAE,gBAAgB,EAAyB,MAAM,yBAAyB,CAAC;AAEvF,2DAA2D;AAC3D,MAAM,WAAW,sBAAsB;IACrC,+EAA+E;IAC/E,MAAM,EAAE,gBAAgB,CAAC;IACzB,oDAAoD;IACpD,KAAK,EAAE,MAAM,CAAC;IACd,gCAAgC;IAChC,KAAK,EAAE,MAAM,CAAC;IACd,uBAAuB;IACvB,IAAI,EAAE,MAAM,CAAC;CACd;AA4BD;;;;;;;GAOG;AACH,qBAAa,kBAAmB,YAAW,gBAAgB,EAAE,eAAe,EAAE,gBAAgB;;IAC5F,QAAQ,CAAC,YAAY,EAAE,iBAAiB,CAItC;gBAOU,IAAI,EAAE,sBAAsB;IAqClC,SAAS,CAAC,GAAG,EAAE,gBAAgB,GAAG,OAAO,CAAC,WAAW,CAAC;IAOtD,kBAAkB,CAAC,GAAG,EAAE,gBAAgB,GAAG,OAAO,CAAC,aAAa,CAAC;IAcjE,aAAa,CAAC,GAAG,EAAE,gBAAgB,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;IAY5D,YAAY,CAAC,GAAG,EAAE,gBAAgB,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAa5D;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACG,oBAAoB,CACxB,GAAG,EAAE,gBAAgB,EACrB,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,aAAa,GACrB,OAAO,CAAC,mBAAmB,CAAC;IAiD/B;;;;;;OAMG;IACG,WAAW,CAAC,SAAS,EAAE,SAAS,EAAE,QAAQ,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC;IAc9E;;;;;;OAMG;IACG,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC;IAIjE;;;OAGG;IACG,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC;CAGxE;AAGD,OAAO,EAAE,aAAa,EAAE,CAAC"}