uncial-cms 0.0.0

package/dist/cli/assert-clean-pages.js

@@ -0,0 +1,153 @@
+/**
+ * The zero-CMS-JS build gate: Content pages must ship none of this package's
+ * JavaScript, Editor variants must ship it, and a local-only site's production
+ * build must carry no editor stack at all.
+ *
+ * Node only, and deliberately dependency-free apart from the sentinel: the
+ * published `bin` runs this against a build directory with nothing installed
+ * but the package itself.
+ */
+import { readdirSync, readFileSync } from 'node:fs';
+import { dirname, join, relative } from 'node:path';
+import { UNCIAL_CMS_RUNTIME_SENTINEL } from '../sentinel.js';
+/**
+ * Names the editor stack cannot be bundled without, and that nothing else in a
+ * built site carries. The ProseMirror marker is its class-name prefix rather
+ * than the bare word: `ProseMirror-focused` and its siblings are string
+ * literals in prosemirror-view that survive minification, while the bare word
+ * also appears in a validation message uncial's renderer ships — prose about a
+ * document format, not a copy of the library.
+ */
+const EDITOR_STACK_MARKERS = [
+    ['tiptap', /tiptap/i],
+    ['ProseMirror-', /ProseMirror-/],
+    ['uncial-editor', /uncial-editor/]
+];
+function walk(dir) {
+    return readdirSync(dir, { withFileTypes: true }).flatMap((entry) => {
+        const path = join(dir, entry.name);
+        return entry.isDirectory() ? walk(path) : [path];
+    });
+}
+/**
+ * Map an href/src (which may include a BASE_PATH prefix) to a file in the build
+ * directory: everything the app emits lives under `_app/`, so resolve from that
+ * segment.
+ */
+function resolveAppAsset(buildDir, url) {
+    const marker = url.indexOf('_app/');
+    return marker === -1 ? null : join(buildDir, url.slice(marker));
+}
+/** All JS files reachable from the HTML: script/link tags, then static imports. */
+function scriptClosure(buildDir, html) {
+    const queue = [];
+    for (const [, url] of html.matchAll(/(?:src|href)="([^"]+\.js)"/g)) {
+        const resolved = resolveAppAsset(buildDir, url);
+        if (resolved)
+            queue.push(resolved);
+    }
+    // Inline module scripts import chunks by absolute (base-prefixed) URL too.
+    for (const [, url] of html.matchAll(/import\(?["']([^"']+\.js)["']/g)) {
+        const resolved = resolveAppAsset(buildDir, url);
+        if (resolved)
+            queue.push(resolved);
+    }
+    const seen = new Set();
+    while (queue.length > 0) {
+        const file = queue.pop();
+        if (seen.has(file))
+            continue;
+        seen.add(file);
+        let source;
+        try {
+            source = readFileSync(file, 'utf-8');
+        }
+        catch {
+            continue; // external or non-emitted reference
+        }
+        // Static imports only: the kit router *dynamically* imports every route
+        // module lazily, and those never load on a content page.
+        for (const [, spec] of source.matchAll(/(?:from|import)\s*["']([^"']+\.js)["']/g)) {
+            if (spec.startsWith('.'))
+                queue.push(join(dirname(file), spec));
+            else {
+                const resolved = resolveAppAsset(buildDir, spec);
+                if (resolved)
+                    queue.push(resolved);
+            }
+        }
+    }
+    return seen;
+}
+function pageContainsSentinel(buildDir, htmlPath) {
+    const html = readFileSync(htmlPath, 'utf-8');
+    if (html.includes(UNCIAL_CMS_RUNTIME_SENTINEL))
+        return true;
+    for (const file of scriptClosure(buildDir, html)) {
+        if (readFileSync(file, 'utf-8').includes(UNCIAL_CMS_RUNTIME_SENTINEL))
+            return true;
+    }
+    return false;
+}
+/** Site-relative page path of an `index.html`, as the failure messages name it. */
+function pageOf(buildDir, htmlPath) {
+    return `/${relative(buildDir, dirname(htmlPath))}/`.replace(/^\/\.\/$/, '/');
+}
+export function assertCleanPages(buildDir, options, io) {
+    let files;
+    try {
+        files = walk(buildDir);
+    }
+    catch {
+        io.err(`No pages found under "${buildDir}" — build the site first.`);
+        return 1;
+    }
+    const htmlFiles = files.filter((path) => path.endsWith('index.html'));
+    if (htmlFiles.length === 0) {
+        io.err(`No pages found under "${buildDir}" — build the site first.`);
+        return 1;
+    }
+    const failures = [];
+    for (const htmlPath of htmlFiles) {
+        const page = pageOf(buildDir, htmlPath);
+        const isEditPage = page.endsWith('/edit/');
+        const isIndexPage = page === '/uncial/';
+        const hasSentinel = pageContainsSentinel(buildDir, htmlPath);
+        if (isEditPage && !options.localOnly && !hasSentinel) {
+            failures.push(`${page} is an editor variant but does not reference the CMS runtime.`);
+        }
+        else if (!isEditPage && !isIndexPage && hasSentinel) {
+            failures.push(`${page} is a content page but ships uncial-cms JavaScript.`);
+        }
+        if (options.localOnly && isEditPage) {
+            failures.push(`${page} is an editor variant, but a local-only build must ship none.`);
+        }
+    }
+    if (options.localOnly) {
+        for (const file of files) {
+            let source;
+            try {
+                source = readFileSync(file, 'utf-8');
+            }
+            catch {
+                continue;
+            }
+            const name = relative(buildDir, file);
+            if (source.includes(UNCIAL_CMS_RUNTIME_SENTINEL)) {
+                failures.push(`${name} carries the CMS runtime sentinel (${UNCIAL_CMS_RUNTIME_SENTINEL}).`);
+            }
+            for (const [marker, pattern] of EDITOR_STACK_MARKERS) {
+                if (pattern.test(source))
+                    failures.push(`${name} carries the editor stack (${marker}).`);
+            }
+        }
+    }
+    if (failures.length > 0) {
+        io.err('assert:clean-pages FAILED');
+        for (const failure of failures)
+            io.err(`  - ${failure}`);
+        return 1;
+    }
+    io.out(`assert:clean-pages OK — ${htmlFiles.length} pages checked, content pages are sentinel-free.`);
+    return 0;
+}

package/dist/cli/bin.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli/bin.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { run } from './run.js';
+process.exit(await run(process.argv.slice(2)));

package/dist/cli/doctor.d.ts

@@ -0,0 +1,23 @@
+import type { CliOutput } from './assert-clean-pages.js';
+export interface GhResult {
+    stdout: string;
+    /** Process exit status; a non-zero status is a refusal, never a throw. */
+    status: number;
+}
+export type GhInvoker = (args: string[]) => Promise<GhResult>;
+export interface DoctorOptions {
+    /** The site's origin, as the Allowlist and the auth worker spell it. */
+    origin: string;
+    /** `owner/name`; defaults to the repository `gh` sees in the working tree. */
+    repo?: string;
+    appSlug?: string;
+    /** Ref the Allowlist is read from; defaults to the repository's default branch. */
+    branch?: string;
+}
+/** Runs the real `gh`. A missing binary is a non-zero status, not an exception. */
+export declare function ghCli(): GhInvoker;
+/**
+ * Exit 0 when every check passes, 1 when one fails, and 2 when the command
+ * could not run at all — no authenticated `gh`, or no repository to check.
+ */
+export declare function doctor(options: DoctorOptions, io: CliOutput, gh?: GhInvoker): Promise<number>;

package/dist/cli/doctor.js

@@ -0,0 +1,217 @@
+/**
+ * The provisioning checks a site owner would otherwise learn about from a
+ * failed sign-in: the GitHub App installed on the repository, the Allowlist
+ * committed to the default branch naming the site's origin, and Pages serving
+ * that origin. Each failure names the auth worker refusal it would produce.
+ *
+ * Every fact comes from the authenticated `gh` CLI through one injectable
+ * invoker, so the specs never touch the network and the command never needs a
+ * token of its own.
+ */
+import { execFile } from 'node:child_process';
+import { DEFAULT_APP_SLUG } from '../define-site.js';
+/** Runs the real `gh`. A missing binary is a non-zero status, not an exception. */
+export function ghCli() {
+    return (args) => new Promise((resolve) => {
+        execFile('gh', args, { maxBuffer: 16 * 1024 * 1024 }, (error, stdout) => {
+            const code = error?.code;
+            resolve({ stdout, status: error === null ? 0 : typeof code === 'number' ? code : 1 });
+        });
+    });
+}
+const GH_INSTRUCTION = '`gh` is missing or not authenticated. Install it from https://cli.github.com and run `gh auth login`, then run this command again.';
+class Report {
+    io;
+    failed = false;
+    constructor(io) {
+        this.io = io;
+    }
+    pass(line) {
+        this.io.out(`✓ ${line}`);
+    }
+    /** `code` is the auth worker refusal this failure would have produced. */
+    fail(line, fix, code) {
+        this.failed = true;
+        this.io.err(`✗ ${line}${code ? ` (${code})` : ''}`);
+        this.io.err(`  Fix: ${fix}`);
+    }
+    warn(line) {
+        this.io.out(`! ${line}`);
+    }
+    get exitCode() {
+        return this.failed ? 1 : 0;
+    }
+}
+/** Non-empty trimmed lines of a `--jq` result. */
+function lines(stdout) {
+    return stdout
+        .split('\n')
+        .map((line) => line.trim())
+        .filter((line) => line.length > 0);
+}
+function parseJson(stdout) {
+    try {
+        return JSON.parse(stdout);
+    }
+    catch {
+        return undefined;
+    }
+}
+async function checkAppInstalled(gh, report, repo, appSlug) {
+    // `GET /repos/{owner}/{repo}/installation` needs App auth, so ask the
+    // installations the authenticated user can see which repositories they cover.
+    const installations = await gh([
+        'api',
+        '--paginate',
+        '/user/installations',
+        '--jq',
+        `.installations[] | select(.app_slug == "${appSlug}") | .id`
+    ]);
+    const installUrl = `https://github.com/apps/${appSlug}/installations/new`;
+    // A `gh auth login` token is not authorized to a GitHub App, so this route
+    // answers 403 for most users. That is unknown, not absent: reporting it as a
+    // failure would make every real run red on a check nothing here can settle.
+    if (installations.status !== 0) {
+        report.warn(`could not list "${appSlug}" App installations — \`gh\`'s token is not authorized to a GitHub App. Confirm the install by eye at ${installUrl}.`);
+        return;
+    }
+    const ids = lines(installations.stdout);
+    if (ids.length === 0) {
+        report.fail(`the "${appSlug}" GitHub App is not installed on any repository you can see`, `install it at ${installUrl}`, 'app_not_installed');
+        return;
+    }
+    let refused = false;
+    for (const id of ids) {
+        const repositories = await gh([
+            'api',
+            '--paginate',
+            `/user/installations/${id}/repositories`,
+            '--jq',
+            '.repositories[].full_name'
+        ]);
+        if (repositories.status !== 0) {
+            refused = true;
+            continue;
+        }
+        if (lines(repositories.stdout).some((name) => name.toLowerCase() === repo.toLowerCase())) {
+            report.pass(`the "${appSlug}" GitHub App is installed on ${repo}`);
+            return;
+        }
+    }
+    if (refused) {
+        report.warn(`could not list the repositories the "${appSlug}" App is installed on. Confirm ${repo} is among them at ${installUrl}.`);
+        return;
+    }
+    report.fail(`the "${appSlug}" GitHub App is installed, but not on ${repo}`, `grant it access to ${repo} at ${installUrl}`, 'app_not_installed');
+}
+async function checkPushPermission(gh, report, repo) {
+    const user = await gh(['api', 'user', '--jq', '.login']);
+    const login = lines(user.stdout)[0];
+    if (user.status !== 0 || login === undefined) {
+        report.fail('could not read the authenticated user from `gh`', 'run `gh auth status` and re-authenticate', 'no_push_permission');
+        return;
+    }
+    const permission = await gh([
+        'api',
+        `repos/${repo}/collaborators/${login}/permission`,
+        '--jq',
+        '.user.permissions.push'
+    ]);
+    if (permission.status === 0 && lines(permission.stdout)[0] === 'true') {
+        report.pass(`${login} has push permission on ${repo}`);
+        return;
+    }
+    report.fail(`${login} does not have push permission on ${repo}`, `ask an admin of ${repo} for write access — the editor commits as you`, 'no_push_permission');
+}
+async function checkAllowlist(gh, report, repo, origin, branch) {
+    const ref = branch === undefined ? '' : `?ref=${branch}`;
+    const where = branch === undefined ? 'the default branch' : `${branch}`;
+    const file = await gh([
+        'api',
+        '-H',
+        'Accept: application/vnd.github.raw',
+        `repos/${repo}/contents/.uncial/cms.json${ref}`
+    ]);
+    if (file.status !== 0) {
+        report.fail(`.uncial/cms.json is not on ${where} of ${repo}`, `commit { "allowedOrigins": ["${origin}"] } to .uncial/cms.json on ${where}`, 'missing_allowlist');
+        return;
+    }
+    const parsed = parseJson(file.stdout);
+    const allowed = typeof parsed === 'object' && parsed !== null
+        ? parsed.allowedOrigins
+        : undefined;
+    if (!Array.isArray(allowed) || allowed.some((entry) => typeof entry !== 'string')) {
+        report.fail(`.uncial/cms.json on ${where} of ${repo} has no "allowedOrigins" array of strings`, `make it { "allowedOrigins": ["${origin}"] }`, 'missing_allowlist');
+        return;
+    }
+    report.pass(`.uncial/cms.json on ${where} of ${repo} lists ${allowed.length} origin(s)`);
+    if (allowed.includes(origin)) {
+        report.pass(`${origin} is allowlisted`);
+        return;
+    }
+    report.fail(`${origin} is not in the allowlist (${allowed.join(', ') || 'empty'})`, `add "${origin}" to allowedOrigins in .uncial/cms.json — the worker matches the origin string exactly`, 'origin_not_allowed');
+}
+async function checkPages(gh, report, repo, host) {
+    const settingsUrl = `https://github.com/${repo}/settings/pages`;
+    const pages = await gh(['api', `repos/${repo}/pages`]);
+    if (pages.status !== 0) {
+        report.fail(`GitHub Pages is not enabled for ${repo}`, `enable it at ${settingsUrl}`);
+        return;
+    }
+    report.pass(`GitHub Pages is enabled for ${repo}`);
+    if (host.endsWith('.github.io'))
+        return;
+    const settings = parseJson(pages.stdout);
+    const cname = typeof settings?.cname === 'string' ? settings.cname : null;
+    if (cname !== host) {
+        report.fail(`the Pages custom domain is ${cname ?? 'unset'}, not ${host}`, `set the custom domain to ${host} at ${settingsUrl}`);
+    }
+    else {
+        report.pass(`the Pages custom domain is ${host}`);
+    }
+    if (settings?.https_enforced === true) {
+        report.pass('Pages enforces HTTPS');
+    }
+    else {
+        report.fail(`Pages does not enforce HTTPS for ${host}`, `tick "Enforce HTTPS" at ${settingsUrl} once the certificate is issued`);
+    }
+}
+/**
+ * Exit 0 when every check passes, 1 when one fails, and 2 when the command
+ * could not run at all — no authenticated `gh`, or no repository to check.
+ */
+export async function doctor(options, io, gh = ghCli()) {
+    let origin;
+    try {
+        origin = new URL(options.origin);
+    }
+    catch {
+        io.err(`"${options.origin}" is not a URL — pass an origin like https://example.com.`);
+        return 2;
+    }
+    const auth = await gh(['auth', 'status']);
+    if (auth.status !== 0) {
+        io.err(GH_INSTRUCTION);
+        return 2;
+    }
+    let repo = options.repo;
+    if (repo === undefined) {
+        const view = await gh(['repo', 'view', '--json', 'nameWithOwner', '--jq', '.nameWithOwner']);
+        repo = view.status === 0 ? lines(view.stdout)[0] : undefined;
+        if (repo === undefined) {
+            io.err('Could not determine the repository — run this in a checkout or pass --repo owner/name.');
+            return 2;
+        }
+    }
+    const appSlug = options.appSlug ?? DEFAULT_APP_SLUG;
+    const report = new Report(io);
+    report.pass('`gh` is installed and authenticated');
+    await checkAppInstalled(gh, report, repo, appSlug);
+    await checkPushPermission(gh, report, repo);
+    await checkAllowlist(gh, report, repo, origin.origin, options.branch);
+    await checkPages(gh, report, repo, origin.host);
+    if (origin.host.endsWith('.github.io')) {
+        report.warn(`${origin.host} is a shared origin: allowlisting it authorises every project page served from it. A custom domain restores per-site granularity.`);
+    }
+    return report.exitCode;
+}

package/dist/cli/run.d.ts

@@ -0,0 +1,4 @@
+import type { CliOutput } from './assert-clean-pages.js';
+import type { GhInvoker } from './doctor.js';
+export declare const consoleOutput: CliOutput;
+export declare function run(argv: string[], io?: CliOutput, gh?: GhInvoker): Promise<number>;

package/dist/cli/run.js

@@ -0,0 +1,99 @@
+/** Argument parsing and dispatch for the `uncial-cms` command. */
+import { assertCleanPages } from './assert-clean-pages.js';
+import { DEFAULT_APP_SLUG } from '../define-site.js';
+import { doctor } from './doctor.js';
+const USAGE = `uncial-cms — build gates and provisioning checks for a site that edits itself
+
+Usage:
+  uncial-cms assert-clean-pages [buildDir] [--local-only]
+
+    Assert that Content pages ship no uncial-cms JavaScript and that every
+    Editor variant does. buildDir defaults to "build".
+
+    --local-only  Assert a local-only site's production build instead: no
+                  Editor variant exists, and no file in the build carries the
+                  CMS runtime sentinel or the editor stack.
+
+  uncial-cms doctor --origin <https://host> [--repo owner/name]
+                    [--app-slug <slug>] [--branch <ref>]
+
+    Check, through the authenticated \`gh\` CLI, that the GitHub App is
+    installed on the repository, that .uncial/cms.json is committed and lists
+    the origin, and that Pages serves it. Each failure names the auth worker
+    refusal it would have produced.
+
+    --origin     The site's origin, spelled as the allowlist spells it.
+    --repo       Defaults to the repository of the current checkout.
+    --app-slug   Defaults to "${DEFAULT_APP_SLUG}".
+    --branch     Ref the allowlist is read from; defaults to the default branch.
+
+  uncial-cms --help    Print this message.`;
+export const consoleOutput = {
+    out: (line) => console.log(line),
+    err: (line) => console.error(line)
+};
+/** Flags taking a value, in either `--flag value` or `--flag=value` form. */
+function parseFlags(rest, names) {
+    const values = {};
+    for (let i = 0; i < rest.length; i += 1) {
+        const arg = rest[i];
+        const [name, inline] = arg.startsWith('--') && arg.includes('=')
+            ? [arg.slice(0, arg.indexOf('=')), arg.slice(arg.indexOf('=') + 1)]
+            : [arg, undefined];
+        if (!names.includes(name))
+            return { values, error: `Unknown option "${arg}".` };
+        const value = inline ?? rest[i + 1];
+        if (value === undefined || value.startsWith('-')) {
+            return { values, error: `Option "${name}" needs a value.` };
+        }
+        if (inline === undefined)
+            i += 1;
+        values[name] = value;
+    }
+    return { values, error: null };
+}
+export async function run(argv, io = consoleOutput, gh) {
+    const [command, ...rest] = argv;
+    if (command === undefined || command === '--help' || command === '-h') {
+        io.out(USAGE);
+        return 0;
+    }
+    if (command !== 'assert-clean-pages' && command !== 'doctor') {
+        io.err(`Unknown command "${command}".`);
+        io.err(USAGE);
+        return 2;
+    }
+    if (rest.includes('--help') || rest.includes('-h')) {
+        io.out(USAGE);
+        return 0;
+    }
+    if (command === 'doctor') {
+        const { values, error } = parseFlags(rest, ['--origin', '--repo', '--app-slug', '--branch']);
+        if (error !== null) {
+            io.err(error);
+            io.err(USAGE);
+            return 2;
+        }
+        const origin = values['--origin'];
+        if (origin === undefined) {
+            io.err('doctor needs --origin <https://host>.');
+            io.err(USAGE);
+            return 2;
+        }
+        return doctor({
+            origin,
+            repo: values['--repo'],
+            appSlug: values['--app-slug'],
+            branch: values['--branch']
+        }, io, gh);
+    }
+    const localOnly = rest.includes('--local-only');
+    const positional = rest.filter((arg) => !arg.startsWith('-'));
+    const unknownFlag = rest.find((arg) => arg.startsWith('-') && arg !== '--local-only');
+    if (unknownFlag !== undefined) {
+        io.err(`Unknown option "${unknownFlag}".`);
+        io.err(USAGE);
+        return 2;
+    }
+    return assertCleanPages(positional[0] ?? 'build', { localOnly }, io);
+}

package/dist/constants.d.ts

@@ -0,0 +1,6 @@
+/**
+ * The GitHub Contents API rejects file payloads larger than ~1 MB. Reads,
+ * document writes, and asset uploads all share this ceiling; there is no
+ * git-blobs-API fallback (see the uncial-cms spec's media non-goal).
+ */
+export declare const MAX_CONTENT_BYTES: number;

package/dist/constants.js

@@ -0,0 +1,6 @@
+/**
+ * The GitHub Contents API rejects file payloads larger than ~1 MB. Reads,
+ * document writes, and asset uploads all share this ceiling; there is no
+ * git-blobs-API fallback (see the uncial-cms spec's media non-goal).
+ */
+export const MAX_CONTENT_BYTES = 1024 * 1024;

package/dist/define-site.d.ts

@@ -0,0 +1,37 @@
+/**
+ * One declaration of a site's CMS configuration, resolved for the current
+ * build: the local forge while developing, the declared GitHub forge in a
+ * production build, and a local-only site when no GitHub half is declared.
+ */
+import type { UncialCmsSiteConfig } from './types.js';
+/** The auth worker this project operates for sites using the canonical GitHub App. */
+export declare const DEFAULT_AUTH_WORKER_URL = "https://uncial-cms-auth.dflood.workers.dev";
+/** The canonical GitHub App a site installs on its repository. */
+export declare const DEFAULT_APP_SLUG = "uncial-cms";
+export interface SiteOptions {
+    /** Repo-root-relative content directory, as the forge APIs address it. */
+    contentDir: string;
+    /** FS path of that directory at build time; defaults to `contentDir`. */
+    localContentDir?: string;
+    /** Repo-root-relative directory uploaded media commits into. */
+    mediaDir?: string;
+    /** Omit for a local-only site: one with no forge to commit to. */
+    github?: {
+        repo: string;
+        branch: string;
+        authWorkerUrl?: string;
+        appSlug?: string;
+    };
+    /** Honoured only when the resolved forge is local; a forge commit is never autosaved. */
+    autosaveMs?: number;
+}
+export interface Site {
+    config: UncialCmsSiteConfig;
+    /** No GitHub half was declared, so this site is only editable in development. */
+    localOnly: boolean;
+    autosaveMs: number | undefined;
+    localContentDir: string;
+}
+export declare function defineSite(options: SiteOptions, env?: {
+    dev: boolean;
+}): Site;

package/dist/define-site.js

@@ -0,0 +1,24 @@
+/** The auth worker this project operates for sites using the canonical GitHub App. */
+export const DEFAULT_AUTH_WORKER_URL = 'https://uncial-cms-auth.dflood.workers.dev';
+/** The canonical GitHub App a site installs on its repository. */
+export const DEFAULT_APP_SLUG = 'uncial-cms';
+export function defineSite(options, env = { dev: import.meta.env.DEV }) {
+    const localOnly = options.github === undefined;
+    const config = env.dev || options.github === undefined
+        ? { forge: 'local', contentDir: options.contentDir, mediaDir: options.mediaDir }
+        : {
+            forge: 'github',
+            repo: options.github.repo,
+            branch: options.github.branch,
+            contentDir: options.contentDir,
+            authWorkerUrl: options.github.authWorkerUrl ?? DEFAULT_AUTH_WORKER_URL,
+            appSlug: options.github.appSlug ?? DEFAULT_APP_SLUG,
+            mediaDir: options.mediaDir
+        };
+    return {
+        config,
+        localOnly,
+        autosaveMs: config.forge === 'local' ? options.autosaveMs : undefined,
+        localContentDir: options.localContentDir ?? options.contentDir
+    };
+}

package/dist/deploy-status.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Post-save deploy-status lifecycle (ticket 05, SPEC §6.6 / D5).
+ *
+ * After a save commits, the runtime polls `adapter.commitStatus(commitSha)` and
+ * surfaces the deploy lifecycle: `committed → building… → live` (or
+ * `build failed`, or a calm `status unknown` when the repo reports no checks).
+ * The timing constants live here; tests shrink them via injection.
+ */
+export type CommitStatus = 'pending' | 'success' | 'failure' | 'unknown';
+export type DeployPhase = 'committed' | 'building' | 'live' | 'failed' | 'unknown' | 'timeout';
+export interface DeployStatusTimings {
+    /** Delay before the first commit-status poll. */
+    firstDelayMs: number;
+    /** Delay between subsequent polls. */
+    intervalMs: number;
+    /** Hard stop; after this the phase becomes `timeout` and polling ends. */
+    timeoutMs: number;
+}
+export declare const DEFAULT_DEPLOY_STATUS_TIMINGS: DeployStatusTimings;
+/** Map a forge commit status to a deploy phase and whether polling should stop. */
+export declare function deployPhaseForStatus(status: CommitStatus): {
+    phase: DeployPhase;
+    done: boolean;
+};
+export interface DeployStatusView {
+    text: string;
+    /** Commit permalink on the forge, offered as a follow-up link. */
+    commitUrl: string;
+    /** Non-`failed` phases must render calmly, never as errors (D5). */
+    tone: 'progress' | 'success' | 'error';
+}
+export declare function githubCommitUrl(repo: string, commitSha: string): string;
+/** Human-facing copy for a phase; the branch is always named (ticket contract). */
+export declare function describeDeployPhase(phase: DeployPhase, ctx: {
+    branch: string;
+    commitSha: string;
+    commitUrl: string;
+}): DeployStatusView;
+export type Schedule = (fn: () => void, ms: number) => () => void;
+export declare const defaultSchedule: Schedule;
+export interface DeployPollHandle {
+    cancel(): void;
+}
+/**
+ * Poll `check` until a terminal status or the timeout. Emits `committed`
+ * synchronously, then a phase per poll. Stops on any terminal phase, on
+ * timeout, or on `cancel()`. Never throws — a failed check retries until the
+ * deadline.
+ */
+export declare function startDeployPolling(opts: {
+    check: () => Promise<CommitStatus>;
+    onPhase: (phase: DeployPhase) => void;
+    timings?: DeployStatusTimings;
+    schedule?: Schedule;
+}): DeployPollHandle;