docugate 0.3.1 → 0.4.1

package/dist/project.js

@@ -0,0 +1,369 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { basename, join, relative, resolve, sep } from 'node:path';
+import { createInterface } from 'node:readline/promises';
+import { apiFetch } from './api.js';
+import { login } from './auth.js';
+import { packageVersion } from './banner.js';
+import { loadConfig } from './config.js';
+import { guessRole } from './init.js';
+import { scanLockfiles } from './lockfiles.js';
+import { defaultGit } from './sync/changes.js';
+import { repoFromRemote } from './sync/pr.js';
+import { bold, dim, green, plural, red, yellow } from './ui.js';
+// A repository connected to a DocuGate account. `docugate connect` links it, and
+// from then on the dashboard decides which docs it updates, how often and what
+// kind of project it is. Everything that talks to DocuGate on a project's behalf
+// lives here, and none of it may ever be the reason a sync fails.
+export const PROJECT_TYPES = ['frontend', 'backend', 'serverless', 'monorepo'];
+export const FREQUENCIES = ['push', 'daily', 'weekly', 'off'];
+const TOKENS_FILE = () => join(process.env.DOCUGATE_HOME ?? join(homedir(), '.docugate'), 'projects.json');
+const base = () => process.env.DOCUGATE_URL ?? 'https://www.trydocugate.site';
+function readTokens() {
+    try {
+        return JSON.parse(readFileSync(TOKENS_FILE(), 'utf8'));
+    }
+    catch {
+        return {};
+    }
+}
+/** `owner/name` from the git remote, or the folder's name without one. */
+export function detectRepo(root) {
+    try {
+        const repo = repoFromRemote(defaultGit(['remote', 'get-url', 'origin'], root));
+        if (repo)
+            return repo;
+    }
+    catch {
+        // Not a git repository, or no remote.
+    }
+    return basename(root);
+}
+/** The token for this codebase: CI's secret first, then what `connect` saved for this folder, then for its repository. */
+export function projectToken(root, env = process.env) {
+    if (env.DOCUGATE_PROJECT_TOKEN)
+        return env.DOCUGATE_PROJECT_TOKEN;
+    const { repo, path } = codebaseOf(root);
+    const tokens = readTokens();
+    return tokens[tokenKey(repo, path)] || tokens[repo] || null;
+}
+/** A suggestion only. The person confirms it, and the dashboard can change it. */
+export function detectType(root) {
+    const has = (name) => existsSync(join(root, name));
+    let workspaces = has('pnpm-workspace.yaml') || has('turbo.json') || has('nx.json');
+    try {
+        workspaces ||= Boolean(JSON.parse(readFileSync(join(root, 'package.json'), 'utf8')).workspaces);
+    }
+    catch {
+        // No package.json, or an unreadable one.
+    }
+    const role = guessRole(root);
+    if (workspaces || role === 'both')
+        return 'monorepo';
+    if (['serverless.yml', 'serverless.ts', 'wrangler.toml', 'wrangler.jsonc', 'netlify.toml', 'vercel.json', 'template.yaml'].some(has))
+        return 'serverless';
+    return role === 'frontend' ? 'frontend' : 'backend';
+}
+/** Where the backend lives in a monorepo, which is where the key-check package installs. */
+export function detectBackendDir(root) {
+    return ['backend', 'server', 'api', 'apps/api', 'apps/server', 'packages/api', 'packages/server'].find((d) => existsSync(join(root, d))) ?? '';
+}
+async function projectFetch(token, path, init = {}) {
+    return fetch(`${base()}/api/projects/self${path}`, {
+        ...init,
+        headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${token}` },
+        signal: AbortSignal.timeout(20_000),
+    });
+}
+/** This project's settings, or null: unlinked, offline, or a revoked token. */
+export async function readSettings(token) {
+    try {
+        const res = await projectFetch(token, '');
+        return res.ok ? (await res.json()) : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Tells the dashboard what a run did. A failure here is not the run's failure. */
+export async function reportRun(token, run) {
+    try {
+        await projectFetch(token, '/runs', { method: 'POST', body: JSON.stringify({ ...run, version: packageVersion() }) });
+    }
+    catch {
+        // The docs matter more than the log line.
+    }
+}
+export async function runAudit(root, token) {
+    const owner = detectRepo(root).split('/').length === 2 ? detectRepo(root).split('/')[0] : undefined;
+    if (loadConfig(root).config.audit === false) {
+        return { checked: false, reason: 'audit_off', findings: [], files: [], unchecked: [], packages: 0 };
+    }
+    const scan = scanLockfiles(root, owner);
+    const none = { findings: [], files: scan.files, unchecked: scan.unchecked, packages: scan.dependencies.length };
+    try {
+        const res = await projectFetch(token, '/dependencies', {
+            method: 'POST',
+            body: JSON.stringify({ dependencies: scan.dependencies, unchecked: scan.unchecked }),
+        });
+        if (!res.ok)
+            return { checked: false, reason: `status_${res.status}`, ...none };
+        const body = (await res.json());
+        return { ...none, ...body };
+    }
+    catch {
+        return { checked: false, reason: 'unreachable', ...none };
+    }
+}
+const SEVERITY_ORDER = ['critical', 'high', 'moderate', 'low', 'unknown'];
+/** Critical and high by name with their fix; the rest as a count. */
+export function printFindings(answer, log = console.log) {
+    if (!answer.checked) {
+        const why = answer.reason === 'audit_off' ? 'it is turned off for this project' : 'DocuGate could not finish the lookup';
+        log(`  ${yellow('Dependencies not checked')}: ${why}. This does not mean they are safe.`);
+        return;
+    }
+    const urgent = answer.findings.filter((f) => f.severity === 'critical' || f.severity === 'high');
+    if (!answer.findings.length)
+        log(`  ${green('No known vulnerabilities')} in ${plural(answer.packages, 'package')} checked.`);
+    else {
+        log(`  ${red(plural(answer.findings.length, 'known vulnerability').replace('vulnerabilitys', 'vulnerabilities'))} in ${plural(answer.packages, 'package')}. Please fix these:`);
+        for (const f of urgent.sort((a, b) => SEVERITY_ORDER.indexOf(a.severity) - SEVERITY_ORDER.indexOf(b.severity))) {
+            log(`    ${red(f.severity.padEnd(8))} ${bold(`${f.package}@${f.version}`)}  ${f.fixedIn ? `upgrade to ${f.fixedIn}` : 'no fix published yet'}`);
+            log(`             ${dim(`${f.summary}  ${f.url}`)}`);
+        }
+        if (urgent.length < answer.findings.length)
+            log(`    ${dim(`and ${answer.findings.length - urgent.length} of lower severity, listed in the dashboard's Security screen.`)}`);
+    }
+    for (const file of answer.unchecked)
+        log(`  ${yellow('Not checked')}: ${file} could not be read, or uses a private package source.`);
+}
+/** `docugate audit`. Returns the exit code. */
+export async function auditCommand(root, args, env = process.env) {
+    if (args.failOn && !['critical', 'high', 'moderate', 'low'].includes(args.failOn)) {
+        console.error(`${red('error')} --fail-on must be critical, high, moderate or low.`);
+        return 2;
+    }
+    const token = projectToken(root, env);
+    if (!token) {
+        console.error(`${red('error')} This project is not connected. Run docugate connect first.`);
+        return 1;
+    }
+    const answer = await runAudit(root, token);
+    if (args.json)
+        console.log(JSON.stringify(answer, null, 2));
+    else {
+        console.log();
+        console.log(`  ${bold('Dependency check')}  ${dim(`${plural(answer.files.length, 'lockfile')} read`)}`);
+        printFindings(answer);
+        console.log();
+    }
+    if (!answer.checked)
+        return args.failOn ? 1 : 0;
+    if (args.failOn) {
+        const limit = SEVERITY_ORDER.indexOf(args.failOn);
+        if (answer.findings.some((f) => SEVERITY_ORDER.indexOf(f.severity) <= limit))
+            return 1;
+    }
+    return 0;
+}
+/**
+ * Which codebase this folder is: its repository, and where in it. A frontend and
+ * a backend side by side in one repository are two codebases, told apart by
+ * their folder. `path` is `''` at the top of the repository.
+ */
+export function codebaseOf(root, git = defaultGit) {
+    const repo = detectRepo(root);
+    try {
+        const top = git(['rev-parse', '--show-toplevel'], root).trim();
+        const path = relative(resolve(top), resolve(root)).split(sep).join('/');
+        return { repo, path: path.startsWith('..') ? '' : path };
+    }
+    catch {
+        return { repo, path: '' };
+    }
+}
+/** Where a codebase's project token is kept: the repository, and the folder when it is not the whole of it. */
+export const tokenKey = (repo, path) => (path ? `${repo}#${path}` : repo);
+/**
+ * The section a codebase's docs go under. The first codebase of a project is the
+ * top level; each one after it gets a section named after what it is, so two
+ * pages called "Authentication" cannot clash.
+ */
+export function sectionFor(type, sources) {
+    if (!sources.length)
+        return '';
+    const wanted = type === 'monorepo' ? 'app' : type;
+    const taken = new Set(sources.map((s) => s.mount));
+    if (!taken.has(wanted))
+        return wanted;
+    for (let n = 2;; n++)
+        if (!taken.has(`${wanted}-${n}`))
+            return `${wanted}-${n}`;
+}
+/** The project someone named: by slug, `owner/slug` or name, in any case. */
+export function pickProject(choices, wanted) {
+    const w = wanted.trim().toLowerCase();
+    return choices.find((p) => `${p.owner}/${p.slug}`.toLowerCase() === w) ?? choices.find((p) => p.slug.toLowerCase() === w) ?? choices.find((p) => p.name.toLowerCase() === w);
+}
+async function choose(question, options, fallback, ask) {
+    const answer = (await ask(`  ${question} ${dim(`(${options.join(', ')})`)} [${fallback}] `)).trim().toLowerCase();
+    return options.includes(answer) ? answer : fallback;
+}
+const codeOf = (error) => error.code;
+/**
+ * `docugate connect`, run in each codebase of a project: the backend, then the
+ * frontend, whether they are two repositories or two folders of one. It joins
+ * the codebase to the project, and adds its docs to the project's space so they
+ * are published with the rest. Returns the exit code.
+ */
+export async function connectCommand(root, args) {
+    if (args.type && !PROJECT_TYPES.includes(args.type)) {
+        console.error(`${red('error')} --type must be one of ${PROJECT_TYPES.join(', ')}.`);
+        return 2;
+    }
+    if (args.frequency && !FREQUENCIES.includes(args.frequency)) {
+        console.error(`${red('error')} --frequency must be one of ${FREQUENCIES.join(', ')}.`);
+        return 2;
+    }
+    const { repo, path } = codebaseOf(root);
+    const interactive = Boolean(process.stdin.isTTY && process.stdout.isTTY) && !process.env.CI && !args.yes;
+    const rl = interactive ? createInterface({ input: process.stdin, output: process.stdout }) : null;
+    const ask = async (q) => (rl ? rl.question(q) : '');
+    const where = path ? `${repo} ${dim(`(${path}/)`)}` : repo;
+    try {
+        // Signed in first: everything after this is done as someone.
+        const { user } = (await (await apiFetch('/api/auth/session')).json().catch(() => ({ user: null })));
+        if (!user) {
+            if (!rl || !/^(|y|yes)$/i.test((await ask(`  Sign in to DocuGate first? ${dim('(Y/n)')} `)).trim())) {
+                console.error(`${red('error')} Not signed in. Run docugate login, then docugate connect again.`);
+                return 1;
+            }
+            rl.pause();
+            await login(base());
+            rl.resume();
+        }
+        const { projects: choices } = (await (await apiFetch('/api/projects/choices')).json());
+        console.log();
+        console.log(`  ${bold('Connect')} ${where}`);
+        console.log(`  ${dim('Shared with DocuGate: this repository’s name, the tool running the CLI, the outcome of each sync, and the names,')}`);
+        console.log(`  ${dim('versions and lockfile paths of public packages, to check them for known vulnerabilities. Never your code.')}`);
+        console.log();
+        // The docs this codebase brings, as the repository sees the folder.
+        const config = loadConfig(root);
+        const docsDir = [path, config.docsDir].filter(Boolean).join('/');
+        const hasDocs = existsSync(join(root, config.docsDir));
+        let project;
+        if (args.project) {
+            project = pickProject(choices, args.project);
+            if (!project) {
+                console.error(`${red('error')} No project called "${args.project}" that you can connect to. Run docugate connect without --project to see them.`);
+                return 1;
+            }
+        }
+        else if (rl && choices.length) {
+            console.log(`  ${bold('Which project is this codebase part of?')}`);
+            choices.forEach((p, i) => {
+                const parts = p.codebases.map((c) => `${c.type}: ${c.repo}${c.path ? `/${c.path}` : ''}`);
+                console.log(`    ${i + 1}. ${p.name}${p.org ? dim(` (${p.org})`) : ''} ${dim(parts.length ? `· ${parts.join(', ')}` : '· no codebase yet')}`);
+            });
+            console.log(`    ${dim('n. A new project, from this codebase’s docs')}`);
+            const answer = (await ask(`  ${dim('(number, n, or empty for none yet)')} `)).trim().toLowerCase();
+            if (answer === 'n') {
+                if (!hasDocs) {
+                    console.log(`  ${yellow('No docs folder here yet')} (${config.docsDir}/). Run docugate init in this folder to start one, then connect again.`);
+                    return 1;
+                }
+                const name = (await ask(`  What is the project called? [${repo.split('/').at(-1)}] `)).trim() || repo.split('/').at(-1);
+                const res = await apiFetch('/api/spaces', { method: 'POST', body: JSON.stringify({ repo, name, docsDir }) });
+                const { space } = (await res.json());
+                project = { ...space, org: null, sources: [{ repo, docsDir, mount: '' }], codebases: [] };
+                console.log(`  ${green('✓')} Created ${space.name}, published from ${docsDir}/.`);
+            }
+            else {
+                project = choices[Number(answer) - 1];
+            }
+        }
+        else if (choices.length === 1) {
+            project = choices[0];
+        }
+        const type = args.type ?? (await choose('What is this codebase?', PROJECT_TYPES, detectType(root), ask));
+        let backendDir = args.backendDir ?? '';
+        if (type === 'monorepo' && !backendDir) {
+            const found = detectBackendDir(root);
+            backendDir = (await ask(`  Which folder holds the backend? [${found || 'none'}] `)).trim() || found;
+        }
+        const frequency = args.frequency ?? (await choose('How often should docs be checked?', FREQUENCIES, 'weekly', ask));
+        const res = await apiFetch('/api/projects', {
+            method: 'POST',
+            body: JSON.stringify({ repo, path, type, backendDir, frequency, spaceId: project?.id ?? null, audit: !args.noAudit }),
+        });
+        const { token } = (await res.json());
+        const file = TOKENS_FILE();
+        mkdirSync(join(file, '..'), { recursive: true });
+        writeFileSync(file, JSON.stringify({ ...readTokens(), [tokenKey(repo, path)]: token }, null, 2) + '\n', { mode: 0o600 });
+        // Its docs join the project's, unless the space already reads that folder.
+        let section = null;
+        const read = project?.sources.some((s) => s.repo.toLowerCase() === repo.toLowerCase() && s.docsDir === docsDir);
+        if (project && hasDocs && !read) {
+            section = args.section ?? sectionFor(type, project.sources);
+            for (let attempt = 0; attempt < 2; attempt++) {
+                try {
+                    await apiFetch(`/api/spaces/${project.id}/sources`, {
+                        method: 'POST',
+                        body: JSON.stringify({ repo, docsDir, mount: section, label: path ? `${repo.split('/').at(-1)}/${path}` : repo.split('/').at(-1) }),
+                    });
+                    break;
+                }
+                catch (error) {
+                    const code = codeOf(error);
+                    // Two pages at one address: a section of its own settles it.
+                    if (code === 'source_collision' && attempt === 0) {
+                        const fallback = section || (type === 'monorepo' ? 'app' : type);
+                        section = rl ? (await ask(`  Some of its pages share an address with pages already there. Put them under a section? [${fallback}] `)).trim() || fallback : fallback;
+                        continue;
+                    }
+                    section = null;
+                    if (code === 'pro_required_sources')
+                        console.log(`  ${yellow('Its docs were not added.')} One project fed by several codebases needs Pro or an organization plan: ${base()}/pricing`);
+                    else if (code === 'no_repo_access')
+                        console.log(`  ${yellow('Its docs were not added.')} Install the DocuGate GitHub App on ${repo} (${base()}/api/auth/github?install=1), then run docugate connect again.`);
+                    else
+                        console.log(`  ${yellow('Its docs were not added.')} ${error.message}`);
+                    break;
+                }
+            }
+        }
+        console.log();
+        if (project) {
+            const docs = section === null ? (read ? 'Its docs were already published.' : hasDocs ? '' : `It has no docs folder (${config.docsDir}/) to publish yet.`) : section ? `Its docs appear under ${section}.` : 'Its docs are at the top of the space.';
+            console.log(`  ${green('Connected')} ${where} (${type}) to ${bold(project.name)}. ${docs}`);
+            const others = project.codebases.filter((c) => !(c.repo === repo && c.path === path));
+            if (!others.length)
+                console.log(`  ${dim('Run docugate connect in its other codebases, the frontend or the backend, to add them to the same project.')}`);
+        }
+        else {
+            console.log(`  ${green('Connected')} ${where}. Choose its project in the dashboard, under Projects, or run docugate connect again.`);
+        }
+        console.log();
+        if (type === 'frontend')
+            console.log(`  ${dim('A frontend needs no server package.')}`);
+        else {
+            const inside = type === 'monorepo' && backendDir ? `in ${backendDir}` : 'in your backend';
+            console.log(`  ${dim(`To check API keys, install the package ${inside}:`)} npm i docugate`);
+        }
+        console.log();
+        console.log(`  For scheduled syncs, add this token as a GitHub secret. It is shown once:`);
+        console.log(`    gh secret set DOCUGATE_PROJECT_TOKEN --body ${token}`);
+        console.log(`  ${dim('Then run docugate sync init --force so the workflow follows the dashboard.')}`);
+        console.log();
+        return 0;
+    }
+    catch (error) {
+        console.error(`${red('error')} ${error.message}`);
+        return 1;
+    }
+    finally {
+        rl?.close();
+    }
+}

package/dist/rules.d.ts

@@ -49,6 +49,8 @@ export type DocugateConfig = {
     title?: string;
     role?: 'frontend' | 'backend' | 'both';
     /** How often DocuGate checks the docs still match the code. */
+    /** False keeps package names on this machine: no vulnerability check. */
+    audit?: boolean;
     freshness?: 'push' | 'daily' | 'weekly' | 'off';
     /** The DocuGate space the docs publish to, as owner/slug. */
     space?: string;

package/dist/rules.js

@@ -59,4 +59,4 @@ export function firstHeading(content) {
     return heading ? heading[1].trim() : null;
 }
 export const FRESHNESS_VALUES = ['push', 'daily', 'weekly', 'off'];
-export const KNOWN_KEYS = new Set(['$schema', 'docsDir', 'title', 'role', 'freshness', 'space', 'sidebar', 'sync', 'api']);
+export const KNOWN_KEYS = new Set(['$schema', 'docsDir', 'title', 'role', 'freshness', 'audit', 'space', 'sidebar', 'sync', 'api']);

package/dist/sync/command.js

@@ -10,6 +10,7 @@ import { defaultGit, SyncError } from './changes.js';
 import { installHook, removeHook } from './hook.js';
 import { runSync } from './run.js';
 import { repoFromRemote } from './pr.js';
+import { printFindings, projectToken, readSettings, reportRun, runAudit } from '../project.js';
 import { writeWorkflow, WORKFLOW_FILE } from './workflow.js';
 const out = (line = '') => console.log(line);
 /** `docugate sync ...`. Returns the exit code. */
@@ -34,12 +35,37 @@ export async function syncCommand(root, args, deps = {}) {
         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);
+        // A dry run and the git hook stay local: free, private and quick.
+        const token = options.dryRun || quiet ? null : projectToken(root, deps.env ?? process.env);
+        const settings = token ? await readSettings(token) : null;
+        const trigger = (deps.env ?? process.env).GITHUB_EVENT_NAME ?? 'manual';
+        // Only an automatic wake-up waits for its turn. Asking by hand always runs.
+        if (token && settings && !settings.due && (trigger === 'push' || trigger === 'schedule')) {
+            out(`  ${dim(`Not due: this project syncs ${settings.frequency === 'off' ? 'never (off in the dashboard)' : settings.frequency}.`)}`);
+            await reportRun(token, { status: 'skipped', trigger });
+            return 0;
+        }
+        let result;
+        try {
+            result = await runSync(root, options, {
+                ...deps,
+                log: quiet ? undefined : (line) => out(`  ${dim(line)}`),
+                confirm: interactive && !options.yes ? ask : undefined,
+            });
+        }
+        catch (error) {
+            if (token)
+                await reportRun(token, { status: 'failed', trigger, commit: headCommit(root), reason: error instanceof SyncError ? error.message : 'The sync stopped with an unexpected error.' });
+            throw error;
+        }
+        const code = report(result, quiet);
+        if (token) {
+            await reportRun(token, runOutcome(result, trigger, headCommit(root)));
+            // An audit that fails or finds something warns. It never fails the sync.
+            if (settings?.audit)
+                printFindings(await runAudit(root, token));
+        }
+        return code;
     }
     catch (error) {
         // A hook must never be the reason a commit looks broken.
@@ -52,6 +78,18 @@ export async function syncCommand(root, args, deps = {}) {
         throw error;
     }
 }
+function headCommit(root) {
+    try {
+        return defaultGit(['rev-parse', '--short', 'HEAD'], root).trim();
+    }
+    catch {
+        return '';
+    }
+}
+function runOutcome(result, trigger, commit) {
+    const pages = result.written.length;
+    return { status: pages ? 'updated' : 'no_changes', pages, prUrl: result.pr?.url, trigger, commit };
+}
 async function ask(question) {
     const rl = createInterface({ input: process.stdin, output: process.stdout });
     try {
@@ -169,7 +207,7 @@ function syncInit(root, args) {
             /* 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'));
+    const result = writeWorkflow(root, { freshness, docsDir: loaded.docsDir, branch, version: packageVersion(), provider: loaded.config.sync?.provider, managed: Boolean(projectToken(root)) }, 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:`);

package/dist/sync/workflow.d.ts

@@ -8,6 +8,8 @@ export type WorkflowOptions = {
     /** The version to run, so a new release never changes what CI does by surprise. */
     version: string;
     provider?: 'anthropic' | 'openai';
+    /** Connected to DocuGate: it wakes often, and the dashboard decides whether a run is due. */
+    managed?: boolean;
 };
 /** The workflow file, or null when `freshness` is "off". */
 export declare function buildWorkflow(o: WorkflowOptions): string | null;

package/dist/sync/workflow.js

@@ -11,54 +11,60 @@ const CRON = {
 };
 /** The workflow file, or null when `freshness` is "off". */
 export function buildWorkflow(o) {
-    if (o.freshness === 'off')
+    if (o.freshness === 'off' && !o.managed)
         return null;
     const secret = o.provider === 'openai' ? 'OPENAI_API_KEY' : 'ANTHROPIC_API_KEY';
     const docs = o.docsDir === '.' ? null : o.docsDir.replace(/^\/|\/$/g, '');
-    const on = o.freshness === 'push'
-        ? [
-            '  push:',
-            `    branches: [${o.branch}]`,
-            '    paths-ignore:',
-            ...(docs ? [`      - '${docs}/**'`] : []),
-            `      - '.docugate/**'`,
-        ]
-        : ['  schedule:', `    - cron: '${CRON[o.freshness]}'`];
-    return `# Written by \`docugate sync init\`. It keeps your docs in step with your code.
-# ${o.freshness === 'push' ? 'Runs on every push' : o.freshness === 'daily' ? 'Runs every day' : 'Runs every Monday'}, reads what changed, and opens a pull request with the docs
-# edits. Nothing is merged for you. Change how often in docugate.json ("freshness"),
-# then run \`docugate sync init --force\`.
-name: DocuGate sync
-
-on:
-${on.join('\n')}
-  workflow_dispatch:
-
-permissions:
-  contents: write
-  pull-requests: write
-
-# One sync at a time, so two runs never fight over the same branch.
-concurrency:
-  group: docugate-sync
-  cancel-in-progress: false
-
-jobs:
-  sync:
-    # A sync's own commits and branch never start another sync.
-    if: \${{ !contains(github.event.head_commit.message, '${SYNC_TAG}') && !startsWith(github.ref_name, '${SYNC_BRANCH_PREFIX}') }}
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-        with:
-          fetch-depth: 0
-      - uses: actions/setup-node@v4
-        with:
-          node-version: 22
-      - run: npx --yes docugate@${o.version} sync --pr --yes
-        env:
-          ${secret}: \${{ secrets.${secret} }}
-          GITHUB_TOKEN: \${{ secrets.GITHUB_TOKEN }}
+    const push = [
+        '  push:',
+        `    branches: [${o.branch}]`,
+        '    paths-ignore:',
+        ...(docs ? [`      - '${docs}/**'`] : []),
+        `      - '.docugate/**'`,
+    ];
+    const on = o.managed
+        ? [...push, '  schedule:', `    - cron: '${CRON.daily}'`]
+        : o.freshness === 'push'
+            ? push
+            : ['  schedule:', `    - cron: '${CRON[o.freshness]}'`];
+    const when = o.managed
+        ? `Wakes on every push and every day; the DocuGate dashboard decides whether a sync is due.`
+        : null;
+    return `# Written by \`docugate sync init\`. It keeps your docs in step with your code.
+# ${when ?? ''}${when ? '' : o.freshness === 'push' ? 'Runs on every push' : o.freshness === 'daily' ? 'Runs every day' : 'Runs every Monday'}, reads what changed, and opens a pull request with the docs
+# edits. Nothing is merged for you. Change how often in docugate.json ("freshness"),
+# then run \`docugate sync init --force\`.
+name: DocuGate sync
+
+on:
+${on.join('\n')}
+  workflow_dispatch:
+
+permissions:
+  contents: write
+  pull-requests: write
+
+# One sync at a time, so two runs never fight over the same branch.
+concurrency:
+  group: docugate-sync
+  cancel-in-progress: false
+
+jobs:
+  sync:
+    # A sync's own commits and branch never start another sync.
+    if: \${{ !contains(github.event.head_commit.message, '${SYNC_TAG}') && !startsWith(github.ref_name, '${SYNC_BRANCH_PREFIX}') }}
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+      - run: npx --yes docugate@${o.version} sync --pr --yes
+        env:
+          ${secret}: \${{ secrets.${secret} }}
+          GITHUB_TOKEN: \${{ secrets.GITHUB_TOKEN }}${o.managed ? '\n          DOCUGATE_PROJECT_TOKEN: \${{ secrets.DOCUGATE_PROJECT_TOKEN }}' : ''}
 `;
 }
 /** Write the workflow. An existing one that differs is left alone unless `force`. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "docugate",
-  "version": "0.3.1",
+  "version": "0.4.1",
   "description": "Command-line tools for DocuGate: set up, check and prepare the documentation DocuGate reads straight from your repository. Also checks DocuGate API keys from Express, Hono and Fastify.",
   "type": "module",
   "bin": {