@auto-agents/github-app-installer 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Geoff Seemueller
+
+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,67 @@
+# auto-agents-github-app-installer
+
+Register a GitHub App for [auto-agents](https://github.com/geoffsee/auto-agents)'s code-review bot
+via the [GitHub App Manifest Flow](https://docs.github.com/en/apps/sharing-github-apps/registering-a-github-app-from-a-manifest).
+
+Run it from any repository — it spins up a local Bun server, opens your browser
+to GitHub's app-registration form, exchanges the returned code for credentials,
+and writes them where auto-agents expects.
+
+## Usage
+
+```bash
+bunx auto-agents-github-app-installer
+```
+
+For an organization-owned app:
+
+```bash
+GITHUB_ORG=my-org APP_NAME=my-auto-agents-bot bunx auto-agents-github-app-installer
+```
+
+### Environment variables
+
+| Variable      | Default                                 | Purpose                                                                                       |
+| ------------- | --------------------------------------- | --------------------------------------------------------------------------------------------- |
+| `PORT`        | `3000`                                  | Port for the local callback server.                                                           |
+| `GITHUB_ORG`  | _(personal)_                            | Register the app under this organization.                                                     |
+| `APP_NAME`    | `auto-agents-dev-bot`                       | Default name for the new app (editable on GitHub).                                            |
+| `WEBHOOK_URL` | `https://example.com/auto-agents-webhook`   | Webhook target embedded in the manifest. GitHub requires a public URL even with `active=false`. |
+
+### What it writes
+
+- `~/.config/auto-agents/dev-ui-bot.pem` — the app's private key, `chmod 600`.
+- `./.env.github-app` in the current directory — `DEV_BOT_APP_ID`, `DEV_BOT_PRIVATE_KEY`, etc.
+
+After the flow completes:
+
+1. Install the app on a repo via the URL printed in the terminal.
+2. Copy the installation ID from the resulting URL into `DEV_BOT_INSTALLATION_ID` in `.env.github-app`.
+3. `source .env.github-app && auto-agents`.
+
+## Programmatic use
+
+```ts
+import { run } from "auto-agents-github-app-installer";
+
+await run({
+  port: 4000,
+  owner: "my-org",
+  appName: "my-bot",
+});
+```
+
+Lower-level building blocks are exported from the package root: `buildManifest`,
+`createHandler`, `convertCode`, `writeAppCredentials`, `formatEnvFile`,
+`defaultConfigPaths`, `githubNewAppUrl`.
+
+## Development
+
+```bash
+bun install
+bun test
+bun run typecheck
+bun src/cli.ts   # run locally
+```
+
+Built on [Bun](https://bun.com); the published bin requires `bun` (use `bunx`, not `npx`).

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@auto-agents/github-app-installer",
+  "version": "0.1.1",
+  "description": "Register a GitHub App for auto-agents via the App Manifest Flow. Run `bunx @auto-agents/github-app-installer` in any repo.",
+  "license": "MIT",
+  "author": "Geoff Seemueller",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/geoffsee/auto-agents-github-app-installer"
+  },
+  "bugs": {
+    "url": "https://github.com/geoffsee/auto-agents-github-app-installer/issues"
+  },
+  "homepage": "https://github.com/geoffsee/auto-agents-github-app-installer#readme",
+  "type": "module",
+  "module": "./src/index.ts",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "bin": {
+    "auto-agents-github-app-installer": "./src/cli.ts"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "start": "bun src/cli.ts",
+    "test": "bun test",
+    "typecheck": "bunx tsc --noEmit",
+    "release": "bunx release-it",
+    "release:patch": "bunx release-it patch",
+    "release:minor": "bunx release-it minor",
+    "release:major": "bunx release-it major"
+  },
+  "keywords": [
+    "auto-agents",
+    "github-app",
+    "github-app-manifest",
+    "code-review"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "bun": ">=1.3.0"
+  },
+  "devDependencies": {
+    "@types/bun": "latest"
+  },
+  "peerDependencies": {
+    "typescript": "^5"
+  }
+}

package/src/cli.ts

@@ -0,0 +1,72 @@
+#!/usr/bin/env bun
+import {
+  type ConfigPaths,
+  defaultConfigPaths,
+  writeAppCredentials,
+} from "./config.ts";
+import { convertCode } from "./github.ts";
+import { createHandler } from "./handler.ts";
+import { buildManifest } from "./manifest.ts";
+
+export interface RunOptions {
+  port?: number;
+  owner?: string;
+  appName?: string;
+  hookUrl?: string;
+  openBrowser?: (url: string) => void;
+  configPaths?: ConfigPaths;
+}
+
+function defaultOpenBrowser(url: string): void {
+  const cmd =
+    process.platform === "darwin"
+      ? ["open", url]
+      : process.platform === "win32"
+        ? ["cmd", "/c", "start", url]
+        : ["xdg-open", url];
+  Bun.spawn(cmd, { stdout: "ignore", stderr: "ignore" });
+}
+
+export async function run(opts: RunOptions = {}): Promise<void> {
+  const port = opts.port ?? Number(process.env.PORT ?? 3000);
+  const owner = opts.owner ?? process.env.GITHUB_ORG;
+  const appName = opts.appName ?? process.env.APP_NAME ?? "auto-agents-dev-bot";
+  const hookUrl = opts.hookUrl ?? process.env.WEBHOOK_URL;
+  const openBrowser = opts.openBrowser ?? defaultOpenBrowser;
+
+  const baseUrl = `http://localhost:${port}`;
+  const manifest = buildManifest({ appName, baseUrl, hookUrl });
+  const state = crypto.randomUUID();
+  const paths = opts.configPaths ?? defaultConfigPaths();
+
+  let resolveDone: () => void;
+  const done = new Promise<void>((r) => {
+    resolveDone = r;
+  });
+
+  const server = Bun.serve({
+    port,
+    fetch: createHandler({
+      manifest,
+      state,
+      owner,
+      exchangeCode: (code) => convertCode(code),
+      onSuccess: async (app) => {
+        await writeAppCredentials(app, paths);
+        queueMicrotask(() => {
+          server.stop();
+          resolveDone();
+        });
+        return { pemPath: paths.pemPath, envPath: paths.envPath };
+      },
+    }),
+  });
+
+  console.log(`Listening on ${baseUrl} — opening browser…`);
+  openBrowser(baseUrl);
+  await done;
+}
+
+if (import.meta.main) {
+  await run();
+}

package/src/config.ts

@@ -0,0 +1,52 @@
+import { mkdir } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+import type { AppCredentials } from "./github.ts";
+
+export interface ConfigPaths {
+  configDir: string;
+  pemPath: string;
+  envPath: string;
+}
+
+export const DEFAULT_ENV_FILE = ".env.github-app";
+export const DEFAULT_PEM_NAME = "dev-ui-bot.pem";
+
+export function defaultConfigPaths(cwd: string = process.cwd()): ConfigPaths {
+  const configDir = join(homedir(), ".config", "auto-agents");
+  return {
+    configDir,
+    pemPath: join(configDir, DEFAULT_PEM_NAME),
+    envPath: join(cwd, DEFAULT_ENV_FILE),
+  };
+}
+
+export function formatEnvFile(
+  app: AppCredentials,
+  pemPath: string,
+  now: Date = new Date(),
+): string {
+  return [
+    `# Generated by auto-agents-github-app-installer on ${now.toISOString()}`,
+    `# Install the app at ${app.html_url}/installations/new then fill in DEV_BOT_INSTALLATION_ID below.`,
+    `DEV_BOT_APP_ID=${app.id}`,
+    `DEV_BOT_INSTALLATION_ID=`,
+    `DEV_BOT_PRIVATE_KEY=${pemPath}`,
+    `# Reference values (not consumed by auto-agents):`,
+    `CLIENT_ID=${app.client_id}`,
+    `CLIENT_SECRET=${app.client_secret}`,
+    `WEBHOOK_SECRET=${app.webhook_secret}`,
+    "",
+  ].join("\n");
+}
+
+export async function writeAppCredentials(
+  app: AppCredentials,
+  paths: ConfigPaths,
+): Promise<void> {
+  await mkdir(paths.configDir, { recursive: true, mode: 0o700 });
+  await Bun.write(paths.pemPath, app.pem);
+  await Bun.$`chmod 600 ${paths.pemPath}`.quiet();
+  await Bun.write(paths.envPath, formatEnvFile(app, paths.pemPath));
+}

package/src/github.ts

@@ -0,0 +1,35 @@
+export interface AppCredentials {
+  id: number;
+  html_url: string;
+  pem: string;
+  client_id: string;
+  client_secret: string;
+  webhook_secret: string;
+}
+
+export type FetchLike = (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
+
+export async function convertCode(
+  code: string,
+  fetchImpl: FetchLike = fetch,
+): Promise<AppCredentials> {
+  const res = await fetchImpl(
+    `https://api.github.com/app-manifests/${code}/conversions`,
+    {
+      method: "POST",
+      headers: {
+        accept: "application/vnd.github+json",
+        "x-github-api-version": "2022-11-28",
+        "user-agent": "auto-agents-github-app-manifest",
+      },
+    },
+  );
+
+  if (!res.ok) {
+    throw new Error(
+      `GitHub manifest conversion failed (${res.status}): ${await res.text()}`,
+    );
+  }
+
+  return (await res.json()) as AppCredentials;
+}

package/src/handler.ts

@@ -0,0 +1,68 @@
+import type { AppCredentials } from "./github.ts";
+import type { AppManifest } from "./manifest.ts";
+import { githubNewAppUrl } from "./manifest.ts";
+
+export interface HandlerDeps {
+  manifest: AppManifest;
+  state: string;
+  owner?: string;
+  exchangeCode: (code: string) => Promise<AppCredentials>;
+  onSuccess: (app: AppCredentials) => Promise<{ pemPath: string; envPath: string }>;
+}
+
+export function createHandler(deps: HandlerDeps): (req: Request) => Promise<Response> {
+  return async (req) => {
+    const url = new URL(req.url);
+
+    if (url.pathname === "/") {
+      const manifestJson = JSON.stringify(deps.manifest).replaceAll("'", "&apos;");
+      const action = githubNewAppUrl(deps.state, deps.owner);
+      return new Response(
+        `<!doctype html>
+<form id="f" action="${action}" method="post">
+  <input type="hidden" name="manifest" value='${manifestJson}' />
+  <button>Create GitHub App</button>
+</form>
+<script>document.getElementById("f").submit()</script>`,
+        { headers: { "content-type": "text/html" } },
+      );
+    }
+
+    if (url.pathname === "/callback") {
+      if (url.searchParams.get("state") !== deps.state) {
+        return new Response("Invalid state", { status: 400 });
+      }
+      const code = url.searchParams.get("code");
+      if (!code) return new Response("Missing code", { status: 400 });
+
+      let app: AppCredentials;
+      try {
+        app = await deps.exchangeCode(code);
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return new Response(msg, { status: 502 });
+      }
+
+      const { pemPath, envPath } = await deps.onSuccess(app);
+
+      return new Response(
+        [
+          `Created GitHub App: ${app.html_url}`,
+          ``,
+          `Wrote:`,
+          `  ${pemPath}  (private key, chmod 600)`,
+          `  ${envPath}                (DEV_BOT_APP_ID, DEV_BOT_PRIVATE_KEY)`,
+          ``,
+          `Next steps:`,
+          `  1. Install the app on your repo: ${app.html_url}/installations/new`,
+          `  2. Copy the installation ID from the URL and set DEV_BOT_INSTALLATION_ID in ${envPath}.`,
+          `  3. source ${envPath} && auto-agents`,
+          ``,
+        ].join("\n"),
+        { headers: { "content-type": "text/plain" } },
+      );
+    }
+
+    return new Response("Not found", { status: 404 });
+  };
+}

package/src/index.ts

@@ -0,0 +1,25 @@
+export { run } from "./cli.ts";
+export type { RunOptions } from "./cli.ts";
+
+export {
+  buildManifest,
+  githubNewAppUrl,
+  DEFAULT_HOMEPAGE_URL,
+  DEFAULT_HOOK_URL,
+} from "./manifest.ts";
+export type { AppManifest, ManifestOptions } from "./manifest.ts";
+
+export { convertCode } from "./github.ts";
+export type { AppCredentials, FetchLike } from "./github.ts";
+
+export {
+  defaultConfigPaths,
+  formatEnvFile,
+  writeAppCredentials,
+  DEFAULT_ENV_FILE,
+  DEFAULT_PEM_NAME,
+} from "./config.ts";
+export type { ConfigPaths } from "./config.ts";
+
+export { createHandler } from "./handler.ts";
+export type { HandlerDeps } from "./handler.ts";

package/src/manifest.ts

@@ -0,0 +1,48 @@
+export interface ManifestOptions {
+  appName: string;
+  baseUrl: string;
+  homepageUrl?: string;
+  hookUrl?: string;
+}
+
+export interface AppManifest {
+  name: string;
+  url: string;
+  hook_attributes: { url: string; active: boolean };
+  redirect_url: string;
+  callback_urls: string[];
+  public: boolean;
+  default_permissions: Record<string, string>;
+  default_events: string[];
+}
+
+export const DEFAULT_HOMEPAGE_URL = "https://github.com/geoffsee/auto-agents";
+
+// GitHub rejects manifests whose hook URL isn't publicly reachable, even when
+// active=false. auto-agents doesn't consume webhooks for this dev bot, so default
+// to a placeholder that passes validation; callers can override via hookUrl.
+export const DEFAULT_HOOK_URL = "https://example.com/auto-agents-webhook";
+
+export function buildManifest(opts: ManifestOptions): AppManifest {
+  return {
+    name: opts.appName,
+    url: opts.homepageUrl ?? DEFAULT_HOMEPAGE_URL,
+    hook_attributes: { url: opts.hookUrl ?? DEFAULT_HOOK_URL, active: false },
+    redirect_url: `${opts.baseUrl}/callback`,
+    callback_urls: [`${opts.baseUrl}/callback`],
+    public: false,
+    default_permissions: {
+      contents: "read",
+      pull_requests: "write",
+      issues: "write",
+      metadata: "read",
+    },
+    default_events: [],
+  };
+}
+
+export function githubNewAppUrl(state: string, owner?: string): string {
+  return owner
+    ? `https://github.com/organizations/${owner}/settings/apps/new?state=${state}`
+    : `https://github.com/settings/apps/new?state=${state}`;
+}