docugate 0.3.1 → 0.4.0

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/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.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": {