@devdogsuga/devtools 0.1.0

package/dist/gh/rulesets/actors.js

@@ -0,0 +1,68 @@
+/**
+ * Resolves the numeric ids `desired.ts`'s bypass actors need, by NAME —
+ * never hardcoded, because a team or App id is only stable until somebody
+ * deletes and recreates it, and a stale id in a bypass actor is the
+ * dangerous failure: the ruleset then blocks the team or App it is named
+ * for while letting whoever inherited the old id through (the same
+ * reasoning `teamSync.ts`'s `ensureTeamRuleset` gives for always re-writing
+ * rather than skipping on an existing ruleset).
+ *
+ * Both come from plain, read-only `gh api` GETs — no Octokit, same as every
+ * other GitHub call in this package.
+ */
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { GhRulesetsError } from "./api.js";
+const run = promisify(execFile);
+function describe(err) {
+    const e = err;
+    const stderr = (e.stderr ?? "").trim();
+    return stderr || e.message || "gh failed with no output.";
+}
+/** `GET /orgs/{org}/teams/{slug}` -> the team's numeric id. */
+export async function resolveTeamId(org, slug) {
+    try {
+        const { stdout } = await run("gh", ["api", `orgs/${org}/teams/${slug}`], {
+            shell: false,
+        });
+        const data = JSON.parse(stdout);
+        if (typeof data.id !== "number") {
+            throw new GhRulesetsError(`orgs/${org}/teams/${slug} returned no numeric id`);
+        }
+        return data.id;
+    }
+    catch (err) {
+        if (err instanceof GhRulesetsError)
+            throw err;
+        throw new GhRulesetsError(`resolving team "${slug}" in ${org}: ${describe(err)}`);
+    }
+}
+/**
+ * `GET /orgs/{org}/installations` -> the id of the App installation whose
+ * `app_slug` matches, e.g. `devdogs-platform` (production) or
+ * `devdogs-platform-staging`.
+ *
+ * `orgs/{org}/installations` rather than the App's own `/app` endpoint: the
+ * latter needs App-JWT auth this CLI has no path to, while the installations
+ * list is a plain org-admin GET — the exact command DevDogsUGA's own
+ * `docs/platform/guides/identity/github-app.md` already tells an operator to
+ * run to verify the App's permission grant.
+ */
+export async function resolveAppId(org, appSlug) {
+    try {
+        const { stdout } = await run("gh", ["api", `orgs/${org}/installations`], {
+            shell: false,
+        });
+        const data = JSON.parse(stdout);
+        const match = (data.installations ?? []).find((i) => i.app_slug === appSlug);
+        if (!match) {
+            throw new GhRulesetsError(`no installation with app_slug "${appSlug}" found in orgs/${org}/installations`);
+        }
+        return match.app_id;
+    }
+    catch (err) {
+        if (err instanceof GhRulesetsError)
+            throw err;
+        throw new GhRulesetsError(`resolving App "${appSlug}" in ${org}: ${describe(err)}`);
+    }
+}

package/dist/gh/rulesets/api.d.ts

@@ -0,0 +1,15 @@
+import type { DesiredRuleset, LiveRuleset, LiveRulesetSummary } from "./types.js";
+export declare class GhRulesetsError extends Error {
+}
+/** `owner/repo`, e.g. `DevDogsUGA/DevDogsUGA`. */
+export interface Repo {
+    owner: string;
+    repo: string;
+}
+/** `GET /repos/{owner}/{repo}/rulesets` — id, name and target only. */
+export declare function listRulesets(r: Repo): Promise<LiveRulesetSummary[]>;
+/** `GET /repos/{owner}/{repo}/rulesets/{id}` — the full ruleset. */
+export declare function getRuleset(r: Repo, id: number): Promise<LiveRuleset>;
+export declare function createRuleset(r: Repo, desired: DesiredRuleset): Promise<LiveRuleset>;
+export declare function updateRuleset(r: Repo, id: number, desired: DesiredRuleset): Promise<LiveRuleset>;
+export declare function deleteRuleset(r: Repo, id: number): Promise<void>;

package/dist/gh/rulesets/api.js

@@ -0,0 +1,99 @@
+/**
+ * `gh api` calls this reconciler needs: listing and reading rulesets, and
+ * writing them (create/update/delete).
+ *
+ * `gh`, not Octokit — devtools has no Octokit dependency, and every other
+ * GitHub call in this package (`../client.ts`) already goes through the
+ * `gh` CLI for the same reason `bws` goes through its own CLI: `gh` already
+ * owns authentication (a contributor's `gh auth login`, or `GH_TOKEN` in
+ * CI), and re-deriving that here would mean a second credential path to
+ * keep in step with the first.
+ *
+ * Reads (`listRulesets`, `getRuleset`) run unauthenticated-safe GETs and are
+ * always allowed. Writes (`createRuleset`, `updateRuleset`, `deleteRuleset`)
+ * need `admin` on the repository — the same requirement `gh api
+ * .../rulesets -X POST` has always had — and `commands.ts` is the only
+ * caller that reaches them, gated behind `--apply`.
+ */
+import { execFile, spawn } from "node:child_process";
+import { promisify } from "node:util";
+const run = promisify(execFile);
+const MAX_BUFFER = 16 * 1024 * 1024;
+export class GhRulesetsError extends Error {
+}
+function describe(err) {
+    const e = err;
+    const stderr = (e.stderr ?? "").trim();
+    return stderr || e.message || "gh failed with no output.";
+}
+function path(r, suffix = "") {
+    return `repos/${r.owner}/${r.repo}/rulesets${suffix}`;
+}
+/** `GET /repos/{owner}/{repo}/rulesets` — id, name and target only. */
+export async function listRulesets(r) {
+    try {
+        const { stdout } = await run("gh", ["api", path(r), "--paginate"], {
+            maxBuffer: MAX_BUFFER,
+            shell: false,
+        });
+        return stdout.trim() === "" ? [] : JSON.parse(stdout);
+    }
+    catch (err) {
+        throw new GhRulesetsError(describe(err));
+    }
+}
+/** `GET /repos/{owner}/{repo}/rulesets/{id}` — the full ruleset. */
+export async function getRuleset(r, id) {
+    try {
+        const { stdout } = await run("gh", ["api", path(r, `/${id}`)], {
+            maxBuffer: MAX_BUFFER,
+            shell: false,
+        });
+        return JSON.parse(stdout);
+    }
+    catch (err) {
+        throw new GhRulesetsError(describe(err));
+    }
+}
+/**
+ * Runs `gh api <path> -X <method> --input -`, writing `body` on stdin (JSON)
+ * and returning the parsed JSON response.
+ *
+ * stdin, not `-f`/`-F` field flags: this reconciler always sends the WHOLE
+ * ruleset payload as one JSON document (the shape `desired.ts` already
+ * builds), and `gh api`'s field flags exist for building that document one
+ * key at a time from shell arguments — a worse fit than handing over the
+ * object this code already has. Not `-X POST --input path` via a temp file
+ * either: stdin needs no cleanup and cannot be left behind by a crash.
+ */
+async function writeJson(method, apiPath, body) {
+    return new Promise((resolve, reject) => {
+        const child = spawn("gh", ["api", apiPath, "-X", method, "--input", "-"], {
+            stdio: ["pipe", "pipe", "pipe"],
+            shell: false,
+        });
+        let stdout = "";
+        let stderr = "";
+        child.stdout.on("data", (c) => (stdout += c.toString()));
+        child.stderr.on("data", (c) => (stderr += c.toString()));
+        child.on("error", (err) => reject(new GhRulesetsError(describe(err))));
+        child.on("close", (code) => {
+            if (code !== 0) {
+                reject(new GhRulesetsError(describe({ stderr })));
+                return;
+            }
+            const trimmed = stdout.trim();
+            resolve(trimmed === "" ? {} : JSON.parse(trimmed));
+        });
+        child.stdin.end(JSON.stringify(body));
+    });
+}
+export async function createRuleset(r, desired) {
+    return writeJson("POST", path(r), desired);
+}
+export async function updateRuleset(r, id, desired) {
+    return writeJson("PATCH", path(r, `/${id}`), desired);
+}
+export async function deleteRuleset(r, id) {
+    await writeJson("DELETE", path(r, `/${id}`), {});
+}

package/dist/gh/rulesets/commands.d.ts

@@ -0,0 +1,3 @@
+import { type RulesetPlan } from "./diff.js";
+export declare function renderPlan(plan: RulesetPlan): string;
+export declare function runGithubRulesets(argv: readonly string[]): Promise<number>;

package/dist/gh/rulesets/commands.js

@@ -0,0 +1,203 @@
+/**
+ * `devtools github rulesets` — TASK-322.
+ *
+ * Prints the diff between the five fixed rulesets DevDogsUGA's
+ * `apps/platform/src/server/github/rulesets.ts` has always assumed exist
+ * (`main`, `production`, `~ALL`, `team/**`, and the tag ruleset — see
+ * `desired.ts`'s header) and what `gh api .../rulesets` actually reports.
+ * Defaults to a dry-run plan; `--apply` writes it, gated behind a
+ * confirmation unless `--yes`.
+ *
+ * Never touches a per-team ruleset (`teamRulesetName()`'s `team/<slug>`) —
+ * those are `teamSync.ts`'s, not this command's — and never deletes or
+ * creates anything outside `desired.ts`'s five names plus the one explicit
+ * deletion (`comp-branches`). See `diff.ts`'s header for the full
+ * classification.
+ */
+import { confirm } from "@clack/prompts";
+import { resolveAppId, resolveTeamId } from "./actors.js";
+import { createRuleset, deleteRuleset, getRuleset, listRulesets, updateRuleset, } from "./api.js";
+import { buildDesiredRulesets, isPerTeamRulesetName } from "./desired.js";
+import { planHasChanges, planRulesets } from "./diff.js";
+import { unwrap } from "../../ui.js";
+const DEFAULT_ORG = "DevDogsUGA";
+const DEFAULT_REPO = "DevDogsUGA";
+const DEFAULT_APP_SLUG = "devdogs-platform";
+const DEFAULT_DEVOPS_SLUG = "devops";
+const DEFAULT_ADMINS_SLUG = "admins";
+/** TASK-299 — installed separately from the platform App; may not exist yet. */
+const DEFAULT_RENOVATE_SLUG = "renovate";
+function parseOptions(argv) {
+    const opts = {
+        org: DEFAULT_ORG,
+        repo: DEFAULT_REPO,
+        appSlug: DEFAULT_APP_SLUG,
+        apply: false,
+        yes: false,
+        json: false,
+    };
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (arg === "--org")
+            opts.org = argv[++i] ?? opts.org;
+        else if (arg === "--repo")
+            opts.repo = argv[++i] ?? opts.repo;
+        else if (arg === "--app-slug")
+            opts.appSlug = argv[++i] ?? opts.appSlug;
+        else if (arg === "--apply")
+            opts.apply = true;
+        else if (arg === "--yes")
+            opts.yes = true;
+        else if (arg === "--json")
+            opts.json = true;
+    }
+    return opts;
+}
+/**
+ * Fetches full detail for every live ruleset EXCEPT per-team ones —
+ * `diff.ts`'s `planRulesets` never reads past a per-team ruleset's name, and
+ * there can be up to ~70 of them, so fetching each would be up to ~70 extra
+ * GETs this reconciler has no use for.
+ */
+async function fetchDetails(r, summaries) {
+    const details = new Map();
+    for (const s of summaries) {
+        if (isPerTeamRulesetName(s.name))
+            continue;
+        details.set(s.id, await getRuleset(r, s.id));
+    }
+    return details;
+}
+function renderRuleLine(rule) {
+    return rule.type;
+}
+function renderDesired(desired) {
+    return [
+        `    rules:   ${desired.rules.map(renderRuleLine).join(", ")}`,
+        `    bypass:  ${desired.bypass_actors.length === 0
+            ? "(none)"
+            : desired.bypass_actors
+                .map((a) => `${a.actor_type}#${a.actor_id} (${a.bypass_mode})`)
+                .join(", ")}`,
+    ];
+}
+export function renderPlan(plan) {
+    const lines = [];
+    for (const create of plan.creates) {
+        lines.push(`+ create   "${create.desired.name}"`);
+        lines.push(...renderDesired(create.desired));
+    }
+    for (const update of plan.updates) {
+        const renameNote = update.liveName !== update.desired.name
+            ? ` (renamed from "${update.liveName}")`
+            : "";
+        lines.push(`~ update   "${update.desired.name}"${renameNote} [id ${update.id}]`);
+        lines.push(...renderDesired(update.desired));
+    }
+    for (const del of plan.deletes) {
+        lines.push(`- delete   "${del.name}" [id ${del.id}]`);
+    }
+    for (const noop of plan.noops) {
+        lines.push(`= ok       "${noop.name}" [id ${noop.id}] — already matches`);
+    }
+    if (plan.perTeamSkipped.length > 0) {
+        lines.push(`  skipped  ${plan.perTeamSkipped.length} per-team ruleset(s), owned by teamSync.ts: ` +
+            plan.perTeamSkipped.join(", "));
+    }
+    if (plan.unmanaged.length > 0) {
+        lines.push(`  unmanaged  ${plan.unmanaged.join(", ")} — not a fixed ruleset or a deletion target, left alone`);
+    }
+    if (lines.length === 0)
+        return "(nothing to report)";
+    return lines.join("\n");
+}
+async function confirmApply(yes) {
+    if (yes)
+        return true;
+    if (!process.stdin.isTTY) {
+        process.stderr.write("devtools github rulesets: --yes is required to apply with no terminal available.\n");
+        return false;
+    }
+    return unwrap(await confirm({
+        message: "Apply this ruleset plan?",
+        initialValue: false,
+    }));
+}
+export async function runGithubRulesets(argv) {
+    const opts = parseOptions(argv);
+    const r = { owner: opts.org, repo: opts.repo };
+    let devopsTeamId;
+    let adminsTeamId;
+    let appId;
+    try {
+        [devopsTeamId, adminsTeamId, appId] = await Promise.all([
+            resolveTeamId(opts.org, DEFAULT_DEVOPS_SLUG),
+            resolveTeamId(opts.org, DEFAULT_ADMINS_SLUG),
+            resolveAppId(opts.org, opts.appSlug),
+        ]);
+    }
+    catch (err) {
+        process.stderr.write(`devtools github rulesets: ${err instanceof Error ? err.message : String(err)}\n`);
+        return 1;
+    }
+    // Renovate (TASK-299) is resolved SEPARATELY and is allowed to fail: Sloan
+    // may not have installed it yet, and that must not block reconciling
+    // everything else. A failure here prints a warning and the plan simply
+    // omits it from `~ALL`'s bypass list — re-running after the App is
+    // installed picks it up with no further action.
+    let renovateAppId;
+    try {
+        renovateAppId = await resolveAppId(opts.org, DEFAULT_RENOVATE_SLUG);
+    }
+    catch (err) {
+        process.stderr.write(`devtools github rulesets: warning: could not resolve the Renovate App ` +
+            `("${DEFAULT_RENOVATE_SLUG}") — ~ALL's plan omits it as a bypass actor ` +
+            `until it is installed (TASK-299). ${err instanceof Error ? err.message : String(err)}\n`);
+    }
+    const actors = { devopsTeamId, adminsTeamId, appId, renovateAppId };
+    const desired = buildDesiredRulesets(actors);
+    let summaries;
+    let details;
+    try {
+        summaries = await listRulesets(r);
+        details = await fetchDetails(r, summaries);
+    }
+    catch (err) {
+        process.stderr.write(`devtools github rulesets: ${err instanceof Error ? err.message : String(err)}\n`);
+        return 1;
+    }
+    const plan = planRulesets(summaries, details, actors, desired);
+    if (opts.json) {
+        console.log(JSON.stringify(plan, null, 2));
+    }
+    else {
+        console.log(renderPlan(plan));
+    }
+    if (!opts.apply) {
+        if (!opts.json && planHasChanges(plan)) {
+            console.log("\n(dry run — pass --apply to write this plan)");
+        }
+        return 0;
+    }
+    if (!planHasChanges(plan))
+        return 0;
+    if (!(await confirmApply(opts.yes)))
+        return 1;
+    try {
+        for (const create of plan.creates) {
+            await createRuleset(r, create.desired);
+        }
+        for (const update of plan.updates) {
+            await updateRuleset(r, update.id, update.desired);
+        }
+        for (const del of plan.deletes) {
+            await deleteRuleset(r, del.id);
+        }
+    }
+    catch (err) {
+        process.stderr.write(`devtools github rulesets: apply failed: ${err instanceof Error ? err.message : String(err)}\n`);
+        return 1;
+    }
+    console.log("Applied.");
+    return 0;
+}

package/dist/gh/rulesets/desired.d.ts

@@ -0,0 +1,112 @@
+/**
+ * The five fixed rulesets this repository must carry, as code.
+ *
+ * `apps/platform/src/server/github/rulesets.ts` (DevDogsUGA) has described
+ * these in prose since it was written — its module doc counts them toward
+ * the 75-ruleset cap — but nothing ever created them. TASK-322 is that gap:
+ * `main-protection` blocked only deletion and force-push (a push landed on
+ * `main` directly), `production` had no ruleset at all (a push there
+ * deploys), and a stale `comp-branches` ruleset survived a naming change.
+ * This module is the missing desired-state builder; `diff.ts` compares it
+ * against what `gh api .../rulesets` actually reports; `commands.ts` is the
+ * `devtools github rulesets` command that prints or applies the difference.
+ *
+ * ## Why the fixed `team/**` ruleset is safe alongside per-team ones
+ *
+ * `rulesets.ts`'s constraint 2 warns against ever running a broad `team/**`
+ * ruleset alongside the per-team ones `teamSync.ts` creates: rules AGGREGATE
+ * across rulesets sharing a ref, but bypass does NOT, so a broad ruleset
+ * restricting `update`/`push` would leave every team blocked by the broad
+ * one while bypassing only its own — readable, unpushable, silently.
+ *
+ * That warning is about a ruleset carrying `update` on `team/**`. This one
+ * carries `creation`, `deletion` and `non_fast_forward` — deliberately NOT
+ * `update`. No per-team ruleset (`teamRulesetPayload` in DevDogsUGA) has
+ * ever granted a `creation` rule — `rulesets.ts`'s own doc says why: the
+ * branch is cut by `cutTeamBranch` with the App's token before the per-team
+ * ruleset exists, so a `creation` rule there would be inert on the first
+ * branch and would block re-provisioning after a deletion. Two rulesets
+ * governing disjoint rule TYPES on the same ref pattern don't aggregate into
+ * a conflict for `creation` — there is nothing for them to disagree about.
+ * What that rule closes is a real hole `rulesets.ts` never covered: every
+ * team member holds a repository-wide `push` grant (GitHub team permissions
+ * have no branch dimension), so *before* the platform provisions a team, any
+ * member could `git push origin HEAD:refs/heads/team/<slug>` and front-run
+ * the App — creating the ref with content of their choosing, or squatting a
+ * slug that never gets legitimately provisioned.
+ *
+ * `deletion` and `non_fast_forward` DO aggregate against the per-team
+ * ruleset's own `deletion` rule (and its deliberate absence of
+ * `non_fast_forward`) — deliberately. A team is a bypass actor on its OWN
+ * per-team ruleset, not on this one, so the aggregate result is that a team
+ * can no longer delete or force-push its own branch, even though its
+ * per-team ruleset alone would let it (bypass is ruleset-scoped, constraint
+ * 1) — TASK-324's access-control checklist requires exactly that refusal.
+ * `update` is excluded from this ruleset for the opposite reason: it is the
+ * one rule type the per-team ruleset itself carries and bypasses its own
+ * team for, so adding a second `update` rule here — which only the App and
+ * devops bypass — would block every team's ordinary pushes to its own
+ * branch despite its per-team ruleset correctly bypassing them. That is
+ * exactly the failure constraint 2 describes; leaving `update` out is what
+ * keeps this ruleset on the safe side of it.
+ *
+ * ## Fixed cost is now 5, not 4
+ *
+ * `rulesets.ts`'s constraint 3 said "Fixed cost is 4: `main`, `production`,
+ * `~ALL` and the tag ruleset, leaving 71 for teams." This adds `team/**` as
+ * a fifth fixed ruleset, so the constant there needs updating to 5 fixed /
+ * 70 for teams — done alongside this file, in the same DevDogsUGA commit
+ * that would eventually consume this reconciler's output.
+ */
+import type { DesiredRuleset } from "./types.js";
+/** Resolved GitHub ids this module needs before it can build a plan. */
+export interface RulesetActors {
+    /** The `devops` team's numeric id (`GET /orgs/{org}/teams/devops`). */
+    devopsTeamId: number;
+    /** The `admins` team's numeric id — bypasses the tag ruleset, as it does live today. */
+    adminsTeamId: number;
+    /** The DevDogs Platform GitHub App's id (`app_id`, not the installation id). */
+    appId: number;
+    /**
+     * The Renovate GitHub App's id, or `undefined` when it cannot be resolved
+     * yet (TASK-299 — Sloan has not installed it at the time this module was
+     * written). `undefined` means "omit it from `~ALL`'s bypass list", not "fail
+     * the plan" — `commands.ts` resolves this separately from the other three
+     * (all required) and prints a warning rather than refusing, so re-running
+     * after the App is installed picks it up with no code change here.
+     */
+    renovateAppId?: number;
+}
+/**
+ * Canonical fixed-ruleset name -> earlier name(s) this reconciler recognizes
+ * as the SAME slot, so the first run renames rather than creating a
+ * duplicate that leaves the old one live and unmanaged.
+ *
+ * Only `main` has a legacy alias today (`main-protection`, live on GitHub as
+ * of 2026-09-24). `production`, `~ALL` and `team/**` have no live ruleset to
+ * rename — they are created fresh. The tag ruleset keeps its live name,
+ * `tag-protection`, unchanged; nothing about its shape is wrong today, so
+ * there is no rename to make.
+ */
+export declare const LEGACY_NAME_ALIASES: Readonly<Record<string, readonly string[]>>;
+/** Ruleset names this reconciler deletes outright — nothing in the desired set replaces them. */
+export declare const DELETE_RULESET_NAMES: readonly string[];
+/**
+ * A live ruleset name this reconciler must NEVER touch: one `teamSync.ts`
+ * created and owns (`team/<slug>`, an exact-ref ruleset), as opposed to the
+ * `team/**` wildcard-creation ruleset this module itself manages.
+ *
+ * `teamRulesetName()` in DevDogsUGA's `rulesets.ts` builds these as
+ * `team/${slug}`, and slugs never contain `/`, so a live name is a per-team
+ * ruleset iff it starts with `team/` and is not the literal `team/**` this
+ * reconciler owns.
+ */
+export declare function isPerTeamRulesetName(name: string): boolean;
+/**
+ * The five fixed rulesets, built from resolved actor ids.
+ *
+ * Pure — no network, no `gh` — so `desired.test.ts` can assert the shape
+ * without mocking anything, and `commands.ts` calls this only after
+ * resolving `RulesetActors` from the live org.
+ */
+export declare function buildDesiredRulesets(actors: RulesetActors): DesiredRuleset[];