co-maintainer 0.4.13 → 0.5.0-beta.1

package/dist/src/cli/review_result.js

@@ -1,6 +1,7 @@
 import { parseFindings } from "../pr/findings.js";
 import { readSuggestion, stripSuggestion } from "../pr/suggestion.js";
 import { anchorTextFromPatch, } from "../review/carry_over.js";
+import { DEFAULT_REVIEW_BLOCKING, isBlocking, } from "../review/blocking.js";
 import { humanCopy } from "../services/review.js";
 const SEVERITY_RANK = {
     P0: 0,
@@ -8,12 +9,8 @@ const SEVERITY_RANK = {
     P2: 2,
     P3: 3,
 };
-export function isBlockingFinding(title, severity) {
-    if (/\[P0\b/i.test(title) || /^P0$/i.test(severity))
-        return true;
-    if (/\[P\d\s*·\s*blocking\]/i.test(title))
-        return true;
-    return false;
+export function isBlockingFinding(title, severity, mode = DEFAULT_REVIEW_BLOCKING) {
+    return isBlocking(mode, { severity, text: title });
 }
 export function resolvedFromFirstReview(parsed, filesByPath) {
     return parsed.map((finding) => {
@@ -54,14 +51,14 @@ function compareFindings(a, b) {
 export function sortResolvedFindings(findings) {
     return [...findings].sort(compareFindings);
 }
-export function toJsonFinding(row) {
+export function toJsonFinding(row, mode = DEFAULT_REVIEW_BLOCKING) {
     const suggestion = readSuggestion(row.bodyMd);
     return {
         id: row.id,
         state: row.state,
         closeReason: row.closeReason ?? null,
         severity: row.severity,
-        blocking: isBlockingFinding(row.title, row.severity),
+        blocking: isBlockingFinding(row.title, row.severity, mode),
         path: row.path,
         lineFrom: row.lineFrom,
         lineTo: row.lineTo,
@@ -90,11 +87,11 @@ export function revisionStats(revision) {
         truncated: false,
     };
 }
-export function summaryCounts(findings) {
+export function summaryCounts(findings, mode = DEFAULT_REVIEW_BLOCKING) {
     let blocking = 0;
     for (const row of findings) {
         if ((row.state === "new" || row.state === "open") &&
-            isBlockingFinding(row.title, row.severity)) {
+            isBlockingFinding(row.title, row.severity, mode)) {
             blocking++;
         }
     }
@@ -105,10 +102,50 @@ export function summaryCounts(findings) {
         blocking,
     };
 }
-export function reviewExitCodeFromResolved(findings) {
-    return summaryCounts(findings).blocking > 0 ? 1 : 0;
+export function reviewExitCodeFromResolved(findings, mode = DEFAULT_REVIEW_BLOCKING) {
+    return summaryCounts(findings, mode).blocking > 0 ? 1 : 0;
 }
-function locationLabel(row) {
+/** Local and PR findings: blocking is decided here from the configured rule,
+ * exactly as the exit code decides it (CORE-41). */
+export function humanFindingsFromResolved(findings, mode = DEFAULT_REVIEW_BLOCKING) {
+    return findings.map((row) => {
+        const suggestion = readSuggestion(row.bodyMd);
+        return {
+            state: row.state,
+            severity: row.severity,
+            blocking: isBlockingFinding(row.title, row.severity, mode),
+            path: row.path,
+            lineFrom: row.lineFrom,
+            lineTo: row.lineTo,
+            title: humanCopy(row.title),
+            body: humanCopy(stripSuggestion(row.bodyMd)).trim(),
+            suggestion: suggestion
+                ? {
+                    lineFrom: suggestion.from,
+                    lineTo: suggestion.to,
+                    text: suggestion.code,
+                }
+                : null,
+        };
+    });
+}
+/** Remote findings already carry the server's blocking decision, so the label
+ * uses that field rather than re-deriving the rule on a client that may not
+ * share the server's config (CORE-41). */
+export function humanFindingsFromJson(findings) {
+    return findings.map((row) => ({
+        state: row.state,
+        severity: row.severity,
+        blocking: row.blocking,
+        path: row.path,
+        lineFrom: row.lineFrom,
+        lineTo: row.lineTo,
+        title: row.title,
+        body: row.body.trim(),
+        suggestion: row.suggestion,
+    }));
+}
+function humanLocation(row) {
     if (!row.path)
         return row.title;
     const from = row.lineFrom ?? 0;
@@ -116,37 +153,59 @@ function locationLabel(row) {
     const span = from === to ? `${from}` : `${from}-${to}`;
     return `${row.path}:${span}`;
 }
-function shortTitle(row) {
-    const title = humanCopy(row.title);
-    const dash = title.indexOf(" — ");
-    return dash === -1
-        ? title
-        : title
-            .slice(dash + 3)
-            .replace(/^`|`$/g, "")
-            .trim();
+/** The finding heading, as the shared header prints it. A parsed heading is
+ * `[P2 · non-blocking] \`path\`: \`symbol\``. The label and the location are
+ * already printed beside it, so only the symbol survives. An older heading
+ * that used an em dash is still accepted, so comments posted before 0.5.0
+ * stay readable. A heading with no symbol leaves nothing: printing the label
+ * or the path again would repeat what the line already says (CORE-43). */
+function humanShortTitle(row) {
+    const withoutLabel = row.title.replace(/^\[P\d\s*·\s*[^\]]*\]\s*/, "");
+    const dash = withoutLabel.indexOf(" — ");
+    const tail = dash === -1 ? withoutLabel : withoutLabel.slice(dash + 3);
+    const colon = tail.indexOf(": ");
+    const symbol = colon === -1 ? tail : tail.slice(colon + 2);
+    const clean = symbol.replace(/^`|`$/g, "").trim();
+    return clean === "" || clean === row.path ? "" : clean;
 }
-function impactLabel(row) {
-    const blocking = isBlockingFinding(row.title, row.severity);
-    return `[${row.severity} · ${blocking ? "blocking" : "non-blocking"}]`;
+function sortHumanFindings(rows) {
+    const stateOrder = { new: 0, open: 1, closed: 2 };
+    return [...rows].sort((a, b) => {
+        const ds = stateOrder[a.state] - stateOrder[b.state];
+        if (ds !== 0)
+            return ds;
+        const sa = SEVERITY_RANK[a.severity] ?? 9;
+        const sb = SEVERITY_RANK[b.severity] ?? 9;
+        if (sa !== sb)
+            return sa - sb;
+        const pa = a.path ?? "";
+        const pb = b.path ?? "";
+        if (pa !== pb)
+            return pa.localeCompare(pb);
+        return (a.lineFrom ?? 0) - (b.lineFrom ?? 0);
+    });
 }
-/** Plan §9.1 human-readable local review output. */
-export function formatHumanLocalReview(header, revision, guideBuiltAt, codegraphState, findings, warnings) {
-    const stats = revisionStats(revision);
-    const guideBit = guideBuiltAt
-        ? `guide ${guideBuiltAt.slice(0, 10)}`
+/** The single human-readable review format (CORE-43 / F21, F22, F23). Local,
+ * PR and remote reviews print this: a header naming the guide build date and
+ * the codegraph state, the findings grouped by state, then one summary line.
+ *
+ * The severity legend and the "ask for more detail" sentence are deliberately
+ * absent: a terminal has nobody to ask, and the legend is fixed noise. Both
+ * stay in the GitHub comment, which is a different reader. */
+export function formatHumanReview(input) {
+    const guideBit = input.guideBuiltAt
+        ? `guide built ${input.guideBuiltAt.slice(0, 10)}`
         : "guide unknown";
-    const cgBit = codegraphState === "used"
+    const cgBit = input.codegraphState === "used"
         ? "codegraph used"
-        : codegraphState === "disabled"
+        : input.codegraphState === "disabled"
             ? "codegraph disabled"
-            : "codegraph unavailable";
-    const lines = [
-        header,
-        `${stats.files} files · +${stats.additions} −${stats.deletions} · ${guideBit} · ${cgBit}`,
-        "",
-    ];
-    const sorted = sortResolvedFindings(findings);
+            : input.codegraphState === "unavailable"
+                ? "codegraph unavailable"
+                : "codegraph unknown";
+    const meta = [input.stats, guideBit, cgBit].filter(Boolean).join(" · ");
+    const lines = [input.title, meta, ""];
+    const sorted = sortHumanFindings(input.findings);
     const groups = [
         { label: "Closed", state: "closed", bullet: "✓" },
         { label: "Still open", state: "open", bullet: "•" },
@@ -160,25 +219,24 @@ export function formatHumanLocalReview(header, revision, guideBuiltAt, codegraph
         any = true;
         lines.push(`${group.label} (${rows.length})`);
         for (const row of rows) {
-            const loc = locationLabel(row);
-            const head = `${group.bullet} ${loc}  ${impactLabel(row)} ${shortTitle(row)}`;
+            const loc = humanLocation(row);
+            const label = `[${row.severity} · ${row.blocking ? "blocking" : "non-blocking"}]`;
+            const short = humanShortTitle(row);
+            const head = `${group.bullet} ${loc}  ${label}${short ? ` \`${short}\`` : ""}`;
             lines.push(`  ${head}`);
-            if (row.state !== "closed") {
-                const body = humanCopy(stripSuggestion(row.bodyMd)).trim();
-                if (body) {
-                    for (const part of body.split("\n")) {
-                        lines.push(`    ${part}`);
-                    }
-                    const suggestion = readSuggestion(row.bodyMd);
-                    if (suggestion && row.path) {
-                        lines.push(`    Suggested replacement for ${row.path}:${suggestion.from}${suggestion.to !== suggestion.from ? `-${suggestion.to}` : ""}`);
-                        lines.push("    ```");
-                        for (const part of suggestion.code.split("\n")) {
-                            lines.push(`    ${part}`);
-                        }
-                        lines.push("    ```");
-                    }
-                }
+            if (row.state === "closed")
+                continue;
+            if (row.body) {
+                for (const part of row.body.split("\n"))
+                    lines.push(`    ${part}`);
+            }
+            if (row.suggestion && row.path) {
+                const { lineFrom, lineTo, text } = row.suggestion;
+                lines.push(`    Suggested replacement for ${row.path}:${lineFrom}${lineTo !== lineFrom ? `-${lineTo}` : ""}`);
+                lines.push("    ```");
+                for (const part of text.split("\n"))
+                    lines.push(`    ${part}`);
+                lines.push("    ```");
             }
         }
         lines.push("");
@@ -187,58 +245,41 @@ export function formatHumanLocalReview(header, revision, guideBuiltAt, codegraph
         lines.push("No actionable findings.");
         lines.push("");
     }
-    const counts = summaryCounts(findings);
+    const counts = {
+        new: sorted.filter((f) => f.state === "new").length,
+        open: sorted.filter((f) => f.state === "open").length,
+        closed: sorted.filter((f) => f.state === "closed").length,
+        blocking: sorted.filter((f) => (f.state === "new" || f.state === "open") && f.blocking).length,
+    };
     lines.push(`Summary: ${counts.new} new · ${counts.open} open · ${counts.closed} closed · ${counts.blocking} blocking`);
-    if (warnings.length) {
+    if (input.warnings?.length) {
         lines.push("Warnings:");
-        for (const w of warnings)
+        for (const w of input.warnings)
             lines.push(`  - ${w.message}`);
     }
     return lines.join("\n");
 }
-/** Human-readable findings block for remote sync JSON (same shape as `toJsonFinding`). */
-export function formatHumanJsonFindings(findings) {
-    if (findings.length === 0) {
-        return "## Findings\n\nNo actionable findings.";
-    }
-    const lines = ["## Findings", ""];
-    const sorted = [...findings].sort((a, b) => (SEVERITY_RANK[a.severity] ?? 9) - (SEVERITY_RANK[b.severity] ?? 9));
-    for (const row of sorted) {
-        const blocking = row.blocking || isBlockingFinding(row.title, row.severity);
-        const impact = `[${row.severity} · ${blocking ? "blocking" : "non-blocking"}]`;
-        let prefix = "";
-        if (row.path) {
-            const from = row.lineFrom ?? 0;
-            const to = row.lineTo ?? from;
-            const span = from === to ? `${from}` : `${from}-${to}`;
-            prefix = `${row.path}:${span}  `;
-        }
-        lines.push(`- ${prefix}${impact} ${row.title}`);
-        const body = row.body.trim();
-        if (body) {
-            for (const part of body.split("\n")) {
-                lines.push(`  ${part}`);
-            }
-        }
-        if (row.suggestion && row.path) {
-            const { lineFrom, lineTo, text } = row.suggestion;
-            lines.push(`  Suggested replacement for ${row.path}:${lineFrom}${lineTo !== lineFrom ? `-${lineTo}` : ""}`);
-            lines.push("  ```");
-            for (const part of text.split("\n")) {
-                lines.push(`  ${part}`);
-            }
-            lines.push("  ```");
-        }
-        lines.push("");
-    }
-    return lines.join("\n").trimEnd();
+/** Local review output: the shared format plus the working-tree file stats. */
+export function formatHumanLocalReview(header, revision, guideBuiltAt, codegraphState, findings, warnings, mode = DEFAULT_REVIEW_BLOCKING) {
+    const stats = revisionStats(revision);
+    return formatHumanReview({
+        title: header,
+        stats: `${stats.files} files · +${stats.additions} −${stats.deletions}`,
+        guideBuiltAt,
+        codegraphState,
+        findings: humanFindingsFromResolved(findings, mode),
+        warnings,
+    });
 }
+/** The exit code for a remote review (CORE-41). The server already decided
+ * each finding's `blocking` under its own configured rule, so the client
+ * trusts that field instead of re-deriving the rule from a title: the client
+ * may not even have the same config as the server. */
 export function reviewExitCodeFromJsonFindings(findings) {
-    return findings.some((f) => f.blocking || isBlockingFinding(f.title, f.severity))
-        ? 1
-        : 0;
+    return findings.some((f) => f.blocking) ? 1 : 0;
 }
 export function buildPrReviewJson(input) {
+    const mode = input.reviewBlocking ?? DEFAULT_REVIEW_BLOCKING;
     const findings = resolvedFromFirstReview(parseFindings(input.markdown), new Map());
     const sorted = sortResolvedFindings(findings);
     return JSON.stringify({
@@ -251,14 +292,15 @@ export function buildPrReviewJson(input) {
             state: input.codegraphState,
             reason: input.codegraphReason,
         },
-        summary: summaryCounts(findings),
-        findings: sorted.map(toJsonFinding),
+        summary: summaryCounts(findings, mode),
+        findings: sorted.map((row) => toJsonFinding(row, mode)),
         warnings: [],
         usage: input.usage,
         durationMs: input.durationMs,
     });
 }
 export function buildLocalReviewJson(input) {
+    const mode = input.reviewBlocking ?? DEFAULT_REVIEW_BLOCKING;
     const sorted = sortResolvedFindings(input.findings);
     return JSON.stringify({
         schemaVersion: 1,
@@ -272,8 +314,8 @@ export function buildLocalReviewJson(input) {
             state: input.codegraphState,
             reason: input.codegraphReason,
         },
-        summary: summaryCounts(input.findings),
-        findings: sorted.map(toJsonFinding),
+        summary: summaryCounts(input.findings, mode),
+        findings: sorted.map((row) => toJsonFinding(row, mode)),
         warnings: input.warnings,
         usage: input.usage,
         durationMs: input.durationMs,

package/dist/src/config.d.ts

@@ -37,6 +37,9 @@ export type UserConfig = {
      * written by `set`. `githubWebhookSecret` is optional. */
     githubAppId?: string;
     githubAppPrivateKey?: string;
+    /** Path to the App private key file, kept as a path so the key is never
+     * copied into config.json. An inline `githubAppPrivateKey` wins over it. */
+    githubAppPrivateKeyPath?: string;
     githubWebhookSecret?: string;
     webhookUrl?: string;
     /** "Sign in with GitHub" for the dashboard, reusing the App's own OAuth
@@ -58,6 +61,9 @@ export type UserConfig = {
     };
     /** Cap on jobs running at once across all types. Unset means no limit. */
     maxConcurrentJobs?: number;
+    /** What a review uses to decide a blocking finding (CORE-41). `model` lets
+     * the model's own severity decide, `severity` uses a fixed threshold. */
+    reviewBlocking?: "model" | "severity";
     /** Remote review CLI target (`co-maintainer set`). */
     remoteHost?: string;
     /** Bearer token for `/api/remote/*`; only written by `set`. */
@@ -101,6 +107,15 @@ export declare function worktreeDir(repo: string, pr: number): string;
 export declare function cacheDbPath(): string;
 export declare function loadEnvFile(path: string): void;
 export declare function readConfig(): UserConfig;
+/** The App private key to sign with. An inline `githubAppPrivateKey` wins,
+ * then the file named by `githubAppPrivateKeyPath`. Reading the file here
+ * instead of copying it into config.json keeps a key on disk in one place.
+ * `undefined` when neither is set or the named file cannot be read, which is
+ * the same as "App not configured" to every caller. */
+export declare function resolveAppPrivateKey(config: Pick<UserConfig, "githubAppPrivateKey" | "githubAppPrivateKeyPath">): string | undefined;
+/** `true` when a path is configured but the file is missing or unreadable,
+ * so `serve` can warn at startup instead of looking silently unconfigured. */
+export declare function appPrivateKeyFileMissing(config: Pick<UserConfig, "githubAppPrivateKey" | "githubAppPrivateKeyPath">): boolean;
 /** Merges `patch` into `repos[repo]` in config.json, dropping undefined
  * fields. Never call this with a token or other secret. */
 export declare function writeRepoConfig(repo: string, patch: RepoConfig): Promise<void>;

package/dist/src/config.js

@@ -100,6 +100,37 @@ export function readConfig() {
         throw new Error(`Could not read config ${configPath()}: ${String(error)}`);
     }
 }
+/** The App private key to sign with. An inline `githubAppPrivateKey` wins,
+ * then the file named by `githubAppPrivateKeyPath`. Reading the file here
+ * instead of copying it into config.json keeps a key on disk in one place.
+ * `undefined` when neither is set or the named file cannot be read, which is
+ * the same as "App not configured" to every caller. */
+export function resolveAppPrivateKey(config) {
+    if (config.githubAppPrivateKey)
+        return config.githubAppPrivateKey;
+    if (!config.githubAppPrivateKeyPath)
+        return undefined;
+    try {
+        return readTextFileSync(config.githubAppPrivateKeyPath);
+    }
+    catch {
+        return undefined;
+    }
+}
+/** `true` when a path is configured but the file is missing or unreadable,
+ * so `serve` can warn at startup instead of looking silently unconfigured. */
+export function appPrivateKeyFileMissing(config) {
+    if (config.githubAppPrivateKey || !config.githubAppPrivateKeyPath) {
+        return false;
+    }
+    try {
+        readTextFileSync(config.githubAppPrivateKeyPath);
+        return false;
+    }
+    catch {
+        return true;
+    }
+}
 async function writeConfig(config) {
     await mkdir(`${getConfigDir()}/co-maintainer`, { recursive: true });
     const path = configPath();

package/dist/src/github/app.d.ts

@@ -40,4 +40,17 @@ export type InstallationRepos = {
 /** For `GET /api/installations`: every installation the App has, each with
  * the repos it can see. */
 export declare function listInstallationsWithRepos(appId: string, privateKeyPem: string): Promise<InstallationRepos[]>;
+export type OpenPull = {
+    number: number;
+    title: string;
+    draft: boolean;
+    author: string;
+    headRef: string;
+    updatedAt: string;
+};
+/** Open, non-draft pull requests for one repository through the installation
+ * that can see it, for the Pull requests tab. `undefined` when no installation
+ * covers the repo, so the caller can tell "not installed" from "none open"
+ * instead of showing an empty list for a setup mistake. */
+export declare function listOpenPulls(appId: string, privateKeyPem: string, fullName: string): Promise<OpenPull[] | undefined>;
 export declare function findInstallationForRepo(appId: string, privateKeyPem: string, fullName: string): Promise<number | undefined>;

package/dist/src/github/app.js

@@ -112,6 +112,29 @@ export async function listInstallationsWithRepos(appId, privateKeyPem) {
     }
     return result;
 }
+/** Open, non-draft pull requests for one repository through the installation
+ * that can see it, for the Pull requests tab. `undefined` when no installation
+ * covers the repo, so the caller can tell "not installed" from "none open"
+ * instead of showing an empty list for a setup mistake. */
+export async function listOpenPulls(appId, privateKeyPem, fullName) {
+    const installationId = await findInstallationForRepo(appId, privateKeyPem, fullName);
+    if (installationId === undefined)
+        return undefined;
+    const client = new AppClient(appId, privateKeyPem, installationId);
+    const [owner, repo] = fullName.split("/");
+    const raw = await client.pages(`repos/${owner}/${repo}/pulls?state=open&sort=updated&direction=desc`, 100);
+    return raw
+        .filter((pull) => pull.draft !== true)
+        .map((pull) => ({
+        number: Number(pull.number ?? 0),
+        title: String(pull.title ?? ""),
+        draft: false,
+        author: String(pull.user?.login ?? ""),
+        headRef: String(pull.head?.ref ?? ""),
+        updatedAt: String(pull.updated_at ?? ""),
+    }))
+        .filter((pull) => Number.isSafeInteger(pull.number) && pull.number > 0);
+}
 export async function findInstallationForRepo(appId, privateKeyPem, fullName) {
     const normalized = fullName.toLowerCase();
     const installations = await listInstallationsWithRepos(appId, privateKeyPem);

package/dist/src/github/app_manifest.d.ts

@@ -0,0 +1,50 @@
+export declare const APP_MANIFEST_PERMISSIONS: {
+    readonly contents: "read";
+    readonly issues: "write";
+    readonly pull_requests: "write";
+    readonly checks: "write";
+    readonly metadata: "read";
+};
+export declare const APP_MANIFEST_EVENTS: readonly ["pull_request", "pull_request_review", "pull_request_review_comment", "issue_comment"];
+/** GitHub App names are globally unique and capped at 34 characters. */
+export declare const APP_NAME_MAX = 34;
+export type 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 declare function buildAppManifest(input: {
+    name: string;
+    baseUrl: string;
+    webhookUrl: string;
+}): AppManifest;
+/** `co-maintainer-<host>`, shortened to fit the 34 character cap. The name
+ * is only a suggestion: GitHub rejects a duplicate and the field stays
+ * editable. */
+export declare function defaultAppName(host: string): string;
+export declare function appNameProblem(name: string): string | undefined;
+/** Why the App cannot be created yet, or `undefined` when its webhook
+ * address looks reachable from GitHub. */
+export declare function manifestBlockedReason(webhookUrl: string): string | undefined;
+export type ManifestConversion = {
+    appId: string;
+    slug: string;
+    pem: string;
+    webhookSecret: string;
+    clientId: string;
+    clientSecret: string;
+};
+/** `POST /app-manifests/{code}/conversions` — the `code` is single use and
+ * expires roughly an hour after GitHub redirects the browser back. */
+export declare function convertManifest(code: string): Promise<ManifestConversion>;
+export declare function beginManifestState(now?: number): string;
+/** `false` for an unknown state, a replayed one, or an expired one. */
+export declare function consumeManifestState(state: string, now?: number): boolean;

package/dist/src/github/app_manifest.js

@@ -0,0 +1,138 @@
+/** The GitHub App manifest flow: create the App from the dashboard so its
+ * webhook secret, private key, and OAuth credentials are written straight
+ * into config.json instead of being copied by hand between two screens.
+ *
+ * Permissions and events are derived from the calls this codebase actually
+ * makes, not guessed:
+ *  - `contents: read`   read PR_REVIEW_GUIDE.md, file contents, git trees
+ *  - `pull_requests: write`  post reviews and review comments, read a PR
+ *  - `issues: write`    post issue comments, read them
+ *  - `checks: write`    create and update the review check run
+ *  - `metadata: read`   required by every App
+ *  - events             handled by `dispatchGithubEvent` in services/webhook.ts
+ *
+ * `installation` and `installation_repositories` are deliberately absent:
+ * GitHub delivers both to every App without a subscription, which is why
+ * `webhook.ts` handles them at all. */
+import { githubFetch } from "./client.js";
+import { webhookReachabilityProblem } from "../util/webhook_reachability.js";
+export const APP_MANIFEST_PERMISSIONS = {
+    contents: "read",
+    issues: "write",
+    pull_requests: "write",
+    checks: "write",
+    metadata: "read",
+};
+export const APP_MANIFEST_EVENTS = [
+    "pull_request",
+    "pull_request_review",
+    "pull_request_review_comment",
+    "issue_comment",
+];
+/** GitHub App names are globally unique and capped at 34 characters. */
+export const APP_NAME_MAX = 34;
+export function buildAppManifest(input) {
+    const base = input.baseUrl.replace(/\/+$/, "");
+    return {
+        name: input.name.trim(),
+        url: base,
+        hook_attributes: { url: input.webhookUrl, active: true },
+        redirect_url: `${base}/github/app-manifest/callback`,
+        callback_urls: [`${base}/auth/github/callback`],
+        public: false,
+        default_permissions: { ...APP_MANIFEST_PERMISSIONS },
+        default_events: [...APP_MANIFEST_EVENTS],
+    };
+}
+/** `co-maintainer-<host>`, shortened to fit the 34 character cap. The name
+ * is only a suggestion: GitHub rejects a duplicate and the field stays
+ * editable. */
+export function defaultAppName(host) {
+    const clean = host
+        .toLowerCase()
+        .replace(/[^a-z0-9-]+/g, "-")
+        .replace(/^-+|-+$/g, "");
+    const name = `co-maintainer-${clean}`;
+    return name.length <= APP_NAME_MAX
+        ? name
+        : name.slice(0, APP_NAME_MAX).replace(/-+$/, "");
+}
+export function appNameProblem(name) {
+    const trimmed = name.trim();
+    if (!trimmed)
+        return "Enter a name for the GitHub App.";
+    if (trimmed.length > APP_NAME_MAX) {
+        return `The name must be ${APP_NAME_MAX} characters or fewer.`;
+    }
+    if (!/^[A-Za-z0-9][A-Za-z0-9-]*$/.test(trimmed)) {
+        return "Use letters, digits, and hyphens only, starting with a letter or digit.";
+    }
+    return undefined;
+}
+/** Why the App cannot be created yet, or `undefined` when its webhook
+ * address looks reachable from GitHub. */
+export function manifestBlockedReason(webhookUrl) {
+    if (!webhookUrl.trim()) {
+        return "Set a webhook address before creating the App.";
+    }
+    const reach = webhookReachabilityProblem(webhookUrl);
+    if (reach)
+        return `${reach} Set a public webhook address first.`;
+    return undefined;
+}
+/** `POST /app-manifests/{code}/conversions` — the `code` is single use and
+ * expires roughly an hour after GitHub redirects the browser back. */
+export async function convertManifest(code) {
+    const response = await githubFetch(`https://api.github.com/app-manifests/${encodeURIComponent(code)}/conversions`, {
+        method: "POST",
+        headers: {
+            accept: "application/vnd.github+json",
+            "content-type": "application/json",
+        },
+    });
+    if (!response.ok) {
+        throw new Error(`GitHub App conversion failed (${response.status}).`);
+    }
+    const body = (await response.json());
+    const text = (value) => (typeof value === "string" ? value : "");
+    const id = body.id;
+    const appId = typeof id === "number" ? String(id) : typeof id === "string" ? id : "";
+    if (!appId || !text(body.pem)) {
+        throw new Error("GitHub returned an incomplete App conversion.");
+    }
+    return {
+        appId,
+        slug: text(body.slug),
+        pem: text(body.pem),
+        webhookSecret: text(body.webhook_secret),
+        clientId: text(body.client_id),
+        clientSecret: text(body.client_secret),
+    };
+}
+/** One dashboard admin, one in-flight App creation at a time, so a
+ * server-side map is enough. A cookie would work too, but keeping the token
+ * out of the browser is one less thing to forge. Expired entries are swept
+ * on the next start, and a state is single use. */
+const MANIFEST_STATE_TTL_MS = 10 * 60 * 1000;
+const pendingStates = new Map();
+function randomState() {
+    const bytes = crypto.getRandomValues(new Uint8Array(16));
+    return Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+export function beginManifestState(now = Date.now()) {
+    for (const [state, expires] of pendingStates) {
+        if (expires <= now)
+            pendingStates.delete(state);
+    }
+    const state = randomState();
+    pendingStates.set(state, now + MANIFEST_STATE_TTL_MS);
+    return state;
+}
+/** `false` for an unknown state, a replayed one, or an expired one. */
+export function consumeManifestState(state, now = Date.now()) {
+    const expires = pendingStates.get(state);
+    if (expires === undefined)
+        return false;
+    pendingStates.delete(state);
+    return expires > now;
+}