@devdogsuga/devtools 0.1.0

package/dist/newsletter/commands.d.ts

@@ -0,0 +1,16 @@
+export type NewsletterFormat = "eml" | "html";
+export declare const NEWSLETTER_FORMATS: readonly ["eml", "html"];
+export interface NewsletterOptions {
+    versions: string[];
+    formats: NewsletterFormat[];
+    out: string;
+    /** Append each issue as a draft in the club mailbox. */
+    push: boolean;
+    /** Send each issue over SMTP, to `to`, byte-for-byte as authored. */
+    send: boolean;
+    to: string[];
+    mailbox: string;
+}
+export declare function parseNewsletterArgs(argv: readonly string[], cwd: string): NewsletterOptions | Error;
+export declare function destination(out: string, version: string, format: NewsletterFormat): string;
+export declare function runNewsletter(argv: string[]): Promise<void>;

package/dist/newsletter/commands.js

@@ -0,0 +1,311 @@
+/**
+ * `pnpm devtools newsletter [version…] [--format eml,html] [--out dir]
+ * [--push] [--send --to addresses] [--mailbox address]`.
+ */
+import { mkdir, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, resolve } from "node:path";
+import { randomBytes } from "node:crypto";
+import { isTTY, log, multiselect, spinner, text as askText, } from "@clack/prompts";
+import { Resvg } from "@resvg/resvg-js";
+import { positionals } from "../args.js";
+import { errorMessage, explain, unwrap } from "../ui.js";
+import { loadNewsletter, loadNewsletterExport } from "../repo/peers.js";
+import { appendDraft } from "./imap.js";
+import { originationHeaders, submitMessage } from "./smtp.js";
+import { openInBrowser, startLoopback } from "./loopback.js";
+import { authorizeUrl, codeFromRedirect, grantPath, PASTE_REDIRECT_URI, readGrant, redeemCode, refreshTokens, writeGrant, } from "./oauth.js";
+/** The account the newsletter goes out from; `--mailbox` overrides. */
+const CLUB_MAILBOX = "devdogs@uga.edu";
+export const NEWSLETTER_FORMATS = ["eml", "html"];
+function flagValue(argv, flag) {
+    const index = argv.indexOf(flag);
+    if (index === -1)
+        return undefined;
+    const value = argv[index + 1];
+    return value && !value.startsWith("--") ? value : undefined;
+}
+function expandHome(value) {
+    return value === "~" || value.startsWith("~/")
+        ? resolve(homedir(), value.slice(2))
+        : value;
+}
+export function parseNewsletterArgs(argv, cwd) {
+    const push = argv.includes("--push");
+    const send = argv.includes("--send");
+    const to = (flagValue(argv, "--to") ?? "")
+        .split(",")
+        .map((value) => value.trim())
+        .filter(Boolean);
+    // A send is deliberate twice over: the flag names the act and --to names
+    // who receives it. Neither is inferred and neither is prompted for.
+    if (send && !to.length) {
+        return new Error("--send needs --to, a comma-separated recipient list.");
+    }
+    if (to.length && !send) {
+        return new Error("--to only means something with --send.");
+    }
+    // Both formats by default: the .eml is the point of the command, and the
+    // .html is how it gets proofread before an officer opens Outlook. Except
+    // under --push or --send, where a caller who wanted files too would have
+    // said so — the draft in the mailbox, or the send, IS the output.
+    const rawFormats = (flagValue(argv, "--format") ?? (push || send ? "" : "eml,html"))
+        .split(",")
+        .map((value) => value.trim())
+        .filter(Boolean);
+    const badFormats = rawFormats.filter((value) => !NEWSLETTER_FORMATS.includes(value));
+    if (badFormats.length)
+        return new Error(`Unknown format ${badFormats.join(", ")}. Try eml or html.`);
+    return {
+        // Versions can only be validated against the built package, which loads
+        // lazily inside the run — so they pass through here unchecked.
+        versions: positionals(argv),
+        formats: [...new Set(rawFormats)],
+        out: resolve(cwd, expandHome(flagValue(argv, "--out") ?? "changelog-exports")),
+        push,
+        send,
+        to,
+        mailbox: flagValue(argv, "--mailbox") ?? CLUB_MAILBOX,
+    };
+}
+export function destination(out, version, format) {
+    return resolve(out, `changelog-v${version}.${format}`);
+}
+async function interactive(options, all) {
+    if (options.versions.length)
+        return options;
+    if (!isTTY(process.stdout)) {
+        throw new Error("No terminal to choose issues. Name one, or pass * for all.");
+    }
+    const versions = unwrap(await multiselect({
+        message: "Which issues?",
+        options: all.map((issue) => ({
+            value: issue.version,
+            label: `v${issue.version}`,
+            hint: issue.tagline,
+        })),
+        initialValues: [all[all.length - 1]?.version ?? ""].filter(Boolean),
+        required: true,
+    }));
+    const outputs = unwrap(await multiselect({
+        message: "Which outputs?",
+        options: [
+            {
+                value: "push",
+                label: "Draft in the club mailbox",
+                hint: `lands in Drafts of ${options.mailbox}; review in any Outlook`,
+            },
+            {
+                value: "eml",
+                label: "Outlook draft (.eml)",
+                hint: "classic Outlook opens it for review",
+            },
+            { value: "html", label: "HTML preview", hint: "open in a browser" },
+        ],
+        initialValues: [...NEWSLETTER_FORMATS],
+        required: true,
+    }));
+    const formats = outputs.filter((output) => output !== "push");
+    let out = options.out;
+    if (formats.length) {
+        const entered = unwrap(await askText({
+            message: "Where should the files go?",
+            placeholder: "./changelog-exports",
+            defaultValue: "./changelog-exports",
+        })).trim();
+        out = resolve(process.cwd(), expandHome(entered || "changelog-exports"));
+    }
+    return {
+        ...options,
+        versions,
+        formats,
+        out,
+        push: options.push || outputs.includes("push"),
+    };
+}
+/**
+ * The browser sign-in, redirect caught by a loopback server: open the URL,
+ * wait for the code to knock, exchange it. Five minutes is the patience —
+ * authorization codes do not live much longer anyway.
+ */
+async function signInViaLoopback(mailbox, server, state) {
+    const redirectUri = `http://localhost:${server.port}/`;
+    const url = authorizeUrl(mailbox, redirectUri, state);
+    log.step(`Sign in as ${mailbox} in the browser window that just opened:`);
+    log.message(url);
+    openInBrowser(url);
+    const wait = spinner();
+    wait.start("Waiting for the sign-in to come back");
+    try {
+        const timeout = new Promise((_, rejectLate) => {
+            setTimeout(() => rejectLate(new Error("Five minutes passed with no sign-in. Run it again.")), 5 * 60_000).unref();
+        });
+        const code = await Promise.race([server.code, timeout]);
+        wait.stop("The sign-in came back.");
+        return await redeemCode(code, redirectUri);
+    }
+    catch (err) {
+        wait.stop("No sign-in.");
+        throw err;
+    }
+    finally {
+        server.close();
+    }
+}
+/** The pasted fallback for a machine where no local port would bind. */
+async function signInViaPaste(mailbox) {
+    log.step(`Open this and sign in as ${mailbox}:`);
+    log.message(authorizeUrl(mailbox, PASTE_REDIRECT_URI));
+    const pasted = unwrap(await askText({
+        message: "The browser will land on a dead localhost page. Paste its full address:",
+        validate: (value) => {
+            const code = codeFromRedirect(value ?? "");
+            return code instanceof Error ? code.message : undefined;
+        },
+    }));
+    const code = codeFromRedirect(pasted);
+    if (code instanceof Error)
+        throw code;
+    return redeemCode(code, PASTE_REDIRECT_URI);
+}
+/**
+ * An access token for the club mailbox: the stored grant refreshed when there
+ * is one, a browser sign-in when there is not.
+ */
+async function mailboxAccessToken(mailbox) {
+    const stored = await readGrant();
+    if (stored && stored.mailbox === mailbox) {
+        try {
+            const tokens = await refreshTokens(stored.refreshToken);
+            // Microsoft rotates refresh tokens; keeping the old one means the next
+            // run signs in from scratch.
+            await writeGrant({ mailbox, refreshToken: tokens.refreshToken });
+            return tokens.accessToken;
+        }
+        catch (err) {
+            log.warn(`The stored sign-in was refused (${errorMessage(err)}).`);
+        }
+    }
+    if (!isTTY(process.stdout)) {
+        throw new Error(`No terminal to sign in as ${mailbox}. Run \`pnpm devtools newsletter --push\` interactively once; after that this works anywhere.`);
+    }
+    const state = randomBytes(16).toString("hex");
+    const server = await startLoopback(state).catch(() => null);
+    const tokens = server
+        ? await signInViaLoopback(mailbox, server, state)
+        : await signInViaPaste(mailbox);
+    await writeGrant({ mailbox, refreshToken: tokens.refreshToken });
+    log.info(`Signed in. The grant lives in ${grantPath()} — mode 600, keep it that way.`);
+    return tokens.accessToken;
+}
+export async function runNewsletter(argv) {
+    const parsed = parseNewsletterArgs(argv, process.cwd());
+    if (parsed instanceof Error) {
+        explain("Could not read that.", parsed.message, [
+            "pnpm devtools newsletter",
+            "pnpm devtools newsletter '*' --format eml,html --out ~/changelog",
+        ]);
+        process.exitCode = 1;
+        return;
+    }
+    try {
+        // Dynamic so every unrelated devtools command can still run before the
+        // newsletter package has been built on a fresh checkout.
+        const { ISSUES, issueByVersion } = await loadNewsletter();
+        const { buildEml, emailImages, previewRenderContext, renderIssueDocument } = await loadNewsletterExport();
+        const unknown = parsed.versions.filter((version) => version !== "*" && !issueByVersion(version));
+        if (unknown.length) {
+            explain("Could not read that.", `No issue called ${unknown.join(", ")}. Try ${ISSUES.map((issue) => issue.version).join(", ")}, or *.`, ["pnpm devtools newsletter", "pnpm devtools newsletter '*'"]);
+            process.exitCode = 1;
+            return;
+        }
+        const options = await interactive(parsed, ISSUES);
+        const versions = options.versions.includes("*")
+            ? ISSUES.map((issue) => issue.version)
+            : [...new Set(options.versions)];
+        // Rasterised once: the marks are the same in every issue. 2x the display
+        // size the components declare, so the email stays sharp on dense screens.
+        const images = options.formats.includes("eml") || options.push || options.send
+            ? emailImages().map((image) => ({
+                cid: image.cid,
+                filename: image.filename,
+                contentType: "image/png",
+                base64: Buffer.from(new Resvg(image.svg, {
+                    fitTo: { mode: "width", value: image.rasterWidth },
+                    // The marks are pure paths; nothing here needs a host font.
+                    font: { loadSystemFonts: false },
+                })
+                    .render()
+                    .asPng()).toString("base64"),
+            }))
+            : [];
+        const written = [];
+        for (const version of versions) {
+            const issue = issueByVersion(version);
+            for (const format of options.formats) {
+                const file = destination(options.out, version, format);
+                await mkdir(dirname(file), { recursive: true });
+                await writeFile(file, format === "eml"
+                    ? buildEml({
+                        subject: issue.title,
+                        html: renderIssueDocument(issue),
+                        images,
+                    })
+                    : renderIssueDocument(issue, previewRenderContext()));
+                written.push(file);
+            }
+        }
+        for (const file of written)
+            log.success(file);
+        if (written.length) {
+            log.info(`${written.length} file${written.length === 1 ? "" : "s"} written. An .eml opens in classic Outlook for review; send with --send.`);
+        }
+        if (options.push || options.send) {
+            const accessToken = await mailboxAccessToken(options.mailbox);
+            if (options.push) {
+                for (const version of versions) {
+                    const issue = issueByVersion(version);
+                    await appendDraft({
+                        user: options.mailbox,
+                        accessToken,
+                        message: buildEml({
+                            subject: issue.title,
+                            html: renderIssueDocument(issue),
+                            images,
+                            unsent: false,
+                        }),
+                    });
+                    log.success(`v${version} → Drafts of ${options.mailbox}`);
+                }
+                log.info("Open any Outlook as the club account to review — but send with " +
+                    "`--send`, not from Outlook: its composers rewrite the HTML.");
+            }
+            if (options.send) {
+                for (const version of versions) {
+                    const issue = issueByVersion(version);
+                    await submitMessage({
+                        user: options.mailbox,
+                        accessToken,
+                        from: options.mailbox,
+                        recipients: options.to,
+                        message: originationHeaders(options.mailbox, options.to) +
+                            buildEml({
+                                subject: issue.title,
+                                html: renderIssueDocument(issue),
+                                images,
+                                unsent: false,
+                            }),
+                    });
+                    log.success(`v${version} → sent to ${options.to.join(", ")}`);
+                }
+            }
+        }
+    }
+    catch (err) {
+        explain("Could not export the changelog.", errorMessage(err), [
+            "Build it with `pnpm --filter @devdogsuga/newsletter build`.",
+            "Then try `pnpm devtools newsletter '*' --out ~/changelog`.",
+        ]);
+        process.exitCode = 1;
+    }
+}

package/dist/newsletter/imap.d.ts

@@ -0,0 +1,17 @@
+/** RFC 7628's SASL initial response: user and bearer token, ^A-delimited. */
+export declare function xoauth2(user: string, accessToken: string): string;
+/**
+ * The Drafts folder's real name out of `LIST` output, for mailboxes whose
+ * folders are not in English. The `\Drafts` attribute is the label Exchange
+ * puts on the folder regardless of what it is called.
+ */
+export declare function draftsFromList(lines: readonly string[]): string | null;
+/** Folder names go back out quoted, so quote-significant bytes get escaped. */
+export declare function quoteMailbox(name: string): string;
+export declare function appendDraft(options: {
+    user: string;
+    accessToken: string;
+    /** The full MIME message, CRLF line endings. */
+    message: string;
+    host?: string;
+}): Promise<void>;

package/dist/newsletter/imap.js

@@ -0,0 +1,127 @@
+/**
+ * One-shot IMAP APPEND: place a finished MIME message in a mailbox's Drafts
+ * folder, where every Outlook — new, web, Mac, classic — offers it as an
+ * editable draft. This is the whole reason for speaking IMAP at all: the
+ * mailbox is the one place all the clients agree on, and APPEND is the one
+ * verb this workflow needs, so a dependency-free sliver of the protocol beats
+ * a client library that models the rest of it.
+ */
+import { connect } from "node:tls";
+const DEFAULT_HOST = "outlook.office365.com";
+const TIMEOUT_MS = 30_000;
+/** RFC 7628's SASL initial response: user and bearer token, ^A-delimited. */
+export function xoauth2(user, accessToken) {
+    return Buffer.from(`user=${user}\x01auth=Bearer ${accessToken}\x01\x01`, "utf8").toString("base64");
+}
+/**
+ * The Drafts folder's real name out of `LIST` output, for mailboxes whose
+ * folders are not in English. The `\Drafts` attribute is the label Exchange
+ * puts on the folder regardless of what it is called.
+ */
+export function draftsFromList(lines) {
+    for (const line of lines) {
+        const match = /^\* LIST \(([^)]*)\) (?:"[^"]*"|NIL) (.+)$/.exec(line);
+        if (!match || !/\\Drafts\b/i.test(match[1]))
+            continue;
+        const raw = match[2].trim();
+        return raw.startsWith('"') && raw.endsWith('"')
+            ? raw.slice(1, -1).replace(/\\(["\\])/g, "$1")
+            : raw;
+    }
+    return null;
+}
+/** Folder names go back out quoted, so quote-significant bytes get escaped. */
+export function quoteMailbox(name) {
+    return `"${name.replace(/([\\"])/g, "\\$1")}"`;
+}
+export async function appendDraft(options) {
+    const host = options.host ?? DEFAULT_HOST;
+    const socket = connect({ host, port: 993, servername: host });
+    socket.setTimeout(TIMEOUT_MS);
+    let buffer = "";
+    let sequence = 0;
+    const pending = [];
+    let wake = null;
+    let failure = null;
+    socket.on("data", (chunk) => {
+        buffer += chunk.toString("utf8");
+        let index;
+        while ((index = buffer.indexOf("\r\n")) !== -1) {
+            pending.push(buffer.slice(0, index));
+            buffer = buffer.slice(index + 2);
+        }
+        wake?.();
+    });
+    const fail = (err) => {
+        failure ??= err;
+        socket.destroy();
+        wake?.();
+    };
+    socket.on("error", (err) => fail(err));
+    socket.on("timeout", () => fail(new Error(`${host} stopped answering.`)));
+    socket.on("close", () => fail(new Error(`${host} closed the connection.`)));
+    const nextLine = async () => {
+        for (;;) {
+            if (pending.length)
+                return pending.shift();
+            if (failure)
+                throw failure;
+            await new Promise((resolvePromise) => {
+                wake = resolvePromise;
+            });
+            wake = null;
+        }
+    };
+    /**
+     * Sends one command and reads to its tagged reply. A `+ ` continuation
+     * hands control back via `onContinue` — APPEND pushes the literal there,
+     * and a failed AUTHENTICATE wants a bare CRLF to surface its tagged NO.
+     */
+    const command = async (line, onContinue) => {
+        const tag = `T${++sequence}`;
+        socket.write(`${tag} ${line}\r\n`);
+        const untagged = [];
+        for (;;) {
+            const reply = await nextLine();
+            if (reply.startsWith("+ ") || reply === "+") {
+                (onContinue ?? (() => socket.write("\r\n")))();
+                continue;
+            }
+            if (reply.startsWith(`${tag} `)) {
+                const [status = "", ...rest] = reply.slice(tag.length + 1).split(" ");
+                return { status: status.toUpperCase(), text: rest.join(" "), untagged };
+            }
+            if (reply.startsWith("* "))
+                untagged.push(reply);
+        }
+    };
+    try {
+        await nextLine(); // The server greets first; nothing in it matters here.
+        const auth = await command(`AUTHENTICATE XOAUTH2 ${xoauth2(options.user, options.accessToken)}`);
+        if (auth.status !== "OK") {
+            throw new Error(`${options.user} was refused: ${auth.text || auth.status}. ` +
+                "Sign in again if the stored grant has been revoked.");
+        }
+        const literal = Buffer.from(options.message, "utf8");
+        const append = (folder) => command(`APPEND ${quoteMailbox(folder)} (\\Draft \\Seen) {${literal.length}}`, () => {
+            socket.write(literal);
+            socket.write("\r\n");
+        });
+        let placed = await append("Drafts");
+        if (placed.status !== "OK") {
+            // Exchange names the folder in the mailbox's own language; the
+            // attribute in LIST is the stable way to find it.
+            const list = await command('LIST "" "*"');
+            const drafts = draftsFromList(list.untagged);
+            if (drafts && drafts !== "Drafts")
+                placed = await append(drafts);
+            if (placed.status !== "OK") {
+                throw new Error(`APPEND was refused: ${placed.text || placed.status}`);
+            }
+        }
+        await command("LOGOUT");
+    }
+    finally {
+        socket.destroy();
+    }
+}

package/dist/newsletter/loopback.d.ts

@@ -0,0 +1,24 @@
+/**
+ * What one request to the listener means. `null` is a stray — a favicon
+ * probe, a health check — and the server keeps waiting; a wrong or missing
+ * state is also a stray, because rejecting the whole sign-in over a request
+ * an attacker could send unauthenticated would hand them a denial of
+ * service instead.
+ */
+export declare function parseCallback(requestUrl: string, state: string): {
+    code: string;
+} | Error | null;
+export interface Loopback {
+    port: number;
+    /** Resolves with the code, or rejects with what the identity page said. */
+    code: Promise<string>;
+    close(): void;
+}
+/** Throws when it cannot bind, which is the caller's cue to fall back. */
+export declare function startLoopback(state: string): Promise<Loopback>;
+/**
+ * Best effort only: the URL is always printed too, so a machine with no
+ * opener — SSH, a container, a WSL distro without wslview — costs one click
+ * on the printed line instead of a failure.
+ */
+export declare function openInBrowser(url: string): void;

package/dist/newsletter/loopback.js

@@ -0,0 +1,100 @@
+/**
+ * A throwaway HTTP server that catches one OAuth redirect and dies.
+ *
+ * Entra ignores the port when matching a localhost redirect URI, so the
+ * sign-in can come home to `http://localhost:{ephemeral}/` even though
+ * Thunderbird registered no port. Bound to 127.0.0.1 only — the redirect
+ * never leaves the machine, and nothing off it should reach the listener.
+ * The `state` nonce ties the callback to this run: any other process that
+ * finds the port cannot feed the flow a code it did not mint.
+ */
+import { createServer } from "node:http";
+import { spawn } from "node:child_process";
+/**
+ * What one request to the listener means. `null` is a stray — a favicon
+ * probe, a health check — and the server keeps waiting; a wrong or missing
+ * state is also a stray, because rejecting the whole sign-in over a request
+ * an attacker could send unauthenticated would hand them a denial of
+ * service instead.
+ */
+export function parseCallback(requestUrl, state) {
+    const url = new URL(requestUrl, "http://localhost");
+    if (url.pathname !== "/")
+        return null;
+    if (url.searchParams.get("state") !== state)
+        return null;
+    const error = url.searchParams.get("error");
+    if (error) {
+        return new Error(url.searchParams.get("error_description") ?? error);
+    }
+    const code = url.searchParams.get("code");
+    return code ? { code } : null;
+}
+const LANDING = `<!doctype html>
+<meta charset="utf-8">
+<title>DevDogs devtools</title>
+<body style="font-family: system-ui; display: grid; place-items: center; min-height: 90vh; background: #13121b; color: #f3f1f6">
+<p style="max-width: 36rem; text-align: center">%MESSAGE% You can close this tab; the rest happens in the terminal.</p>
+`;
+/** Throws when it cannot bind, which is the caller's cue to fall back. */
+export function startLoopback(state) {
+    return new Promise((resolve, reject) => {
+        // Assigned synchronously by the executor below, which TS cannot see.
+        let settle;
+        const code = new Promise((resolveCode, rejectCode) => {
+            settle = { resolve: resolveCode, reject: rejectCode };
+        });
+        // A rejection can land in the gap before the caller awaits; this extra
+        // no-op handler marks it handled without eating it for the real awaiter.
+        code.catch(() => { });
+        const server = createServer((request, response) => {
+            const result = parseCallback(request.url ?? "/", state);
+            if (result === null) {
+                response.writeHead(404).end();
+                return;
+            }
+            const failed = result instanceof Error;
+            response
+                .writeHead(200, { "Content-Type": "text/html; charset=utf-8" })
+                .end(LANDING.replace("%MESSAGE%", failed ? "The sign-in did not go through." : "Signed in."));
+            if (failed)
+                settle.reject(result);
+            else
+                settle.resolve(result.code);
+        });
+        server.on("error", reject);
+        server.listen(0, "127.0.0.1", () => {
+            const address = server.address();
+            if (!address || typeof address === "string") {
+                server.close();
+                reject(new Error("The loopback server bound without a port."));
+                return;
+            }
+            resolve({
+                port: address.port,
+                code,
+                close: () => server.close(),
+            });
+        });
+    });
+}
+/**
+ * Best effort only: the URL is always printed too, so a machine with no
+ * opener — SSH, a container, a WSL distro without wslview — costs one click
+ * on the printed line instead of a failure.
+ */
+export function openInBrowser(url) {
+    const [command, args] = process.platform === "win32"
+        ? ["cmd", ["/c", "start", "", url]]
+        : process.platform === "darwin"
+            ? ["open", [url]]
+            : ["xdg-open", [url]];
+    try {
+        spawn(command, args, { stdio: "ignore", detached: true })
+            .on("error", () => { })
+            .unref();
+    }
+    catch {
+        // The printed URL is the real interface; this was only a convenience.
+    }
+}

package/dist/newsletter/oauth.d.ts

@@ -0,0 +1,26 @@
+/** The fallback redirect when no loopback server could bind. */
+export declare const PASTE_REDIRECT_URI = "https://localhost";
+export declare function authorizeUrl(mailbox: string, redirectUri: string, state?: string): string;
+/**
+ * The code out of whatever the officer pastes: the whole `https://localhost/?
+ * code=…` address (the intended gesture — the browser shows a dead page and
+ * they copy its location) or the bare code itself.
+ */
+export declare function codeFromRedirect(pasted: string): string | Error;
+export interface MailboxTokens {
+    accessToken: string;
+    refreshToken: string;
+}
+export declare function redeemCode(code: string, redirectUri: string): Promise<MailboxTokens>;
+export declare function refreshTokens(refreshToken: string): Promise<MailboxTokens>;
+export interface StoredGrant {
+    mailbox: string;
+    refreshToken: string;
+}
+/**
+ * Outside the repo on purpose: the refresh token opens the club mailbox, and
+ * nothing that opens the club mailbox belongs anywhere `git add` can reach.
+ */
+export declare function grantPath(): string;
+export declare function readGrant(): Promise<StoredGrant | null>;
+export declare function writeGrant(grant: StoredGrant): Promise<void>;