ghagga-forge 3.1.0

package/dist/adapters/github/github-forge-adapter.js

@@ -0,0 +1,225 @@
+/**
+ * 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 { ForgeAuthError, getErrorStatus } from '../../errors.js';
+import { REACTION_KIND } from '../../ports/forge-adapter.js';
+import { ACTOR_KIND } from '../../types.js';
+/** Maps a canonical {@link ReactionKind} to the GitHub reaction content string. */
+function toGitHubReaction(reaction) {
+    // ReactionKind values are already GitHub-native strings ('+1','-1','eyes',
+    // 'rocket','confused'); this cast is the single sanctioned bridge point.
+    return reaction;
+}
+/**
+ * Extract the GitHub-native numeric comment id from a boxed {@link CommentId}.
+ * `raw` is `string | number`; GitHub comment ids are numeric.
+ *
+ * Guards against a malformed/non-GitHub id silently coercing to `NaN` (which
+ * would produce a `…/comments/NaN` URL). Throws a clear {@link TypeError} unless
+ * the result is a safe integer.
+ */
+function toNativeCommentId(commentId) {
+    const { raw } = commentId;
+    const native = typeof raw === 'number' ? raw : Number(raw);
+    if (!Number.isSafeInteger(native)) {
+        throw new TypeError(`GitHubForgeAdapter: comment id is not a safe integer (kind=${commentId.kind}, raw=${String(raw)})`);
+    }
+    return native;
+}
+/**
+ * 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 class GitHubForgeAdapter {
+    capabilities = {
+        reactions: true,
+        inlineComments: false,
+        graphRead: true,
+    };
+    #client;
+    #token;
+    #owner;
+    #repo;
+    constructor(deps) {
+        this.#client = deps.client;
+        this.#token = deps.token;
+        this.#owner = deps.owner;
+        this.#repo = deps.repo;
+    }
+    /**
+     * Run a client call, reclassifying a 401/403 failure as a {@link ForgeAuthError}.
+     *
+     * This is the SINGLE point where a GitHub auth failure (the token was rejected
+     * server-side) becomes the typed signal the worker catches to drive the in-job
+     * re-mint + retry (P2 401-recovery). NON-auth failures are rethrown UNCHANGED
+     * (not reclassified) so retry logic only fires for genuine auth failures.
+     *
+     * The status is read off the thrown error's `status` field (the GitHub client
+     * tags its errors with `GitHubApiError.status`). Errors with no usable status
+     * pass through untouched.
+     */
+    async #mapAuth(call) {
+        try {
+            return await call();
+        }
+        catch (error) {
+            const status = getErrorStatus(error);
+            if (status === 401 || status === 403) {
+                throw new ForgeAuthError(status, error instanceof Error ? error.message : `Forge auth failure (HTTP ${status})`, { cause: error });
+            }
+            throw error;
+        }
+    }
+    // ─── Base: reads ───────────────────────────────────────────────
+    async fetchDiff(ref) {
+        const text = await this.#mapAuth(() => this.#client.fetchPRDiff(this.#owner, this.#repo, ref.iid, this.#token));
+        return { text };
+    }
+    async fetchChangeRequest(ref) {
+        const details = await this.#mapAuth(() => this.#client.fetchPRDetails(this.#owner, this.#repo, ref.iid, this.#token));
+        return {
+            ref,
+            headSha: details.headSha,
+            baseBranch: details.baseBranch,
+            // GitHub PR author kind is not exposed by fetchPRDetails; default USER.
+            // (Bot detection, when needed, is the caller's concern via login suffix.)
+            author: { login: details.prAuthor, kind: ACTOR_KIND.USER },
+        };
+    }
+    async fetchFileList(ref) {
+        // client.getPRFileList returns bare paths; the GitHub PR file-list endpoint
+        // wrapper does NOT expose changeKind/additions/deletions, so those optional
+        // ChangedFile fields are OMITTED (honest absence) rather than fabricated as
+        // zeros. The caller flattens via project.ts (toFileList) which only consumes
+        // `path`.
+        const paths = await this.#mapAuth(() => this.#client.getPRFileList(this.#owner, this.#repo, ref.iid, this.#token));
+        return paths.map((path) => ({ path }));
+    }
+    async fetchCommits(ref) {
+        // client.getPRCommitMessages returns only messages; the GitHub PR commit-list
+        // endpoint wrapper does NOT expose sha/author, so those optional Commit fields
+        // are OMITTED (honest absence) rather than fabricated as empty strings. The
+        // caller flattens via toCommitMessages which only consumes `message`.
+        const messages = await this.#mapAuth(() => this.#client.getPRCommitMessages(this.#owner, this.#repo, ref.iid, this.#token));
+        return messages.map((message) => ({ message }));
+    }
+    // ─── Base: upsert summary comment (fold post/find/delete → 1) ──
+    /**
+     * 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.
+     */
+    async upsertSummaryComment(ref, body, _marker) {
+        const existing = await this.#mapAuth(() => this.#client.findExistingComment(this.#owner, this.#repo, ref.iid, this.#token));
+        const deleted = [];
+        if (existing) {
+            // Preserve baseline delete-order: latest FIRST, then stale duplicates.
+            const allIds = [existing.latestId, ...existing.staleIds];
+            for (const commentId of allIds) {
+                try {
+                    await this.#client.deleteComment(this.#owner, this.#repo, commentId, this.#token);
+                    deleted.push(commentId);
+                }
+                catch {
+                    // Best-effort: tolerate BOTH 404 and non-404 delete failures. A stale
+                    // comment that cannot be deleted must NOT block the fresh repost.
+                    //
+                    // REALITY NOTE: the real client.ts deleteComment is fire-and-forget
+                    // (it does NOT check response.ok and never throws), so in production
+                    // this catch is defensive belt-and-suspenders and `deleted[]` reflects
+                    // attempted-and-not-thrown deletes. The catch only triggers under a
+                    // test double / future client that does throw.
+                }
+            }
+        }
+        // Always post a fresh comment at the bottom. This is the ONLY error that
+        // propagates — without it there would be no summary at all. A 401/403 here is
+        // reclassified to ForgeAuthError so the worker can re-mint + retry (P2).
+        const posted = await this.#mapAuth(() => this.#client.postComment(this.#owner, this.#repo, ref.iid, body, this.#token));
+        // Robustness guard: the real client.postComment returns `{ id }` or throws,
+        // so a missing id is a contract violation (e.g. a mis-shaped test double),
+        // never a live path. Fail loudly here rather than silently boxing
+        // `undefined` → the meaningless CommentId `{ kind:'github', raw:'undefined' }`
+        // downstream.
+        if (posted?.id == null) {
+            throw new TypeError('GitHubForgeAdapter.upsertSummaryComment: postComment returned no id (expected { id: number })');
+        }
+        return { created: posted.id, deleted };
+    }
+    // ─── ReactionCapable ───────────────────────────────────────────
+    /**
+     * 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).
+     */
+    async addReaction(commentId, reaction) {
+        await this.#mapAuth(() => this.#client.addCommentReaction(this.#owner, this.#repo, toNativeCommentId(commentId), toGitHubReaction(reaction), this.#token));
+    }
+    // ─── GraphReadCapable (both methods co-present) ─────────────────
+    /**
+     * 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".
+     */
+    async fetchGraph(_repo) {
+        return this.#client.fetchGraphFromBranch(this.#owner, this.#repo, this.#token);
+    }
+    /**
+     * Read graph metadata from the `ghagga/graph` orphan branch (orphan-ref +
+     * 404→null + validation handled inside client.fetchGraphMetadata).
+     */
+    async fetchGraphMetadata(_repo) {
+        return this.#client.fetchGraphMetadata(this.#owner, this.#repo, this.#token);
+    }
+}
+// Re-export so test files and 1.4 can reference the reaction-kind set succinctly.
+export { REACTION_KIND };
+//# sourceMappingURL=github-forge-adapter.js.map

package/dist/adapters/github/github-forge-adapter.js.map

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

package/dist/adapters/github/static-token-provider.d.ts

@@ -0,0 +1,30 @@
+/**
+ * StaticTokenProvider — a fixed-token {@link ForgeCredentialProvider} for the CLI
+ * path (SDD forge-agnostic task 2.2).
+ *
+ * Returns a long-lived token supplied up front (e.g. `GITHUB_TOKEN` / a PAT) with
+ * NO cache and NO refresh — there is nothing to mint. It exists so the CLI (P3)
+ * and GitLab-via-CLI (P4) can satisfy the SAME credential seam the server worker
+ * uses, making the auth strategy a pure construction-site choice (R-TOKEN: "swap
+ * App→Static requires no worker change").
+ *
+ * Forge-agnostic by construction: it takes the token as a plain string, so it is
+ * not GitHub-specific despite living under adapters/github (the only current
+ * consumer is the GitHub CLI path).
+ */
+import type { ForgeCredentialProvider } from '../../ports/credential-provider.js';
+/** Fixed-token credential provider (no cache, no refresh). */
+export declare class StaticTokenProvider implements ForgeCredentialProvider {
+    #private;
+    constructor(token: string);
+    /** Return the fixed token. Always the same value; never mints or refreshes. */
+    getToken(): Promise<string>;
+    /**
+     * No-op: a static provider has NO cache to drop. The fixed token cannot be
+     * re-acquired (there is nothing to mint), so a 401/403 here is terminal — but
+     * the method exists to satisfy the {@link ForgeCredentialProvider} port so the
+     * SAME 401-recovery call-site works regardless of which provider is wired.
+     */
+    invalidate(): void;
+}
+//# sourceMappingURL=static-token-provider.d.ts.map

package/dist/adapters/github/static-token-provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"static-token-provider.d.ts","sourceRoot":"","sources":["../../../src/adapters/github/static-token-provider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,oCAAoC,CAAC;AAElF,8DAA8D;AAC9D,qBAAa,mBAAoB,YAAW,uBAAuB;;gBAGrD,KAAK,EAAE,MAAM;IAIzB,+EAA+E;IACzE,QAAQ,IAAI,OAAO,CAAC,MAAM,CAAC;IAIjC;;;;;OAKG;IACH,UAAU,IAAI,IAAI;CAGnB"}

package/dist/adapters/github/static-token-provider.js

@@ -0,0 +1,35 @@
+/**
+ * StaticTokenProvider — a fixed-token {@link ForgeCredentialProvider} for the CLI
+ * path (SDD forge-agnostic task 2.2).
+ *
+ * Returns a long-lived token supplied up front (e.g. `GITHUB_TOKEN` / a PAT) with
+ * NO cache and NO refresh — there is nothing to mint. It exists so the CLI (P3)
+ * and GitLab-via-CLI (P4) can satisfy the SAME credential seam the server worker
+ * uses, making the auth strategy a pure construction-site choice (R-TOKEN: "swap
+ * App→Static requires no worker change").
+ *
+ * Forge-agnostic by construction: it takes the token as a plain string, so it is
+ * not GitHub-specific despite living under adapters/github (the only current
+ * consumer is the GitHub CLI path).
+ */
+/** Fixed-token credential provider (no cache, no refresh). */
+export class StaticTokenProvider {
+    #token;
+    constructor(token) {
+        this.#token = token;
+    }
+    /** Return the fixed token. Always the same value; never mints or refreshes. */
+    async getToken() {
+        return this.#token;
+    }
+    /**
+     * No-op: a static provider has NO cache to drop. The fixed token cannot be
+     * re-acquired (there is nothing to mint), so a 401/403 here is terminal — but
+     * the method exists to satisfy the {@link ForgeCredentialProvider} port so the
+     * SAME 401-recovery call-site works regardless of which provider is wired.
+     */
+    invalidate() {
+        // intentionally empty — no cache, nothing to invalidate.
+    }
+}
+//# sourceMappingURL=static-token-provider.js.map

package/dist/adapters/github/static-token-provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"static-token-provider.js","sourceRoot":"","sources":["../../../src/adapters/github/static-token-provider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAIH,8DAA8D;AAC9D,MAAM,OAAO,mBAAmB;IACrB,MAAM,CAAS;IAExB,YAAY,KAAa;QACvB,IAAI,CAAC,MAAM,GAAG,KAAK,CAAC;IACtB,CAAC;IAED,+EAA+E;IAC/E,KAAK,CAAC,QAAQ;QACZ,OAAO,IAAI,CAAC,MAAM,CAAC;IACrB,CAAC;IAED;;;;;OAKG;IACH,UAAU;QACR,yDAAyD;IAC3D,CAAC;CACF"}

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

@@ -0,0 +1,82 @@
+/**
+ * GitLab client PORT (dependency inversion seam for the GitLab adapter).
+ *
+ * R-AGNOSTIC / boundary rule: `packages/forge` MUST NOT import a concrete HTTP
+ * client. Mirroring {@link GitHubClientPort}, the {@link GitLabForgeAdapter}
+ * declares — here — the exact GitLab REST function-set it depends on, and the
+ * CALLER (the CLI, P4) injects a native-fetch implementation at construction.
+ *
+ * This interface is intentionally GitLab-native (numeric note ids, numeric
+ * project id, MR iid): the adapter is the layer that maps GitLab-native shapes ↔
+ * canonical forge types. Note ids cross THIS seam as PLAIN numbers
+ * (GitLab-native) — boxing into the canonical `CommentId` (kind:'gitlab') happens
+ * caller-LOCAL via {@link gitlabCommentId}, NOT here.
+ *
+ * SCOPE (P4 — MR summary post-back + inline-note publish):
+ *   REAL members the adapter folds over:
+ *     - listMrNotes   (GET    /projects/:id/merge_requests/:iid/notes)
+ *     - createMrNote  (POST   /projects/:id/merge_requests/:iid/notes)
+ *     - deleteMrNote  (DELETE /projects/:id/merge_requests/:iid/notes/:note_id)
+ *     - updateMrNote  (PUT    /projects/:id/merge_requests/:iid/notes/:note_id)
+ *   The CLI injects real fetch-backed impls (P4); read fns the adapter does not
+ *   need (diff/details/file-list/commits/graph) are deliberately NOT on this
+ *   port — the GitLab v1 deliverable is the summary-comment, and the CLI sources
+ *   the diff locally (same posture as the GitHub CLI port).
+ */
+/** A single GitLab MR note as returned by the list endpoint (subset used). */
+export interface GitLabNote {
+    /** GitLab-native numeric note id. */
+    id: number;
+    /** Note body (markdown) — scanned for the GHAGGA marker. */
+    body: string;
+}
+/**
+ * The GitLab text-diff position payload for a discussion (`position_type=text`).
+ *
+ * Mirrors the GitLab discussions API `position[...]` fields. `oldPath`/`newPath`
+ * are BOTH required by GitLab for a text diff note (they coincide for a
+ * non-renamed file). At least one of `oldLine`/`newLine` must be set.
+ */
+export interface GitLabDiffPosition {
+    baseSha: string;
+    headSha: string;
+    startSha: string;
+    oldPath: string;
+    newPath: string;
+    oldLine?: number;
+    newLine?: number;
+}
+/**
+ * The set of GitLab REST functions the {@link GitLabForgeAdapter} depends on.
+ *
+ * Calls are project-id + MR-iid positional (the GitLab MR API path is
+ * `/projects/:id/merge_requests/:iid/...`). `projectId` is the GitLab NUMERIC
+ * project id (canonical — the group/project path is mutable). The adapter
+ * receives an implementation via its constructor (dependency inversion) so the
+ * forge package never imports a concrete client.
+ */
+export interface GitLabClientPort {
+    /** List the notes on an MR (chronological); returns id + body per note. */
+    listMrNotes(projectId: string, mrIid: number, token: string): Promise<GitLabNote[]>;
+    /** Create a fresh MR note; returns the GitLab-native numeric note id. */
+    createMrNote(projectId: string, mrIid: number, body: string, token: string): Promise<{
+        id: number;
+    }>;
+    /** Delete an MR note by its GitLab-native numeric note id. */
+    deleteMrNote(projectId: string, mrIid: number, noteId: number, token: string): Promise<void>;
+    /** Update an MR note in place by its GitLab-native numeric note id. */
+    updateMrNote(projectId: string, mrIid: number, noteId: number, body: string, token: string): Promise<void>;
+    /**
+     * Create a diff-anchored MR DISCUSSION (`POST /merge_requests/:iid/discussions`
+     * with `position[position_type]=text`). Used by `publishInline` when the
+     * caller supplies a {@link GitLabDiffPosition}. Returns the GitLab-native
+     * numeric id of the discussion's FIRST note (so it boxes like a note id).
+     *
+     * OPTIONAL: an injected client MAY omit this (older CLI builds). When absent,
+     * `publishInline` degrades a positioned comment to a plain `path:line` note.
+     */
+    createMrDiscussion?(projectId: string, mrIid: number, body: string, position: GitLabDiffPosition, token: string): Promise<{
+        id: number;
+    }>;
+}
+//# sourceMappingURL=gitlab-client-port.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"gitlab-client-port.d.ts","sourceRoot":"","sources":["../../../src/adapters/gitlab/gitlab-client-port.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,8EAA8E;AAC9E,MAAM,WAAW,UAAU;IACzB,qCAAqC;IACrC,EAAE,EAAE,MAAM,CAAC;IACX,4DAA4D;IAC5D,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;;;;GAMG;AACH,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,gBAAgB;IAC/B,2EAA2E;IAC3E,WAAW,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC,CAAC;IAEpF,yEAAyE;IACzE,YAAY,CACV,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC;QAAE,EAAE,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAE3B,8DAA8D;IAC9D,YAAY,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE7F,uEAAuE;IACvE,YAAY,CACV,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,IAAI,CAAC,CAAC;IAEjB;;;;;;;;OAQG;IACH,kBAAkB,CAAC,CACjB,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,kBAAkB,EAC5B,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC;QAAE,EAAE,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAC5B"}

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

@@ -0,0 +1,27 @@
+/**
+ * GitLab client PORT (dependency inversion seam for the GitLab adapter).
+ *
+ * R-AGNOSTIC / boundary rule: `packages/forge` MUST NOT import a concrete HTTP
+ * client. Mirroring {@link GitHubClientPort}, the {@link GitLabForgeAdapter}
+ * declares — here — the exact GitLab REST function-set it depends on, and the
+ * CALLER (the CLI, P4) injects a native-fetch implementation at construction.
+ *
+ * This interface is intentionally GitLab-native (numeric note ids, numeric
+ * project id, MR iid): the adapter is the layer that maps GitLab-native shapes ↔
+ * canonical forge types. Note ids cross THIS seam as PLAIN numbers
+ * (GitLab-native) — boxing into the canonical `CommentId` (kind:'gitlab') happens
+ * caller-LOCAL via {@link gitlabCommentId}, NOT here.
+ *
+ * SCOPE (P4 — MR summary post-back + inline-note publish):
+ *   REAL members the adapter folds over:
+ *     - listMrNotes   (GET    /projects/:id/merge_requests/:iid/notes)
+ *     - createMrNote  (POST   /projects/:id/merge_requests/:iid/notes)
+ *     - deleteMrNote  (DELETE /projects/:id/merge_requests/:iid/notes/:note_id)
+ *     - updateMrNote  (PUT    /projects/:id/merge_requests/:iid/notes/:note_id)
+ *   The CLI injects real fetch-backed impls (P4); read fns the adapter does not
+ *   need (diff/details/file-list/commits/graph) are deliberately NOT on this
+ *   port — the GitLab v1 deliverable is the summary-comment, and the CLI sources
+ *   the diff locally (same posture as the GitHub CLI port).
+ */
+export {};
+//# sourceMappingURL=gitlab-client-port.js.map

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

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

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

@@ -0,0 +1,118 @@
+/**
+ * GitLabForgeAdapter — wraps a GitLab REST client behind the forge-agnostic
+ * {@link ForgeAdapterBase} + {@link InlineCapable} surfaces.
+ *
+ * DEPENDENCY INVERSION (boundary rule R-AGNOSTIC):
+ * `packages/forge` MUST NOT import a concrete HTTP client. This adapter depends
+ * on the injected {@link GitLabClientPort} (declared inside the forge package);
+ * the CLI (P4) constructs the adapter passing a native-fetch implementation:
+ *
+ *   new GitLabForgeAdapter({ client, token, projectId })
+ *
+ * IDENTITY (R-GITLAB):
+ * - {@link RepoRef.nativeId} is the GitLab NUMERIC project id (the group/project
+ *   `path` is mutable → the id is canonical). The adapter is constructed with the
+ *   numeric `projectId` and routes EVERY REST call through it — never the path.
+ * - {@link ChangeRequestRef.iid} is the MR iid (project-scoped). The GitLab MR
+ *   API path is `/projects/:id/merge_requests/:iid/...`.
+ *
+ * CAPABILITIES: reactions ❌ (GitLab reaction-award is not modelled — no
+ * `addReaction`), inlineComments ✅ (publishInline present), graphRead ❌ (no
+ * graph methods). The `capabilities` field is a HINT only (R-CAPABILITY): callers
+ * guard optional methods by method-presence, never by these flags.
+ *
+ * SCOPE — v1 deliverable is the SUMMARY COMMENT (upsertSummaryComment). The
+ * adapter also implements {@link InlineCapable.publishInline} to satisfy
+ * R-LEAK-PUBLISH: it posts N INDEPENDENT inline posts, returning a
+ * {@link PublishReport} where partial failure is FIRST-CLASS (never swallowed).
+ * INLINE POSITIONING: when an {@link InlineComment} carries `position` and the
+ * injected client supports `createMrDiscussion`, v1 posts a TRUE diff-anchored
+ * discussion (`position[position_type]=text` + the three SHAs + old/new line +
+ * old/new path). When `position` is absent (or the client lacks discussion
+ * support) it degrades to a plain MR note carrying the `path:line` prefix in the
+ * body. The public {@link InlineComment} type carries `position` + `oldPath`/
+ * `newPath` regardless, so broadening positioned coverage needs NO API change.
+ *
+ * COMMENT IDs: `upsertSummaryComment` returns PLAIN GitLab-native numeric ids
+ * (boxing happens caller-LOCAL via {@link gitlabCommentId}). `publishInline`
+ * boxes per the {@link PublishReport} contract (CommentId) since the report is
+ * the canonical cross-forge shape.
+ */
+import type { ForgeAdapterBase, InlineCapable, InlineComment } from '../../ports/forge-adapter.js';
+import type { ChangedFile, ChangeRequest, ChangeRequestRef, CommentMarker, Commit, ForgeCapabilities, PublishReport, UnifiedDiff, UpsertSummaryResult } from '../../types.js';
+import type { GitLabClientPort } from './gitlab-client-port.js';
+/** Construction options for {@link GitLabForgeAdapter}. */
+export interface GitLabForgeAdapterDeps {
+    /** Injected GitLab REST function-set (real impl = the CLI's fetch client). */
+    client: GitLabClientPort;
+    /** GitLab Personal Access Token used for all calls. */
+    token: string;
+    /**
+     * The GitLab NUMERIC project id (canonical — see R-GITLAB). NOT the mutable
+     * group/project path. The CLI resolves this from the path via
+     * `GET /projects/:url-encoded-path` before constructing the adapter.
+     */
+    projectId: string;
+}
+/**
+ * GitLab implementation of the forge adapter.
+ *
+ * Implements the mandatory base (summary-comment + the read methods, the latter
+ * unused by the CLI v1 path and intentionally absent from the client port) plus
+ * {@link InlineCapable}. Deliberately does NOT implement reactions or graph read.
+ */
+export declare class GitLabForgeAdapter implements ForgeAdapterBase, InlineCapable {
+    #private;
+    readonly capabilities: ForgeCapabilities;
+    constructor(deps: GitLabForgeAdapterDeps);
+    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 note on an MR.
+     *
+     * Behavior (mirrors the GitHub adapter's delete-all-stale + repost-at-bottom):
+     * 1. list MR notes; match the GHAGGA-owned ones by `marker.html` substring.
+     * 2. delete ALL matches in `[latest, ...stale]` order — BEST-EFFORT: each
+     *    delete is per-note try/catch so a 404 (already gone) OR any other failure
+     *    is tolerated and does NOT block the repost. Only ids that actually deleted
+     *    (no throw) are reported in `deleted`.
+     * 3. create a FRESH note at the bottom — this is the ONLY failure that
+     *    propagates (a failed create means no summary exists, which is fatal).
+     *
+     * "latest" = the LAST marker-matching note in chronological order (GitLab list
+     * returns notes oldest-first), matching the GitHub adapter's convention.
+     *
+     * Returns GitLab-native numeric ids (boxing happens caller-local via
+     * {@link gitlabCommentId}).
+     */
+    upsertSummaryComment(ref: ChangeRequestRef, body: string, marker: CommentMarker): Promise<UpsertSummaryResult>;
+    /**
+     * Publish a batch of inline comments as N INDEPENDENT posts (R-LEAK-PUBLISH).
+     *
+     * PARTIAL FAILURE IS FIRST-CLASS: GitLab posts each comment independently, so
+     * each create is wrapped in its own try/catch. A failure records
+     * `{index, error, status?, authFailure?}` into `failed` and the loop CONTINUES
+     * — failures are NEVER swallowed and never abort the remaining posts. The
+     * `status`/`authFailure` tags let a caller tell an AUTH failure (401/403, a
+     * static PAT cannot recover) from a transient one without string-parsing the
+     * message. Successes are boxed into `CommentId` (kind:'gitlab') and collected
+     * into `posted`.
+     *
+     * POSITION HANDLING (v1):
+     * - When a comment carries `position` AND the injected client implements
+     *   `createMrDiscussion`, the adapter posts a TRUE diff-anchored discussion
+     *   (`position[position_type]=text` with the three SHAs + old/new line +
+     *   old/new path — renames are honored via `oldPath`/`newPath`, defaulting to
+     *   `path`). The boxed id is the discussion's first-note id.
+     * - Otherwise (no `position`, or a client without discussion support) it
+     *   degrades to a plain MR note carrying a `path:line` body prefix so the
+     *   anchor info is not lost. Either way the partial-failure REPORT SHAPE +
+     *   independent-post semantics — the load-bearing R-LEAK-PUBLISH contract —
+     *   hold. The public {@link InlineComment} type carries `position` regardless,
+     *   so no future API change is needed to broaden positioned coverage.
+     */
+    publishInline(ref: ChangeRequestRef, comments: InlineComment[]): Promise<PublishReport>;
+}
+//# sourceMappingURL=gitlab-forge-adapter.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"gitlab-forge-adapter.d.ts","sourceRoot":"","sources":["../../../src/adapters/gitlab/gitlab-forge-adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAIH,OAAO,KAAK,EAAE,gBAAgB,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,8BAA8B,CAAC;AACnG,OAAO,KAAK,EACV,WAAW,EACX,aAAa,EACb,gBAAgB,EAChB,aAAa,EACb,MAAM,EACN,iBAAiB,EAEjB,aAAa,EACb,WAAW,EACX,mBAAmB,EACpB,MAAM,gBAAgB,CAAC;AACxB,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAEhE,2DAA2D;AAC3D,MAAM,WAAW,sBAAsB;IACrC,8EAA8E;IAC9E,MAAM,EAAE,gBAAgB,CAAC;IACzB,uDAAuD;IACvD,KAAK,EAAE,MAAM,CAAC;IACd;;;;OAIG;IACH,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;GAMG;AACH,qBAAa,kBAAmB,YAAW,gBAAgB,EAAE,aAAa;;IACxE,QAAQ,CAAC,YAAY,EAAE,iBAAiB,CAItC;gBAMU,IAAI,EAAE,sBAAsB;IAmCxC,SAAS,CAAC,IAAI,EAAE,gBAAgB,GAAG,OAAO,CAAC,WAAW,CAAC;IASvD,kBAAkB,CAAC,IAAI,EAAE,gBAAgB,GAAG,OAAO,CAAC,aAAa,CAAC;IAMlE,aAAa,CAAC,IAAI,EAAE,gBAAgB,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;IAM7D,YAAY,CAAC,IAAI,EAAE,gBAAgB,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAQvD;;;;;;;;;;;;;;;;;OAiBG;IACG,oBAAoB,CACxB,GAAG,EAAE,gBAAgB,EACrB,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,aAAa,GACpB,OAAO,CAAC,mBAAmB,CAAC;IA2C/B;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACG,aAAa,CAAC,GAAG,EAAE,gBAAgB,EAAE,QAAQ,EAAE,aAAa,EAAE,GAAG,OAAO,CAAC,aAAa,CAAC;CAqE9F"}