docugate 0.3.0 → 0.4.0

package/dist/project.d.ts

@@ -0,0 +1,72 @@
+export declare const PROJECT_TYPES: readonly ["frontend", "backend", "serverless", "monorepo"];
+export type ProjectType = (typeof PROJECT_TYPES)[number];
+export declare const FREQUENCIES: readonly ["push", "daily", "weekly", "off"];
+export type Frequency = (typeof FREQUENCIES)[number];
+export type ProjectSettings = {
+    name: string;
+    type: ProjectType;
+    frequency: Frequency;
+    audit: boolean;
+    due: boolean;
+    space: {
+        owner: string;
+        slug: string;
+        name: string;
+    } | null;
+};
+export type Finding = {
+    id: string;
+    package: string;
+    version: string;
+    severity: 'critical' | 'high' | 'moderate' | 'low' | 'unknown';
+    summary: string;
+    fixedIn: string | null;
+    url: string;
+};
+/** `owner/name` from the git remote, or the folder's name without one. */
+export declare function detectRepo(root: string): string;
+/** The token for this repository: CI's secret first, then what `connect` saved. */
+export declare function projectToken(root: string, env?: NodeJS.ProcessEnv): string | null;
+/** A suggestion only. The person confirms it, and the dashboard can change it. */
+export declare function detectType(root: string): ProjectType;
+/** Where the backend lives in a monorepo, which is where the key-check package installs. */
+export declare function detectBackendDir(root: string): string;
+/** This project's settings, or null: unlinked, offline, or a revoked token. */
+export declare function readSettings(token: string): Promise<ProjectSettings | null>;
+export type RunReport = {
+    status: 'updated' | 'no_changes' | 'skipped' | 'failed';
+    pages?: number;
+    prUrl?: string;
+    commit?: string;
+    trigger?: string;
+    reason?: string;
+};
+/** Tells the dashboard what a run did. A failure here is not the run's failure. */
+export declare function reportRun(token: string, run: RunReport): Promise<void>;
+export type AuditAnswer = {
+    checked: boolean;
+    reason?: string;
+    findings: Finding[];
+    files: string[];
+    unchecked: string[];
+    packages: number;
+};
+export declare function runAudit(root: string, token: string): Promise<AuditAnswer>;
+/** Critical and high by name with their fix; the rest as a count. */
+export declare function printFindings(answer: AuditAnswer, log?: (line: string) => void): void;
+export type AuditArgs = {
+    failOn?: string;
+    json: boolean;
+};
+/** `docugate audit`. Returns the exit code. */
+export declare function auditCommand(root: string, args: AuditArgs, env?: NodeJS.ProcessEnv): Promise<number>;
+export type ConnectArgs = {
+    space?: string;
+    frequency?: string;
+    type?: string;
+    backendDir?: string;
+    noAudit: boolean;
+    yes: boolean;
+};
+/** `docugate connect`. Returns the exit code. */
+export declare function connectCommand(root: string, args: ConnectArgs): Promise<number>;

package/dist/project.js

@@ -0,0 +1,246 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { basename, join } from 'node:path';
+import { createInterface } from 'node:readline/promises';
+import { apiFetch } from './api.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 repository: CI's secret first, then what `connect` saved. */
+export function projectToken(root, env = process.env) {
+    return env.DOCUGATE_PROJECT_TOKEN || readTokens()[detectRepo(root)] || 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;
+}
+async function choose(question, options, fallback, ask) {
+    const answer = (await ask(`  ${question} ${dim(`(${options.join(', ')})`)} [${fallback}] `)).trim().toLowerCase();
+    return options.includes(answer) ? answer : fallback;
+}
+/** `docugate connect`. 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 = detectRepo(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) : '');
+    try {
+        const { spaces } = (await (await apiFetch('/api/spaces/mine')).json());
+        console.log();
+        console.log(`  ${bold('Connect')} ${repo}`);
+        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();
+        let spaceId = null;
+        if (args.space) {
+            const match = spaces.find((s) => s.slug === args.space);
+            if (!match) {
+                console.error(`${red('error')} You have no space called "${args.space}".`);
+                return 1;
+            }
+            spaceId = match.id;
+        }
+        else if (rl && spaces.length) {
+            spaces.forEach((s, i) => console.log(`    ${i + 1}. ${s.name} ${dim(s.slug)}`));
+            const n = Number((await ask(`  Which documentation does this project update? ${dim('(number, or empty for none yet)')} `)).trim());
+            spaceId = spaces[n - 1]?.id ?? null;
+        }
+        else if (spaces.length === 1) {
+            spaceId = spaces[0].id;
+        }
+        const guessed = detectType(root);
+        const type = args.type ?? (await choose('What kind of project is this?', PROJECT_TYPES, guessed, 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, type, backendDir, frequency, spaceId, audit: !args.noAudit }),
+        });
+        const { token } = (await res.json());
+        const path = TOKENS_FILE();
+        mkdirSync(join(path, '..'), { recursive: true });
+        writeFileSync(path, JSON.stringify({ ...readTokens(), [repo]: token }, null, 2) + '\n', { mode: 0o600 });
+        console.log();
+        console.log(`  ${green('Connected.')} Change any of this in the dashboard, under Projects.`);
+        console.log();
+        if (type === 'frontend')
+            console.log(`  ${dim('A frontend needs no server package.')}`);
+        else {
+            const where = type === 'monorepo' && backendDir ? `in ${backendDir}` : 'in your backend';
+            console.log(`  ${dim(`To check API keys, install the package ${where}:`)} 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/select.d.ts

@@ -41,7 +41,9 @@ export type KeyResult<T> = {
     state: PickerState;
 };
 /** One key press, applied to the picker's state. */
-export declare function handleKey<T>(choices: Choice<T>[], state: PickerState, str: string | undefined, key: Key, rows: number): KeyResult<T>;
+export declare function handleKey<T>(choices: Choice<T>[], state: PickerState, str: string | undefined, key: Key, rows: number, 
+/** False for a short menu: letters do not search, a number picks, q quits. */
+search?: boolean): KeyResult<T>;
 export type RenderOptions = {
     title?: string;
     width: number;
@@ -49,6 +51,8 @@ export type RenderOptions = {
     footer?: string;
     note?: string;
     legend?: boolean;
+    /** Just the note and a numbered list: no search, rules, description, legend or key hints. */
+    minimal?: boolean;
 };
 /** The picker as lines of text. */
 export declare function renderPicker<T>(choices: Choice<T>[], state: PickerState, o: RenderOptions): string[];
@@ -65,6 +69,8 @@ export type SelectOptions<T> = {
     /** How many choices show at once. */
     rows?: number;
     legend?: boolean;
+    /** The short form: see renderPicker. Every choice shows; a number picks one. */
+    minimal?: boolean;
 };
 /** Whether there is a real terminal to draw a picker in. */
 export declare const canPick: (io?: PickerIO) => boolean;

package/dist/select.js

@@ -43,8 +43,21 @@ function step(list, from, dir) {
     return clamp(from + dir, 0, Math.max(0, list.length - 1));
 }
 /** One key press, applied to the picker's state. */
-export function handleKey(choices, state, str, key, rows) {
+export function handleKey(choices, state, str, key, rows, 
+/** False for a short menu: letters do not search, a number picks, q quits. */
+search = true) {
     const list = filterChoices(choices, state.query);
+    if (!search && str && !key.ctrl && !key.meta) {
+        if (str === 'q')
+            return { done: 'cancelled' };
+        const n = Number(str);
+        if (Number.isInteger(n) && n >= 1 && n <= list.length) {
+            const choice = list[n - 1];
+            return choice.disabled ? { done: 'blocked', reason: choice.disabled, state: { ...state, cursor: n - 1 } } : { done: 'chosen', choice };
+        }
+        if (key.name !== 'return' && key.name !== 'enter')
+            return { state };
+    }
     const move = (cursor) => {
         const c = clamp(cursor, 0, Math.max(0, list.length - 1));
         const top = c < state.top ? c : c >= state.top + rows ? c - rows + 1 : state.top;
@@ -94,9 +107,28 @@ const fit = (text, width) => {
     // Over width: cut the plain text. Color is not worth keeping on a line this long.
     return `${plain.slice(0, Math.max(0, width - 1))}…`;
 };
+/**
+ * The short form: the note, then every choice on its own numbered line. Short
+ * enough never to scroll, and every line cut to the width so none can wrap,
+ * which is what kept the redraw in step with what is on screen.
+ */
+function renderMinimal(list, state, o) {
+    const lines = [];
+    if (o.note)
+        lines.push(`  ${o.note}`, '');
+    list.forEach((c, i) => {
+        const at = i === state.cursor;
+        const n = dim(String(i + 1).padStart(2));
+        const label = at ? bold(gold(c.label)) : c.disabled ? dim(c.label) : c.label;
+        lines.push(`  ${at ? gold('❯') : ' '} ${n}  ${label}`);
+    });
+    return lines.map((l) => fit(l, o.width - 1));
+}
 /** The picker as lines of text. */
 export function renderPicker(choices, state, o) {
     const list = filterChoices(choices, state.query);
+    if (o.minimal)
+        return renderMinimal(list, state, o);
     const rule = dim('─'.repeat(Math.max(10, Math.min(o.width - 4, 78))));
     const lines = [];
     const w = o.width - 2;
@@ -156,7 +188,7 @@ export const canPick = (io = { stdin: process.stdin, stdout: process.stdout }) =
  */
 export function select(options, io = { stdin: process.stdin, stdout: process.stdout }) {
     const { stdin, stdout } = io;
-    const rows = Math.max(3, Math.min(options.rows ?? 8, (stdout.rows ?? 24) - 14));
+    const rows = options.minimal ? options.choices.length : Math.max(3, Math.min(options.rows ?? 8, (stdout.rows ?? 24) - 14));
     const color = colorOn();
     let state = { query: '', cursor: initialCursor(options.choices), top: 0 };
     state.top = Math.max(0, state.cursor - rows + 1);
@@ -171,6 +203,7 @@ export function select(options, io = { stdin: process.stdin, stdout: process.std
             footer: options.footer,
             note,
             legend: options.legend,
+            minimal: options.minimal,
         });
         stdout.write(`${drawn ? `\x1b[${drawn}A\r` : ''}\x1b[0J${hint(lines.join('\n'))}\n`);
         drawn = lines.length;
@@ -193,7 +226,7 @@ export function select(options, io = { stdin: process.stdin, stdout: process.std
             resolve(value);
         };
         const onKey = (str, key = {}) => {
-            const result = handleKey(options.choices, state, str, key, rows);
+            const result = handleKey(options.choices, state, str, key, rows, !options.minimal);
             if ('done' in result) {
                 if (result.done === 'cancelled')
                     return finish(null);

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.0",
+  "version": "0.4.0",
   "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": {