docugate 0.2.8 → 0.3.0

package/dist/sync/command.js

@@ -0,0 +1,236 @@
+import { existsSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { createInterface } from 'node:readline/promises';
+import { packageVersion } from '../banner.js';
+import { CONFIG_FILE, loadConfig } from '../config.js';
+import { readText } from '../text.js';
+import { FRESHNESS_VALUES } from '../rules.js';
+import { bold, dim, gold, green, plural, red, yellow } from '../ui.js';
+import { defaultGit, SyncError } from './changes.js';
+import { installHook, removeHook } from './hook.js';
+import { runSync } from './run.js';
+import { repoFromRemote } from './pr.js';
+import { writeWorkflow, WORKFLOW_FILE } from './workflow.js';
+const out = (line = '') => console.log(line);
+/** `docugate sync ...`. Returns the exit code. */
+export async function syncCommand(root, args, deps = {}) {
+    const quiet = args.bools.has('quiet');
+    try {
+        if (args.sub === 'init')
+            return syncInit(root, args);
+        if (args.sub === 'hook')
+            return syncHook(root, args);
+        if (args.sub)
+            throw new SyncError(`Unknown sync command "${args.sub}". Try: sync, sync init, sync hook install, sync hook remove.`);
+        const interactive = Boolean(process.stdin.isTTY && process.stdout.isTTY) && !process.env.CI && !args.bools.has('no-input');
+        const options = {
+            since: args.since,
+            dryRun: args.bools.has('dry-run'),
+            pr: args.bools.has('pr'),
+            yes: args.bools.has('yes'),
+            model: args.model,
+            maxFiles: args.maxFiles ? Number(args.maxFiles) : undefined,
+        };
+        if (args.maxFiles && !(Number.isInteger(options.maxFiles) && options.maxFiles > 0)) {
+            throw new SyncError('--max-files needs a whole number above zero.');
+        }
+        const result = await runSync(root, options, {
+            ...deps,
+            log: quiet ? undefined : (line) => out(`  ${dim(line)}`),
+            confirm: interactive && !options.yes ? ask : undefined,
+        });
+        return report(result, quiet);
+    }
+    catch (error) {
+        // A hook must never be the reason a commit looks broken.
+        if (quiet)
+            return 0;
+        if (error instanceof SyncError) {
+            console.error(`${red('error')} ${error.message}`);
+            return 1;
+        }
+        throw error;
+    }
+}
+async function ask(question) {
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    try {
+        const answer = (await rl.question(`  ${question} ${dim('[Y/n]')} `)).trim().toLowerCase();
+        return answer === '' || answer.startsWith('y');
+    }
+    finally {
+        rl.close();
+    }
+}
+function report(r, quiet) {
+    const affected = r.impact?.pages ?? [];
+    if (quiet) {
+        if (affected.length) {
+            out(`docugate: ${plural(affected.length, 'docs page')} may be out of date after this change. Run \`docugate sync\` to update ${affected.length === 1 ? 'it' : 'them'}.`);
+        }
+        return 0;
+    }
+    out();
+    if (r.changes) {
+        const c = r.changes;
+        out(`  ${bold('Docs sync')}${r.dryRun ? dim('  (dry run: nothing is sent or written)') : ''}`);
+        out(`  ${plural(c.commits.length, 'commit')} and ${plural(c.files.length, 'code file')} changed ${c.range}`);
+    }
+    if (r.skipped) {
+        out(`  ${yellow(r.skipped.replace(/^Skipped: /, ''))}`);
+        out();
+        return 0;
+    }
+    if (r.dryRun) {
+        out();
+        if (affected.length) {
+            out(`  ${bold('Pages likely affected')}`);
+            for (const p of affected)
+                out(`    ${gold(p.path.padEnd(32))} ${dim(p.reasons.slice(0, 2).join('; '))}`);
+        }
+        else
+            out(`  ${dim('No existing page names these changes.')}`);
+        if (r.impact?.uncovered.length) {
+            out();
+            out(`  ${bold('Not covered by any page')}`);
+            for (const f of r.impact.uncovered.slice(0, 12))
+                out(`    ${f}`);
+            if (r.impact.uncovered.length > 12)
+                out(`    ${dim(`and ${r.impact.uncovered.length - 12} more`)}`);
+        }
+        staleTour(r);
+        out();
+        out(`  ${dim('Next:')} docugate sync`);
+        out();
+        return 0;
+    }
+    if (r.provider)
+        out(`  Written with ${r.provider}`);
+    out();
+    if (r.written.length) {
+        out(`  ${green('Updated')} ${plural(r.written.length, 'page')}`);
+        for (const e of r.written)
+            out(`    ${e.action === 'create' ? green('new ') : '    '}${gold(e.path)}${e.reason ? dim(`  ${e.reason}`) : ''}`);
+    }
+    else {
+        out(`  ${green('The docs already match the code.')} Nothing was changed.`);
+        if (r.summary)
+            out(`  ${dim(r.summary)}`);
+    }
+    if (r.rejected.length) {
+        out();
+        out(`  ${yellow('Left out')}`);
+        for (const x of r.rejected)
+            out(`    ${x.path} ${dim(x.reason)}`);
+    }
+    staleTour(r);
+    if (r.pr) {
+        out();
+        out(r.pr.url ? `  ${green('Pull request')} ${r.pr.url}` : `  ${yellow(r.pr.note ?? `Pushed ${r.pr.branch}.`)}`);
+    }
+    else if (r.written.length) {
+        out();
+        out(`  ${dim('Next:')} read the changes, then commit them. To get a pull request instead, run ${bold('docugate sync --pr')}.`);
+    }
+    out();
+    return 0;
+}
+function staleTour(r) {
+    if (!r.staleTour.length)
+        return;
+    out();
+    out(`  ${yellow('Tour stops that look out of date')} ${dim('(only reported; DocuGate never edits a tour)')}`);
+    for (const t of r.staleTour.slice(0, 8))
+        out(`    ${t.file ? `${t.file}  ` : ''}${t.message}`);
+}
+// ── sync init ───────────────────────────────────────────────────────────
+function syncInit(root, args) {
+    let freshness = args.freshness;
+    if (freshness && !FRESHNESS_VALUES.includes(freshness)) {
+        throw new SyncError(`--freshness must be one of ${FRESHNESS_VALUES.join(', ')}.`);
+    }
+    const loaded = loadConfig(root);
+    if (loaded.errors.length)
+        throw new SyncError(`docugate.json has a problem: ${loaded.errors[0].message}`);
+    freshness ??= loaded.config.freshness ?? 'weekly';
+    // docugate.json is where "how often" lives, so the workflow and the file agree.
+    if (loaded.config.freshness !== freshness)
+        saveConfigKey(root, 'freshness', freshness);
+    const git = defaultGit;
+    let branch = 'main';
+    try {
+        branch = git(['symbolic-ref', '--short', 'refs/remotes/origin/HEAD'], root).trim().replace(/^origin\//, '');
+    }
+    catch {
+        try {
+            branch = git(['rev-parse', '--abbrev-ref', 'HEAD'], root).trim() || 'main';
+        }
+        catch {
+            /* not a git repository: the workflow still gets written with main */
+        }
+    }
+    const result = writeWorkflow(root, { freshness, docsDir: loaded.docsDir, branch, version: packageVersion(), provider: loaded.config.sync?.provider }, args.bools.has('force'));
+    out();
+    if (result.status === 'off') {
+        out(`  ${yellow('freshness is "off"')}, so no workflow was written. Pick how often docs should be checked:`);
+        out(`    docugate sync init --freshness weekly   ${dim('(or daily, or push)')}`);
+        out();
+        return 0;
+    }
+    const when = freshness === 'push' ? `on every push to ${branch}` : freshness === 'daily' ? 'every day' : 'every Monday';
+    out(`  ${result.status === 'kept' ? dim('kept') : green(result.status)}    ${WORKFLOW_FILE}  ${dim(`(runs ${when})`)}`);
+    if (result.status === 'kept' && !args.bools.has('force') && existsSync(join(root, WORKFLOW_FILE))) {
+        out(`  ${dim('It already exists. Add --force to rewrite it from your current settings.')}`);
+    }
+    let repo = null;
+    try {
+        repo = repoFromRemote(git(['remote', 'get-url', 'origin'], root));
+    }
+    catch {
+        /* no remote yet */
+    }
+    const key = loaded.config.sync?.provider === 'openai' ? 'OPENAI_API_KEY' : 'ANTHROPIC_API_KEY';
+    out();
+    out(`  ${bold('Two things to do on GitHub, once:')}`);
+    out(`    1. Add your AI key as a repository secret named ${gold(key)}`);
+    out(`       ${dim(repo ? `https://github.com/${repo}/settings/secrets/actions` : 'Settings > Secrets and variables > Actions')}`);
+    out(`    2. Allow Actions to open pull requests: Settings > Actions > General > Workflow permissions`);
+    out(`       ${dim('and tick "Allow GitHub Actions to create and approve pull requests"')}`);
+    out();
+    out(`  Then commit the workflow. ${dim('Next:')} docugate sync hook install ${dim('(optional: a heads-up after each commit)')}`);
+    out();
+    return 0;
+}
+/** Set one top-level key in docugate.json, keeping everything else as it was. */
+function saveConfigKey(root, key, value) {
+    const path = join(root, CONFIG_FILE);
+    let data = {};
+    if (existsSync(path)) {
+        try {
+            data = JSON.parse(readText(path));
+        }
+        catch {
+            throw new SyncError('docugate.json is not valid JSON, so it was not changed.');
+        }
+    }
+    data[key] = value;
+    writeFileSync(path, `${JSON.stringify(data, null, 2)}\n`);
+}
+// ── sync hook ───────────────────────────────────────────────────────────
+function syncHook(root, args) {
+    if (args.sub2 !== 'install' && args.sub2 !== 'remove') {
+        throw new SyncError('Use `sync hook install` or `sync hook remove`.');
+    }
+    out();
+    if (args.sub2 === 'install') {
+        const r = installHook(root);
+        out(`  ${green(r.status)}  ${r.path}`);
+        out(`  ${dim('After each commit it tells you which docs pages may be out of date. It sends nothing and changes nothing.')}`);
+    }
+    else {
+        const r = removeHook(root);
+        out(r.removed ? `  ${green('removed')}  the DocuGate part of ${r.path}` : `  ${dim('There was no DocuGate hook to remove.')}`);
+    }
+    out();
+    return 0;
+}

package/dist/sync/guard.d.ts

@@ -0,0 +1,15 @@
+/** The commit message tag, and the branch prefix, that mark DocuGate's own work. */
+export declare const SYNC_TAG = "[docugate-sync]";
+export declare const SYNC_BRANCH_PREFIX = "docugate/sync";
+/**
+ * Whether a run should stand down because it was caused by a sync itself.
+ * Without this a merged sync pull request would start the next sync, which
+ * would open another pull request, and so on.
+ */
+export declare function shouldSkip(input: {
+    headMessage?: string;
+    branch?: string;
+    /** Every path the triggering change touched. */
+    changedPaths?: string[];
+    docsDir: string;
+}): string | null;

package/dist/sync/guard.js

@@ -0,0 +1,21 @@
+/** The commit message tag, and the branch prefix, that mark DocuGate's own work. */
+export const SYNC_TAG = '[docugate-sync]';
+export const SYNC_BRANCH_PREFIX = 'docugate/sync';
+/**
+ * Whether a run should stand down because it was caused by a sync itself.
+ * Without this a merged sync pull request would start the next sync, which
+ * would open another pull request, and so on.
+ */
+export function shouldSkip(input) {
+    if (input.headMessage?.includes(SYNC_TAG))
+        return `the latest commit is a DocuGate sync (${SYNC_TAG}).`;
+    if (input.branch?.replace(/^refs\/heads\//, '').startsWith(SYNC_BRANCH_PREFIX)) {
+        return `this is a DocuGate sync branch (${SYNC_BRANCH_PREFIX}*).`;
+    }
+    const docs = input.docsDir === '.' ? '' : input.docsDir.replace(/^\/|\/$/g, '');
+    const paths = input.changedPaths ?? [];
+    if (paths.length && paths.every((p) => (docs && p.startsWith(`${docs}/`)) || p.startsWith('.docugate/'))) {
+        return 'the change only touches documentation.';
+    }
+    return null;
+}

package/dist/sync/hook.d.ts

@@ -0,0 +1,10 @@
+import type { GitFn } from './changes.js';
+export declare function installHook(root: string, git?: GitFn): {
+    path: string;
+    status: 'installed' | 'updated';
+};
+export declare function removeHook(root: string, git?: GitFn): {
+    path: string;
+    removed: boolean;
+};
+export declare function hookInstalled(root: string, git?: GitFn): boolean;

package/dist/sync/hook.js

@@ -0,0 +1,62 @@
+import { chmodSync, existsSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { isAbsolute, join } from 'node:path';
+import { defaultGit } from './changes.js';
+// A git post-commit hook that says, after each commit, how many pages the code
+// has left behind. It runs `sync --dry-run`: no AI, no cost, no files changed,
+// and it never fails a commit.
+const START = '# >>> docugate sync (managed) >>>';
+const END = '# <<< docugate sync (managed) <<<';
+const BLOCK = `${START}
+# Tells you which docs pages the latest changes may have left out of date.
+# Remove with: docugate sync hook remove
+if command -v docugate >/dev/null 2>&1; then
+  docugate sync --dry-run --quiet || true
+elif command -v npx >/dev/null 2>&1; then
+  npx --no-install docugate sync --dry-run --quiet 2>/dev/null || true
+fi
+${END}
+`;
+function hookPath(root, git) {
+    const rel = git(['rev-parse', '--git-path', 'hooks/post-commit'], root).trim();
+    return isAbsolute(rel) ? rel : join(root, rel);
+}
+const escape = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+const strip = (text) => text.replace(new RegExp(`\\n?${escape(START)}[\\s\\S]*?${escape(END)}\\n?`), '\n');
+export function installHook(root, git = defaultGit) {
+    const path = hookPath(root, git);
+    if (!existsSync(path)) {
+        writeFileSync(path, `#!/bin/sh\n${BLOCK}`);
+        chmodSync(path, 0o755);
+        return { path, status: 'installed' };
+    }
+    const existing = readFileSync(path, 'utf8');
+    const had = existing.includes(START);
+    const base = had ? strip(existing) : existing;
+    writeFileSync(path, `${base.replace(/\n*$/, '\n')}\n${BLOCK}`);
+    chmodSync(path, 0o755);
+    return { path, status: had ? 'updated' : 'installed' };
+}
+export function removeHook(root, git = defaultGit) {
+    const path = hookPath(root, git);
+    if (!existsSync(path))
+        return { path, removed: false };
+    const existing = readFileSync(path, 'utf8');
+    if (!existing.includes(START))
+        return { path, removed: false };
+    const rest = strip(existing).trim();
+    // What is left is nothing but the shebang: the hook was ours alone.
+    if (!rest || /^#!.*$/.test(rest))
+        rmSync(path, { force: true });
+    else
+        writeFileSync(path, `${rest}\n`);
+    return { path, removed: true };
+}
+export function hookInstalled(root, git = defaultGit) {
+    try {
+        const path = hookPath(root, git);
+        return existsSync(path) && readFileSync(path, 'utf8').includes(START);
+    }
+    catch {
+        return false;
+    }
+}

package/dist/sync/impact.d.ts

@@ -0,0 +1,23 @@
+import type { ChangedFile } from './changes.js';
+export type PageInfo = {
+    /** Relative to the repository root, like `docs/api.md`. */
+    path: string;
+    title: string;
+    headings: string[];
+    content: string;
+};
+export type PageImpact = {
+    path: string;
+    title: string;
+    score: number;
+    reasons: string[];
+};
+export type Impact = {
+    pages: PageImpact[];
+    /** Changed files that no page mentions and no map entry covers. */
+    uncovered: string[];
+};
+export declare function loadPages(root: string, docsDir: string): PageInfo[];
+/** Everything the changes added or removed that a page might have named. */
+export declare function symbolsIn(files: ChangedFile[]): string[];
+export declare function scoreImpact(pages: PageInfo[], files: ChangedFile[], map?: Record<string, string[]>): Impact;

package/dist/sync/impact.js

@@ -0,0 +1,93 @@
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { walk } from '../check.js';
+import { globToRegExp } from '../openapi.js';
+import { firstHeading } from '../rules.js';
+import { readText } from '../text.js';
+export function loadPages(root, docsDir) {
+    const dir = docsDir === '.' ? '' : docsDir;
+    const base = dir ? join(root, dir) : root;
+    if (!existsSync(base))
+        return [];
+    return walk(base)
+        .filter((f) => /\.md$/i.test(f))
+        .map((f) => {
+        const path = dir ? `${dir}/${f}` : f;
+        const content = readText(join(base, f)).replace(/\r\n/g, '\n');
+        return {
+            path,
+            title: firstHeading(content) ?? f.replace(/\.md$/i, ''),
+            headings: [...content.matchAll(/^#{1,4}\s+(.+)$/gm)].map((m) => m[1].trim()),
+            content,
+        };
+    });
+}
+/** Names too common to mean anything when a page happens to contain them. */
+const GENERIC = new Set(['index', 'main', 'app', 'utils', 'util', 'types', 'config', 'constants', 'helpers', 'test']);
+/** What one file's change added or removed that a page might have named. */
+function symbolsOf(file) {
+    const found = new Set();
+    for (const line of file.diff.split('\n')) {
+        if (!/^[+-]/.test(line) || /^(\+\+\+|---)/.test(line))
+            continue;
+        const decl = line.match(/^[+-]\s*(?:export\s+)?(?:default\s+)?(?:async\s+)?(?:function\*?|class|interface|type|enum|const|def|func|fn)\s+([A-Za-z_]\w{3,})/);
+        if (decl)
+            found.add(decl[1]);
+        for (const route of line.matchAll(/['"`](\/[A-Za-z0-9_\-/:{}.]{3,})['"`]/g))
+            found.add(route[1]);
+        for (const env of line.matchAll(/\b([A-Z][A-Z0-9]*_[A-Z0-9_]{2,})\b/g))
+            found.add(env[1]);
+    }
+    return found;
+}
+/** Everything the changes added or removed that a page might have named. */
+export function symbolsIn(files) {
+    return [...new Set(files.flatMap((f) => [...symbolsOf(f)]))];
+}
+const stem = (path) => (path.split('/').pop() ?? path).replace(/\.[^.]+$/, '');
+export function scoreImpact(pages, files, map = {}) {
+    const symbolsByFile = files.map((f) => ({ path: f.path, symbols: symbolsOf(f) }));
+    const results = new Map();
+    const covered = new Set();
+    const hit = (page, points, reason, file) => {
+        const entry = results.get(page.path) ?? { path: page.path, title: page.title, score: 0, reasons: [] };
+        entry.score += points;
+        if (!entry.reasons.includes(reason))
+            entry.reasons.push(reason);
+        results.set(page.path, entry);
+        if (file)
+            covered.add(file);
+    };
+    const mapped = Object.entries(map).map(([page, globs]) => ({
+        page: page.replace(/^\.?\//, ''),
+        globs: globs.map(globToRegExp),
+        raw: globs,
+    }));
+    for (const page of pages) {
+        const text = page.content;
+        for (const file of files) {
+            const pin = mapped.find((m) => (m.page === page.path || page.path.endsWith(`/${m.page}`)) && m.globs.some((g) => g.test(file.path)));
+            if (pin)
+                hit(page, 10, `pinned to ${pin.raw.find((g) => globToRegExp(g).test(file.path))}`, file.path);
+            if (text.includes(file.path))
+                hit(page, 5, `names ${file.path}`, file.path);
+            else {
+                const name = stem(file.path);
+                const baseName = file.path.split('/').pop();
+                if (!GENERIC.has(name.toLowerCase()) && name.length >= 4 && text.includes(baseName)) {
+                    hit(page, 2, `names ${baseName}`, file.path);
+                }
+            }
+        }
+        for (const { path, symbols } of symbolsByFile) {
+            for (const symbol of symbols) {
+                if (text.includes(symbol))
+                    hit(page, 3, `mentions ${symbol}`, path);
+            }
+        }
+    }
+    return {
+        pages: [...results.values()].sort((a, b) => b.score - a.score || a.path.localeCompare(b.path)),
+        uncovered: files.map((f) => f.path).filter((p) => !covered.has(p)),
+    };
+}

package/dist/sync/pr.d.ts

@@ -0,0 +1,37 @@
+import type { Changes, GitFn } from './changes.js';
+import type { DocEdit } from './ai.js';
+import type { Rejected } from './apply.js';
+export declare const SYNC_BRANCH = "docugate/sync";
+export type PrInput = {
+    root: string;
+    title: string;
+    body: string;
+    /** Everything to commit: the pages and `.docugate/sync.json`. */
+    files: string[];
+};
+export type PrResult = {
+    branch: string;
+    url?: string;
+    note?: string;
+};
+export type PrFn = (input: PrInput) => Promise<PrResult>;
+export type PrDeps = {
+    git?: GitFn;
+    fetchFn?: typeof fetch;
+    env?: NodeJS.ProcessEnv;
+};
+/** `owner/repo` from a GitHub remote URL, whether it is https or ssh. */
+export declare function repoFromRemote(remote: string): string | null;
+export declare function buildPrBody(input: {
+    summary: string;
+    written: DocEdit[];
+    rejected: Rejected[];
+    changes: Changes;
+    docsDir: string;
+    /** `owner/slug` of the DocuGate space, when the repository has one. */
+    space?: string;
+    siteUrl?: string;
+    staleTour?: string[];
+}): string;
+/** Commit the files on the sync branch, push it, and open or update the pull request. */
+export declare function defaultPr(deps?: PrDeps): PrFn;

package/dist/sync/pr.js

@@ -0,0 +1,106 @@
+import { defaultGit, SyncError } from './changes.js';
+import { SYNC_BRANCH_PREFIX, SYNC_TAG } from './guard.js';
+import { pathToSlug } from '../rules.js';
+// Hands the docs over for review. One rolling branch and one pull request:
+// each run rewrites the same branch, so a week of unmerged syncs is one pull
+// request that grows, not a pile of them. Nothing is ever merged from here.
+export const SYNC_BRANCH = SYNC_BRANCH_PREFIX;
+/** `owner/repo` from a GitHub remote URL, whether it is https or ssh. */
+export function repoFromRemote(remote) {
+    const m = remote.trim().match(/github\.com[:/]([^/]+\/[^/\s]+?)(?:\.git)?$/);
+    return m ? m[1] : null;
+}
+export function buildPrBody(input) {
+    const lines = [];
+    lines.push(`DocuGate read the code changes ${input.changes.range} (${input.changes.commits.length} commit${input.changes.commits.length === 1 ? '' : 's'}, ${input.changes.files.length} file${input.changes.files.length === 1 ? '' : 's'}) and updated the docs to match.`, '');
+    if (input.summary)
+        lines.push(input.summary, '');
+    lines.push('**This is generated. Read it before you merge it.**', '', '### Pages');
+    const docs = input.docsDir === '.' ? '' : `${input.docsDir.replace(/\/$/, '')}/`;
+    for (const e of input.written) {
+        const slug = pathToSlug(docs && e.path.startsWith(docs) ? e.path.slice(docs.length) : e.path);
+        const link = input.space && input.siteUrl ? ` ([on the site](${input.siteUrl.replace(/\/$/, '')}/${input.space}/${slug}))` : '';
+        lines.push(`- \`${e.path}\` ${e.action === 'create' ? '(new)' : ''}${e.reason ? `: ${e.reason}` : ''}${link}`.replace('  ', ' '));
+    }
+    if (input.rejected.length) {
+        lines.push('', '### Left out');
+        for (const r of input.rejected)
+            lines.push(`- \`${r.path}\` ${r.reason}`);
+    }
+    if (input.staleTour?.length) {
+        lines.push('', '### Tour stops that look out of date', 'DocuGate never edits a tour. These are for you to look at:');
+        for (const t of input.staleTour)
+            lines.push(`- ${t}`);
+    }
+    lines.push('', `Commits: \`${input.changes.from ? input.changes.from.slice(0, 7) : 'start'}..${input.changes.to.slice(0, 7)}\``, '', `<sub>Made by \`docugate sync\`. Merging this moves the sync forward; closing it changes nothing.</sub>`);
+    return lines.join('\n');
+}
+/** Commit the files on the sync branch, push it, and open or update the pull request. */
+export function defaultPr(deps = {}) {
+    const git = deps.git ?? defaultGit;
+    const fetchFn = deps.fetchFn ?? fetch;
+    const env = deps.env ?? process.env;
+    return async ({ root, title, body, files }) => {
+        const run = (args) => git(args, root).trim();
+        const tryRun = (args) => {
+            try {
+                return run(args);
+            }
+            catch {
+                return null;
+            }
+        };
+        const headSha = run(['rev-parse', 'HEAD']);
+        const current = tryRun(['rev-parse', '--abbrev-ref', 'HEAD']);
+        const base = env.GITHUB_BASE_REF || (current && current !== 'HEAD' ? current : env.GITHUB_REF_NAME) || 'main';
+        const returnTo = current && current !== 'HEAD' ? current : headSha;
+        // CI has no git identity; a developer's own is left alone.
+        const identity = tryRun(['config', 'user.email'])
+            ? []
+            : ['-c', 'user.name=docugate[bot]', '-c', 'user.email=docugate[bot]@users.noreply.github.com'];
+        run(['checkout', '-B', SYNC_BRANCH]);
+        let url;
+        let note;
+        try {
+            run(['add', '--', ...files]);
+            run([...identity, 'commit', '-m', `docs: sync with code changes ${SYNC_TAG}`]);
+            try {
+                run(['push', '--force', '-u', 'origin', SYNC_BRANCH]);
+            }
+            catch (error) {
+                throw new SyncError(`Could not push the ${SYNC_BRANCH} branch: ${error.message.split('\n')[0]}`);
+            }
+            const repo = repoFromRemote(tryRun(['remote', 'get-url', 'origin']) ?? '');
+            const token = env.GITHUB_TOKEN || env.GH_TOKEN;
+            if (!repo)
+                note = `Pushed ${SYNC_BRANCH}. Open a pull request from it on GitHub.`;
+            else if (!token)
+                note = `Pushed ${SYNC_BRANCH}. Set GITHUB_TOKEN to open the pull request automatically, or open it from https://github.com/${repo}/pull/new/${SYNC_BRANCH}`;
+            else {
+                const api = (env.GITHUB_API_URL ?? 'https://api.github.com').replace(/\/$/, '');
+                const headers = { authorization: `Bearer ${token}`, accept: 'application/vnd.github+json', 'content-type': 'application/json', 'user-agent': 'docugate' };
+                const owner = repo.split('/')[0];
+                const existing = await fetchFn(`${api}/repos/${repo}/pulls?head=${owner}:${SYNC_BRANCH}&state=open`, { headers });
+                const open = existing.ok ? (await existing.json()) : [];
+                if (open[0]) {
+                    const res = await fetchFn(`${api}/repos/${repo}/pulls/${open[0].number}`, { method: 'PATCH', headers, body: JSON.stringify({ title, body }) });
+                    url = res.ok ? (await res.json()).html_url : open[0].html_url;
+                }
+                else {
+                    const res = await fetchFn(`${api}/repos/${repo}/pulls`, { method: 'POST', headers, body: JSON.stringify({ title, body, head: SYNC_BRANCH, base }) });
+                    if (!res.ok) {
+                        const detail = ((await res.text().catch(() => '')) || '').slice(0, 200);
+                        note = `Pushed ${SYNC_BRANCH}, but GitHub would not open the pull request (${res.status}). ${res.status === 403 ? 'In the repository settings, allow Actions to create pull requests. ' : ''}${detail}`;
+                    }
+                    else
+                        url = (await res.json()).html_url;
+                }
+            }
+        }
+        finally {
+            // The developer's own branch is left as it was.
+            tryRun(['checkout', returnTo]);
+        }
+        return { branch: SYNC_BRANCH, url, note };
+    };
+}

package/dist/sync/run.d.ts

@@ -0,0 +1,50 @@
+import type { Issue } from '../config.js';
+import type { AiFn } from './ai.js';
+import type { Rejected } from './apply.js';
+import type { Changes, GitFn } from './changes.js';
+import type { Impact } from './impact.js';
+import type { PrFn } from './pr.js';
+import type { DocEdit } from './ai.js';
+export type SyncOptions = {
+    /** `last` (the default), a duration like `7d`, or a git ref. */
+    since?: string;
+    /** Only report what would be updated: no AI, no writes. */
+    dryRun?: boolean;
+    /** Push the result and open a pull request. */
+    pr?: boolean;
+    /** Do not ask before sending the changes to the AI provider. */
+    yes?: boolean;
+    maxFiles?: number;
+    model?: string;
+    /** The branch this is running on, when git cannot say (CI). */
+    branch?: string;
+};
+export type SyncDeps = {
+    git?: GitFn;
+    aiFn?: AiFn;
+    prFn?: PrFn;
+    env?: NodeJS.ProcessEnv;
+    now?: Date;
+    /** Asked before the changes leave the machine. Absent means do not ask. */
+    confirm?: (message: string) => Promise<boolean>;
+    log?: (line: string) => void;
+};
+export type SyncResult = {
+    dryRun: boolean;
+    /** Why nothing was done, when that is so. */
+    skipped?: string;
+    changes?: Changes;
+    impact?: Impact;
+    /** Tour stops that no longer match the code. Only ever reported. */
+    staleTour: Issue[];
+    summary?: string;
+    written: DocEdit[];
+    rejected: Rejected[];
+    provider?: string;
+    pr?: {
+        branch: string;
+        url?: string;
+        note?: string;
+    };
+};
+export declare function runSync(root: string, options?: SyncOptions, deps?: SyncDeps): Promise<SyncResult>;