@a5c-ai/tasks-mux 5.0.1-staging.078c111a306a

package/README.md

@@ -0,0 +1,103 @@
+# @a5c-ai/tasks-mux
+
+Breakpoint routing library, MCP server, and CLI for responder-driven review flows.
+
+## Install
+
+Use the published npm package in consumers. Install it locally in a project or run it directly with `npx`.
+
+```bash
+npm install --save-dev @a5c-ai/tasks-mux
+npx --yes @a5c-ai/tasks-mux --help
+```
+
+## CLI
+
+The published executable is `tasks-mux`. The supported consumer workflow is either:
+
+- run the published package with `npx --yes @a5c-ai/tasks-mux ...`
+- install `@a5c-ai/tasks-mux` and invoke `tasks-mux ...`
+
+```bash
+npx --yes @a5c-ai/tasks-mux --help
+npx --yes @a5c-ai/tasks-mux responders list
+npx --yes @a5c-ai/tasks-mux auth login
+npx --yes @a5c-ai/tasks-mux server start
+```
+
+If the published package is already installed locally or globally, use the bin directly:
+
+```bash
+tasks-mux --help
+tasks-mux auth server set https://tasks-mux.a5c.ai
+tasks-mux auth login
+```
+
+Current CLI commands:
+
+- `tasks-mux ask`
+- `tasks-mux responders list`
+- `tasks-mux responders show <responderId>`
+- `tasks-mux breakpoints pending --responder <responderId>`
+- `tasks-mux breakpoints answer <breakpointId> --answer <text> --responder <responderId> [--confidence <0-100>]`
+- `tasks-mux breakpoints status <breakpointId>`
+- `tasks-mux breakpoints poll <breakpointId> [--timeout <seconds>] [--interval <seconds>]`
+- `tasks-mux responder-loop --responder <responderId> [--interval <seconds>] [--once]`
+- `tasks-mux server start`
+- `tasks-mux auth login|logout|status|server set|server clear|token set|token clear|keygen|key-push|keys`
+
+## MCP Tools
+
+The MCP server currently registers these tools:
+
+- `ask_breakpoint`
+- `check_breakpoint_status`
+- `list_breakpoints`
+- `answer_breakpoint`
+- `verify_breakpoint_answer`
+- `list_responders`
+- `claim_breakpoint`
+- `poll_breakpoints`
+
+## Package Exports
+
+Published subpath exports:
+
+- `.`
+- `./backends`
+- `./proven`
+- `./mcp`
+- `./harness`
+- `./auth`
+- `./config`
+
+Example:
+
+```ts
+import {
+  createBackend,
+  createBreakpointMcpServer,
+  BreakpointMuxInteractionProvider,
+} from "@a5c-ai/tasks-mux";
+```
+
+## Published Package Contents
+
+The npm tarball is intentionally limited to:
+
+- `dist/`
+- `responder/`
+- `README.md`
+
+`docs/`, `skills/`, and `specs/` are repository source docs and are not published files.
+
+## Validation
+
+```bash
+npm run build --workspace=@a5c-ai/tasks-mux
+npm run typecheck --workspace=@a5c-ai/tasks-mux
+npm run test:packaged-surface-parity --workspace=@a5c-ai/tasks-mux
+npm pack --json --dry-run --workspace=@a5c-ai/tasks-mux
+```
+
+Keep this README aligned with the exported CLI, MCP, and package topology surfaced by `packages/tasks-mux/`.

package/dist/auth/forge-interface.d.ts

@@ -0,0 +1,67 @@
+import type { GitForgeConfig } from "./types.js";
+import { GitHubAppClient } from "./github-app.js";
+export interface PullRequestOpts {
+    owner: string;
+    repo: string;
+    title: string;
+    head: string;
+    base: string;
+    body?: string;
+}
+export interface PullRequestResult {
+    prUrl: string;
+    prNumber: number;
+}
+export interface PushFileOpts {
+    owner: string;
+    repo: string;
+    path: string;
+    content: string;
+    message: string;
+    branch?: string;
+}
+export interface RepoInfo {
+    owner: string;
+    name: string;
+    fullName: string;
+    defaultBranch: string;
+    private: boolean;
+}
+/**
+ * Pluggable interface for interacting with Git forges (GitHub, GitLab, etc.).
+ */
+export interface GitForge {
+    createPR(opts: PullRequestOpts): Promise<PullRequestResult>;
+    readFile(opts: {
+        owner: string;
+        repo: string;
+        path: string;
+        ref?: string;
+    }): Promise<string>;
+    pushFile(opts: PushFileOpts): Promise<void>;
+    listRepos(owner: string): Promise<RepoInfo[]>;
+}
+/**
+ * GitHub implementation of the GitForge interface.
+ * Wraps GitHubAppClient for repository operations.
+ */
+export declare class GitHubForge implements GitForge {
+    private readonly client;
+    private readonly installationId;
+    constructor(client: GitHubAppClient, installationId: number);
+    createPR(opts: PullRequestOpts): Promise<PullRequestResult>;
+    readFile(opts: {
+        owner: string;
+        repo: string;
+        path: string;
+        ref?: string;
+    }): Promise<string>;
+    pushFile(opts: PushFileOpts): Promise<void>;
+    listRepos(owner: string): Promise<RepoInfo[]>;
+}
+/**
+ * Create a GitForge instance from a configuration object.
+ * Currently only supports GitHub.
+ */
+export declare function createForge(config: GitForgeConfig): GitForge;
+//# sourceMappingURL=forge-interface.d.ts.map

package/dist/auth/forge-interface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"forge-interface.d.ts","sourceRoot":"","sources":["../../src/auth/forge-interface.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAmB,MAAM,YAAY,CAAC;AAClE,OAAO,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAIlD,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,QAAQ;IACvB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,EAAE,MAAM,CAAC;IACtB,OAAO,EAAE,OAAO,CAAC;CAClB;AAID;;GAEG;AACH,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,IAAI,EAAE,eAAe,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAAC;IAC5D,QAAQ,CAAC,IAAI,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,GAAG,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAC7F,QAAQ,CAAC,IAAI,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5C,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC,CAAC;CAC/C;AAID;;;GAGG;AACH,qBAAa,WAAY,YAAW,QAAQ;IAC1C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAkB;IACzC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAS;gBAE5B,MAAM,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM;IAKrD,QAAQ,CAAC,IAAI,EAAE,eAAe,GAAG,OAAO,CAAC,iBAAiB,CAAC;IAgB3D,QAAQ,CAAC,IAAI,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,GAAG,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,MAAM,CAAC;IAOlG,QAAQ,CAAC,IAAI,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC;IAM3C,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC;CAK9C;AAID;;;GAGG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,cAAc,GAAG,QAAQ,CAmB5D"}

package/dist/auth/forge-interface.js

@@ -0,0 +1,69 @@
+import { GitHubAppClient } from "./github-app.js";
+// ── GitHubForge ───────────────────────────────────────────────────────────
+/**
+ * GitHub implementation of the GitForge interface.
+ * Wraps GitHubAppClient for repository operations.
+ */
+export class GitHubForge {
+    client;
+    installationId;
+    constructor(client, installationId) {
+        this.client = client;
+        this.installationId = installationId;
+    }
+    async createPR(opts) {
+        const result = await this.client.createKeyPR({
+            owner: opts.owner,
+            repo: opts.repo,
+            installationId: this.installationId,
+            userId: "forge",
+            publicKey: opts.body ?? "",
+            keyPath: opts.head,
+        });
+        return {
+            prUrl: result.prUrl,
+            prNumber: result.prNumber,
+        };
+    }
+    async readFile(opts) {
+        return this.client.readFile({
+            ...opts,
+            installationId: this.installationId,
+        });
+    }
+    pushFile(opts) {
+        void opts;
+        // Delegated to Octokit createOrUpdateFileContents via the client
+        return Promise.reject(new Error("pushFile not yet implemented for GitHubForge"));
+    }
+    listRepos(owner) {
+        void owner;
+        // Delegated to Octokit list repos endpoint
+        return Promise.reject(new Error("listRepos not yet implemented for GitHubForge"));
+    }
+}
+// ── Factory ───────────────────────────────────────────────────────────────
+/**
+ * Create a GitForge instance from a configuration object.
+ * Currently only supports GitHub.
+ */
+export function createForge(config) {
+    switch (config.type) {
+        case "github": {
+            const appConfig = {
+                appId: config.credentials.appId ?? "",
+                privateKey: config.credentials.privateKey ?? "",
+                webhookSecret: config.credentials.webhookSecret,
+            };
+            const installationId = parseInt(config.credentials.installationId ?? "0", 10);
+            const client = new GitHubAppClient(appConfig);
+            return new GitHubForge(client, installationId);
+        }
+        case "gitlab":
+            throw new Error("GitLab forge not yet implemented");
+        case "bitbucket":
+            throw new Error("Bitbucket forge not yet implemented");
+        default:
+            throw new Error(`Unknown forge type: ${config.type}`);
+    }
+}

package/dist/auth/github-app.d.ts

@@ -0,0 +1,64 @@
+import type { GitHubAppConfig } from "./types.js";
+export interface Installation {
+    id: number;
+    account: {
+        login: string;
+        type: string;
+    };
+    repositorySelection: string;
+}
+export interface CreateKeyPROpts {
+    owner: string;
+    repo: string;
+    installationId: number;
+    userId: string;
+    publicKey: string;
+    keyPath: string;
+}
+export interface CreateKeyPRResult {
+    prUrl: string;
+    prNumber: number;
+    branch: string;
+}
+/**
+ * Client for interacting with GitHub as a GitHub App.
+ * Uses @octokit/rest and @octokit/auth-app for authentication.
+ */
+export declare class GitHubAppClient {
+    private readonly config;
+    constructor(config: GitHubAppConfig);
+    /**
+     * Get an installation access token for a specific installation.
+     */
+    getInstallationToken(installationId: number): Promise<string>;
+    /**
+     * Create a pull request to add an SSH public key to a repository.
+     */
+    createKeyPR(opts: CreateKeyPROpts): Promise<CreateKeyPRResult>;
+    /**
+     * Read a file from a repository.
+     */
+    readFile(opts: {
+        owner: string;
+        repo: string;
+        installationId: number;
+        path: string;
+        ref?: string;
+    }): Promise<string>;
+    /**
+     * List all installations for this GitHub App.
+     */
+    listInstallations(): Promise<Installation[]>;
+    /**
+     * Extract the key type prefix from an SSH public key string.
+     */
+    private extractKeyType;
+    /**
+     * Extract a short fingerprint-like identifier from an SSH public key.
+     * Returns the first 16 chars of the base64 key data for identification.
+     */
+    private extractKeyFingerprint;
+    private createAppOctokit;
+    private createInstallationOctokit;
+}
+//# sourceMappingURL=github-app.d.ts.map

package/dist/auth/github-app.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"github-app.d.ts","sourceRoot":"","sources":["../../src/auth/github-app.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAIlD,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE;QACP,KAAK,EAAE,MAAM,CAAC;QACd,IAAI,EAAE,MAAM,CAAC;KACd,CAAC;IACF,mBAAmB,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,cAAc,EAAE,MAAM,CAAC;IACvB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;CAChB;AAID;;;GAGG;AACH,qBAAa,eAAe;IAC1B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAkB;gBAE7B,MAAM,EAAE,eAAe;IAInC;;OAEG;IACG,oBAAoB,CAAC,cAAc,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAUnE;;OAEG;IACG,WAAW,CAAC,IAAI,EAAE,eAAe,GAAG,OAAO,CAAC,iBAAiB,CAAC;IA6DpE;;OAEG;IACG,QAAQ,CAAC,IAAI,EAAE;QACnB,KAAK,EAAE,MAAM,CAAC;QACd,IAAI,EAAE,MAAM,CAAC;QACb,cAAc,EAAE,MAAM,CAAC;QACvB,IAAI,EAAE,MAAM,CAAC;QACb,GAAG,CAAC,EAAE,MAAM,CAAC;KACd,GAAG,OAAO,CAAC,MAAM,CAAC;IAiBnB;;OAEG;IACG,iBAAiB,IAAI,OAAO,CAAC,YAAY,EAAE,CAAC;IAiBlD;;OAEG;IACH,OAAO,CAAC,cAAc;IAKtB;;;OAGG;IACH,OAAO,CAAC,qBAAqB;IAM7B,OAAO,CAAC,gBAAgB;YAUV,yBAAyB;CAIxC"}

package/dist/auth/github-app.js

@@ -0,0 +1,141 @@
+import { Octokit } from "@octokit/rest";
+import { createAppAuth } from "@octokit/auth-app";
+// ── GitHubAppClient ───────────────────────────────────────────────────────
+/**
+ * Client for interacting with GitHub as a GitHub App.
+ * Uses @octokit/rest and @octokit/auth-app for authentication.
+ */
+export class GitHubAppClient {
+    config;
+    constructor(config) {
+        this.config = config;
+    }
+    /**
+     * Get an installation access token for a specific installation.
+     */
+    async getInstallationToken(installationId) {
+        const octokit = this.createAppOctokit();
+        const { data } = await octokit.apps.createInstallationAccessToken({
+            installation_id: installationId,
+        });
+        return data.token;
+    }
+    /**
+     * Create a pull request to add an SSH public key to a repository.
+     */
+    async createKeyPR(opts) {
+        const octokit = await this.createInstallationOctokit(opts.installationId);
+        const branch = `tasks-mux/add-key-${opts.userId}-${Date.now()}`;
+        // Get the default branch ref
+        const { data: repo } = await octokit.repos.get({
+            owner: opts.owner,
+            repo: opts.repo,
+        });
+        const defaultBranch = repo.default_branch;
+        // Get the HEAD SHA of the default branch
+        const { data: ref } = await octokit.git.getRef({
+            owner: opts.owner,
+            repo: opts.repo,
+            ref: `heads/${defaultBranch}`,
+        });
+        const baseSha = ref.object.sha;
+        // Create a new branch
+        await octokit.git.createRef({
+            owner: opts.owner,
+            repo: opts.repo,
+            ref: `refs/heads/${branch}`,
+            sha: baseSha,
+        });
+        // Create or update the key file at {keyPath}/{userId}.pub
+        const filePath = `${opts.keyPath}/${opts.userId}.pub`;
+        await octokit.repos.createOrUpdateFileContents({
+            owner: opts.owner,
+            repo: opts.repo,
+            path: filePath,
+            message: `Add SSH public key for user ${opts.userId}`,
+            content: Buffer.from(opts.publicKey).toString("base64"),
+            branch,
+        });
+        // Create a pull request
+        const { data: pr } = await octokit.pulls.create({
+            owner: opts.owner,
+            repo: opts.repo,
+            title: `Add SSH key for user ${opts.userId}`,
+            head: branch,
+            base: defaultBranch,
+            body: [
+                `This PR adds an SSH public key for user \`${opts.userId}\`.`,
+                "",
+                `**Key path:** \`${filePath}\``,
+                `**Key fingerprint:** \`${this.extractKeyFingerprint(opts.publicKey)}\``,
+                `**Key type:** \`${this.extractKeyType(opts.publicKey)}\``,
+            ].join("\n"),
+        });
+        return {
+            prUrl: pr.html_url,
+            prNumber: pr.number,
+            branch,
+        };
+    }
+    /**
+     * Read a file from a repository.
+     */
+    async readFile(opts) {
+        const octokit = await this.createInstallationOctokit(opts.installationId);
+        const { data } = await octokit.repos.getContent({
+            owner: opts.owner,
+            repo: opts.repo,
+            path: opts.path,
+            ref: opts.ref,
+        });
+        if (Array.isArray(data) || data.type !== "file") {
+            throw new Error(`Path "${opts.path}" is not a file`);
+        }
+        return Buffer.from(data.content, "base64").toString("utf-8");
+    }
+    /**
+     * List all installations for this GitHub App.
+     */
+    async listInstallations() {
+        const octokit = this.createAppOctokit();
+        const { data } = await octokit.apps.listInstallations();
+        return data.map((inst) => ({
+            id: inst.id,
+            account: {
+                login: inst.account?.login ?? "unknown",
+                type: inst.account?.type ?? "unknown",
+            },
+            repositorySelection: inst.repository_selection,
+        }));
+    }
+    // ── Internal helpers ──────────────────────────────────────────────────
+    /**
+     * Extract the key type prefix from an SSH public key string.
+     */
+    extractKeyType(publicKey) {
+        const parts = publicKey.trim().split(/\s+/);
+        return parts[0] ?? "unknown";
+    }
+    /**
+     * Extract a short fingerprint-like identifier from an SSH public key.
+     * Returns the first 16 chars of the base64 key data for identification.
+     */
+    extractKeyFingerprint(publicKey) {
+        const parts = publicKey.trim().split(/\s+/);
+        const keyData = parts[1] ?? "";
+        return keyData.length > 16 ? `SHA256:${keyData.substring(0, 16)}...` : `SHA256:${keyData}`;
+    }
+    createAppOctokit() {
+        return new Octokit({
+            authStrategy: createAppAuth,
+            auth: {
+                appId: this.config.appId,
+                privateKey: this.config.privateKey,
+            },
+        });
+    }
+    async createInstallationOctokit(installationId) {
+        const token = await this.getInstallationToken(installationId);
+        return new Octokit({ auth: token });
+    }
+}

package/dist/auth/github-oauth.d.ts

@@ -0,0 +1,27 @@
+import type { GitHubOAuthConfig, User } from "./types.js";
+/**
+ * OAuth 2.0 client for GitHub authentication.
+ * Uses native fetch() for HTTP calls with no external dependencies.
+ */
+export declare class GitHubOAuthClient {
+    private readonly config;
+    constructor(config: GitHubOAuthConfig);
+    /**
+     * Build the GitHub OAuth authorization URL.
+     * Optionally supports PKCE via codeVerifier (S256 challenge).
+     */
+    getAuthorizationUrl(state: string, codeVerifier?: string): string;
+    /**
+     * Exchange an authorization code for an access token.
+     */
+    exchangeCode(code: string, codeVerifier?: string): Promise<{
+        accessToken: string;
+        tokenType: string;
+        scope: string;
+    }>;
+    /**
+     * Fetch the authenticated user's profile from GitHub.
+     */
+    getUserProfile(accessToken: string): Promise<User>;
+}
+//# sourceMappingURL=github-oauth.d.ts.map

package/dist/auth/github-oauth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"github-oauth.d.ts","sourceRoot":"","sources":["../../src/auth/github-oauth.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AAU1D;;;GAGG;AACH,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAoB;gBAE/B,MAAM,EAAE,iBAAiB;IAIrC;;;OAGG;IACH,mBAAmB,CAAC,KAAK,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,MAAM,GAAG,MAAM;IAgBjE;;OAEG;IACG,YAAY,CAChB,IAAI,EAAE,MAAM,EACZ,YAAY,CAAC,EAAE,MAAM,GACpB,OAAO,CAAC;QAAE,WAAW,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;IA4CrE;;OAEG;IACG,cAAc,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CA6BzD"}

package/dist/auth/github-oauth.js

@@ -0,0 +1,89 @@
+// ── Constants ─────────────────────────────────────────────────────────────
+const GITHUB_AUTHORIZE_URL = "https://github.com/login/oauth/authorize";
+const GITHUB_TOKEN_URL = "https://github.com/login/oauth/access_token";
+const GITHUB_API_URL = "https://api.github.com";
+// ── GitHubOAuthClient ─────────────────────────────────────────────────────
+/**
+ * OAuth 2.0 client for GitHub authentication.
+ * Uses native fetch() for HTTP calls with no external dependencies.
+ */
+export class GitHubOAuthClient {
+    config;
+    constructor(config) {
+        this.config = config;
+    }
+    /**
+     * Build the GitHub OAuth authorization URL.
+     * Optionally supports PKCE via codeVerifier (S256 challenge).
+     */
+    getAuthorizationUrl(state, codeVerifier) {
+        const params = new URLSearchParams({
+            client_id: this.config.clientId,
+            redirect_uri: this.config.callbackUrl,
+            scope: this.config.scopes.join(" "),
+            state,
+        });
+        if (codeVerifier) {
+            params.set("code_challenge", codeVerifier);
+            params.set("code_challenge_method", "S256");
+        }
+        return `${GITHUB_AUTHORIZE_URL}?${params.toString()}`;
+    }
+    /**
+     * Exchange an authorization code for an access token.
+     */
+    async exchangeCode(code, codeVerifier) {
+        const body = {
+            client_id: this.config.clientId,
+            client_secret: this.config.clientSecret,
+            code,
+            redirect_uri: this.config.callbackUrl,
+        };
+        if (codeVerifier) {
+            body.code_verifier = codeVerifier;
+        }
+        const response = await fetch(GITHUB_TOKEN_URL, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                Accept: "application/json",
+            },
+            body: JSON.stringify(body),
+        });
+        if (!response.ok) {
+            throw new Error(`GitHub OAuth token exchange failed: ${response.status} ${response.statusText}`);
+        }
+        const data = (await response.json());
+        if (data.error) {
+            throw new Error(`GitHub OAuth error: ${data.error} - ${data.error_description ?? "unknown"}`);
+        }
+        return {
+            accessToken: data.access_token,
+            tokenType: data.token_type,
+            scope: data.scope,
+        };
+    }
+    /**
+     * Fetch the authenticated user's profile from GitHub.
+     */
+    async getUserProfile(accessToken) {
+        const response = await fetch(`${GITHUB_API_URL}/user`, {
+            headers: {
+                Authorization: `Bearer ${accessToken}`,
+                Accept: "application/json",
+            },
+        });
+        if (!response.ok) {
+            throw new Error(`GitHub API user fetch failed: ${response.status} ${response.statusText}`);
+        }
+        const data = (await response.json());
+        return {
+            id: String(data.id),
+            login: data.login,
+            name: data.name ?? data.login,
+            email: data.email ?? `${data.login}@users.noreply.github.com`,
+            avatarUrl: data.avatar_url,
+            provider: "github",
+        };
+    }
+}

package/dist/auth/index.d.ts

@@ -0,0 +1,8 @@
+export { UserSchema, type User, AuthTokenSchema, type AuthToken, JWTPayloadSchema, type JWTPayload, SSHKeyPairSchema, type SSHKeyPair, GitForgeConfigSchema, type GitForgeConfig, GitHubOAuthConfigSchema, type GitHubOAuthConfig, GitHubAppConfigSchema, type GitHubAppConfig, } from "./types.js";
+export { signAccessToken, signRefreshToken, verifyToken, refreshAccessToken, } from "./jwt.js";
+export { generateSSHKeyPair, parsePublicKey, calculateFingerprint, formatAuthorizedKey, } from "./ssh-keys.js";
+export { GitHubOAuthClient } from "./github-oauth.js";
+export { GitHubAppClient, type Installation, type CreateKeyPROpts, type CreateKeyPRResult, } from "./github-app.js";
+export { type GitForge, type PullRequestOpts, type PullRequestResult, type PushFileOpts, type RepoInfo, GitHubForge, createForge, } from "./forge-interface.js";
+export { createAuthMiddleware, type AuthMiddlewareOpts, } from "./middleware.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/auth/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/auth/index.ts"],"names":[],"mappings":"AACA,OAAO,EACL,UAAU,EACV,KAAK,IAAI,EACT,eAAe,EACf,KAAK,SAAS,EACd,gBAAgB,EAChB,KAAK,UAAU,EACf,gBAAgB,EAChB,KAAK,UAAU,EACf,oBAAoB,EACpB,KAAK,cAAc,EACnB,uBAAuB,EACvB,KAAK,iBAAiB,EACtB,qBAAqB,EACrB,KAAK,eAAe,GACrB,MAAM,YAAY,CAAC;AAGpB,OAAO,EACL,eAAe,EACf,gBAAgB,EAChB,WAAW,EACX,kBAAkB,GACnB,MAAM,UAAU,CAAC;AAGlB,OAAO,EACL,kBAAkB,EAClB,cAAc,EACd,oBAAoB,EACpB,mBAAmB,GACpB,MAAM,eAAe,CAAC;AAGvB,OAAO,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAGtD,OAAO,EACL,eAAe,EACf,KAAK,YAAY,EACjB,KAAK,eAAe,EACpB,KAAK,iBAAiB,GACvB,MAAM,iBAAiB,CAAC;AAGzB,OAAO,EACL,KAAK,QAAQ,EACb,KAAK,eAAe,EACpB,KAAK,iBAAiB,EACtB,KAAK,YAAY,EACjB,KAAK,QAAQ,EACb,WAAW,EACX,WAAW,GACZ,MAAM,sBAAsB,CAAC;AAG9B,OAAO,EACL,oBAAoB,EACpB,KAAK,kBAAkB,GACxB,MAAM,iBAAiB,CAAC"}

package/dist/auth/index.js

@@ -0,0 +1,14 @@
+// Types and Zod schemas
+export { UserSchema, AuthTokenSchema, JWTPayloadSchema, SSHKeyPairSchema, GitForgeConfigSchema, GitHubOAuthConfigSchema, GitHubAppConfigSchema, } from "./types.js";
+// JWT utilities
+export { signAccessToken, signRefreshToken, verifyToken, refreshAccessToken, } from "./jwt.js";
+// SSH key management
+export { generateSSHKeyPair, parsePublicKey, calculateFingerprint, formatAuthorizedKey, } from "./ssh-keys.js";
+// GitHub OAuth client
+export { GitHubOAuthClient } from "./github-oauth.js";
+// GitHub App client
+export { GitHubAppClient, } from "./github-app.js";
+// Forge interface
+export { GitHubForge, createForge, } from "./forge-interface.js";
+// Auth middleware
+export { createAuthMiddleware, } from "./middleware.js";

package/dist/auth/jwt.d.ts

@@ -0,0 +1,24 @@
+import type { StringValue } from "ms";
+import type { JWTPayload } from "./types.js";
+/**
+ * Sign a JWT access token with the given payload and secret.
+ */
+export declare function signAccessToken(payload: Pick<JWTPayload, "sub" | "login" | "name">, secret: string, expiresIn?: StringValue | number): string;
+/**
+ * Sign a JWT refresh token with the given payload and secret.
+ */
+export declare function signRefreshToken(payload: Pick<JWTPayload, "sub" | "login" | "name">, secret: string, expiresIn?: StringValue | number): string;
+/**
+ * Verify a JWT token and return its decoded payload.
+ * Throws if the token is invalid or expired.
+ */
+export declare function verifyToken(token: string, secret: string): JWTPayload;
+/**
+ * Refresh an access token using a valid refresh token.
+ * Returns a new access token and a new refresh token.
+ */
+export declare function refreshAccessToken(refreshToken: string, secret: string): {
+    accessToken: string;
+    refreshToken: string;
+};
+//# sourceMappingURL=jwt.d.ts.map

package/dist/auth/jwt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"jwt.d.ts","sourceRoot":"","sources":["../../src/auth/jwt.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,IAAI,CAAC;AAEtC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAW7C;;GAEG;AACH,wBAAgB,eAAe,CAC7B,OAAO,EAAE,IAAI,CAAC,UAAU,EAAE,KAAK,GAAG,OAAO,GAAG,MAAM,CAAC,EACnD,MAAM,EAAE,MAAM,EACd,SAAS,GAAE,WAAW,GAAG,MAAoC,GAC5D,MAAM,CAMR;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,IAAI,CAAC,UAAU,EAAE,KAAK,GAAG,OAAO,GAAG,MAAM,CAAC,EACnD,MAAM,EAAE,MAAM,EACd,SAAS,GAAE,WAAW,GAAG,MAAqC,GAC7D,MAAM,CAMR;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,UAAU,CAIrE;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAChC,YAAY,EAAE,MAAM,EACpB,MAAM,EAAE,MAAM,GACb;IAAE,WAAW,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,CAAA;CAAE,CAa/C"}