docugate 0.3.1 → 0.4.1

package/dist/api.d.ts

@@ -1,3 +1,5 @@
+/** The tool running the CLI, from what it sets in the environment. */
+export declare function detectAgent(env?: NodeJS.ProcessEnv): string;
 /** Module-level default, captured at import time (used by CLI commands). */
 export declare const BASE_URL: string;
 export declare function apiFetch(path: string, init?: RequestInit): Promise<Response>;

package/dist/api.js

@@ -1,4 +1,26 @@
+import { readFileSync } from 'node:fs';
+import { basename } from 'node:path';
 import { loadCredentials, saveCredentials } from './auth.js';
+const CLI_VERSION = (() => {
+    try {
+        return JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version ?? '';
+    }
+    catch {
+        return '';
+    }
+})();
+/** The tool running the CLI, from what it sets in the environment. */
+export function detectAgent(env = process.env) {
+    if (env.CLAUDECODE)
+        return 'Claude Code';
+    if (env.CURSOR_TRACE_ID || env.CURSOR_AGENT)
+        return 'Cursor';
+    if (env.GITHUB_COPILOT_CLI || env.COPILOT_AGENT)
+        return 'Copilot';
+    if (env.CI)
+        return 'CI';
+    return 'Terminal';
+}
 /** Module-level default, captured at import time (used by CLI commands). */
 export const BASE_URL = process.env.DOCUGATE_URL ?? 'https://www.trydocugate.site';
 const ERROR_MESSAGES = {
@@ -10,6 +32,13 @@ const ERROR_MESSAGES = {
     repo_exists: 'You already have a repository with this name on GitHub',
     app_permission: "DocuGate isn't allowed to create repositories on your account yet. Accept the DocuGate app's updated permissions at https://github.com/settings/installations, then try again",
     github_required: 'Sign in with GitHub to create a space',
+    source_collision: 'Some pages would share an address with pages the space already has. Put them under a section',
+    duplicate_source: 'The space already reads that folder of that repository',
+    duplicate_mount: 'Another repository already uses that section. Choose another name',
+    bad_mount: 'A section is a short name: letters, numbers and dashes, up to three levels',
+    bad_path: 'DocuGate could not read which folder of the repository this is',
+    bad_space: 'That project is not one you can connect to',
+    forbidden: 'You can only change a space you own, or one whose repository you can push to',
 };
 function friendlyError(code) {
     return ERROR_MESSAGES[code] ?? `DocuGate said: ${code}`;
@@ -24,6 +53,11 @@ export async function apiFetch(path, init = {}) {
     };
     if (creds) {
         headers['Authorization'] = `Bearer ${creds.token}`;
+        // What the dashboard's Agents screen lists: this folder's name and the tool
+        // running the CLI. No paths, no file contents.
+        headers['x-docugate-project'] = basename(process.cwd());
+        headers['x-docugate-agent'] = detectAgent();
+        headers['x-docugate-version'] = CLI_VERSION;
     }
     // Re-read the env at call time so tests that set DOCUGATE_URL after import work.
     const base = process.env.DOCUGATE_URL ?? 'https://www.trydocugate.site';

package/dist/cli.js

@@ -4,6 +4,7 @@ import { mkdirSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { createInterface } from 'node:readline/promises';
 import { parseArgs, UsageError } from './args.js';
+import { auditCommand, connectCommand } from './project.js';
 import { banner, packageVersion } from './banner.js';
 import { check } from './check.js';
 import { COMMANDS, findCommand, renderCommandHelp, renderCompletion, renderGroupHelp, renderHelp } from './commands.js';
@@ -210,6 +211,23 @@ async function run(argv) {
             console.log(session.user ? `@${session.user.githubLogin}` : `Not signed in. Run ${hint('login')}.`);
             return;
         }
+        case 'connect': {
+            process.exitCode = await connectCommand(root, {
+                // --space is what it was called before a project could have several codebases.
+                project: one('project') ?? one('space'),
+                section: one('section'),
+                frequency: one('frequency'),
+                type: one('type'),
+                backendDir: one('backend-dir'),
+                noAudit: args.bools.has('no-audit'),
+                yes: args.bools.has('yes') || noInput,
+            });
+            return;
+        }
+        case 'audit': {
+            process.exitCode = await auditCommand(root, { failOn: one('fail-on'), json: args.bools.has('json') });
+            return;
+        }
         case 'developers': {
             if (noInput && !args.bools.has('yes'))
                 fail('developers asks questions. Run it in a terminal, or add --yes to take every default.');

package/dist/commands.js

@@ -163,6 +163,38 @@ export const COMMANDS = [
         examples: ['docugate logout'],
         account: 'none',
     },
+    {
+        name: 'connect',
+        group: 'Account',
+        summary: 'Connect this codebase to a project, and publish its docs with the project’s',
+        description: 'Run it in each codebase of a project: the backend, then the frontend, whether they are two repositories or two folders of one. ' +
+            'It asks which project the codebase belongs to, or starts a new one, and adds its docs folder to the project’s space, under a section of its own when the project already has docs. ' +
+            'It shares the repository name, the tool running the CLI, the outcome of each sync, and the names and versions of public packages in your lockfiles. Never your code.',
+        flags: [
+            { name: 'project', value: 'name', description: 'The project to join, by slug, owner/slug or name (--space still works)' },
+            { name: 'section', value: 'name', description: 'The section its docs go under (default: frontend, backend… after the first codebase)' },
+            { name: 'frequency', value: 'when', description: 'How often docs are checked: push, daily, weekly or off' },
+            { name: 'type', value: 'kind', description: 'frontend, backend, serverless or monorepo (default: detected)' },
+            { name: 'backend-dir', value: 'folder', description: 'In a monorepo, the folder that holds the backend' },
+            { name: 'no-audit', description: 'Do not send package names to check for vulnerabilities' },
+            YES,
+        ],
+        examples: ['docugate connect', 'docugate connect --project payments --type backend --yes', 'docugate connect --project payments --type frontend --section web --yes'],
+        account: 'required',
+    },
+    {
+        name: 'audit',
+        group: 'Checks',
+        summary: 'Check this project’s packages for known vulnerabilities',
+        description: 'Reads your lockfiles without installing or running anything, and checks public packages against the OSV.dev vulnerability database. ' +
+            'Private packages stay on your machine. It only warns, unless you ask it to fail with --fail-on.',
+        flags: [
+            { name: 'fail-on', value: 'severity', description: 'Exit 1 at this severity or above: critical, high, moderate or low' },
+            { name: 'json', description: 'Print the result as JSON' },
+        ],
+        examples: ['docugate audit', 'docugate audit --fail-on high'],
+        account: 'required',
+    },
     {
         name: 'whoami',
         group: 'Account',

package/dist/init.d.ts

@@ -19,6 +19,7 @@ export declare function init(root: string, opts?: {
     dir?: string;
     title?: string;
 }): InitResult;
+export declare const AGENTS_FILE = "AGENTS.md";
 export type Role = 'frontend' | 'backend' | 'both';
 /** Minimal I/O surface so the flow can be driven by tests without a terminal. */
 export interface IO {

package/dist/init.js

@@ -38,12 +38,76 @@ export function init(root, opts = {}) {
     else {
         mkdirSync(base, { recursive: true });
         writeFileSync(join(base, 'index.md'), `# ${title}\n\nWelcome. This page is the landing page of your DocuGate space.\n\n` +
+            `New here? Read [Start here](start-here.md) first.\n\n` +
             `Every \`.md\` file in \`${docsDir}/\` becomes a page, and every folder becomes a\n` +
             `section in the sidebar. The first \`# heading\` in a file is its title.\n`);
         created.push(`${docsDir}/index.md`);
+        writeFileSync(join(base, 'start-here.md'), startHere(title));
+        created.push(`${docsDir}/start-here.md`);
+    }
+    // For the AI tools that work in this repository: where the docs are, and how
+    // they are written. Never touched if the repository already has one.
+    if (existsSync(join(root, AGENTS_FILE))) {
+        kept.push(AGENTS_FILE);
+    }
+    else {
+        writeFileSync(join(root, AGENTS_FILE), agentsGuide(title, docsDir));
+        created.push(AGENTS_FILE);
     }
     return { created, kept, docsDir };
 }
+export const AGENTS_FILE = 'AGENTS.md';
+/** The page a new reader opens first: what is here, and how to find the rest. */
+function startHere(title) {
+    return `# Start here
+
+This is the documentation for ${title}. Five minutes here saves an hour later.
+
+## What is in these docs
+
+- **Guides** walk through one task from start to finish.
+- **Reference** pages list every option, for looking things up.
+- **Runbooks** say what to do when something breaks.
+
+Replace this list with the sections your docs actually have.
+
+## Finding things
+
+- Press \`/\` to search every page.
+- The sidebar follows the folders in the repository, so a page lives where you
+  would look for it.
+
+## Getting help
+
+Say where to ask questions: a channel, an email address, or a person.
+`;
+}
+/** AGENTS.md: what an AI coding tool should know before it writes docs here. */
+function agentsGuide(title, docsDir) {
+    return `# AGENTS.md
+
+Guidance for AI coding tools working in ${title}.
+
+## Documentation
+
+- The docs live in \`${docsDir}/\` and are published with DocuGate. Every push
+  updates the site; there is no build step.
+- Every \`.md\` file is a page and every folder is a sidebar section. The first
+  \`# heading\` in a file is its title.
+- \`${docsDir}/index.md\` is the landing page. \`${docsDir}/start-here.md\` is the
+  first page a new reader opens.
+- When you change behaviour, update the page that describes it in the same
+  change. Prefer editing an existing page to adding a new one.
+- Run \`docugate check\` before committing: it confirms every page parses and
+  every link resolves.
+
+## Writing style
+
+- Short sentences, plain words, one idea per paragraph.
+- Name commands, files and settings exactly, in backticks.
+- Lead with the task the reader came to do, then the details.
+`;
+}
 export function makeDefaultIO() {
     const isTTY = Boolean(process.stdin.isTTY);
     return {

package/dist/lockfiles.d.ts

@@ -0,0 +1,24 @@
+export type Dependency = {
+    ecosystem: 'npm' | 'PyPI' | 'Go';
+    name: string;
+    version: string;
+    /** Listed by the project itself. Null when the lockfile cannot say. */
+    direct?: boolean | null;
+    /** For an indirect package, the direct one that brings it in, when known. */
+    via?: string | null;
+    lockfile?: string;
+};
+export type LockfileScan = {
+    dependencies: Dependency[];
+    files: string[];
+    unchecked: string[];
+};
+type Parser = (text: string, ownOwner?: string) => Dependency[];
+export declare const parsePackageLock: Parser;
+export declare const parsePnpmLock: Parser;
+export declare const parseYarnLock: Parser;
+export declare const parseRequirements: Parser;
+export declare const parseGoMod: Parser;
+/** Every lockfile in the project, monorepo folders included, within a depth limit. */
+export declare function scanLockfiles(root: string, ownOwner?: string): LockfileScan;
+export {};

package/dist/lockfiles.js

@@ -0,0 +1,203 @@
+import { readdirSync, readFileSync, statSync } from 'node:fs';
+import { join, relative } from 'node:path';
+const PUBLIC_NPM = /^https:\/\/registry\.(npmjs\.org|yarnpkg\.com)\//;
+const SKIP_DIRS = new Set(['node_modules', '.git', 'dist', 'build', 'vendor', '.next', '.venv', 'venv', '__pycache__', 'target', 'coverage']);
+const MAX_DEPTH = 4;
+const MAX_DIRS = 2000;
+export const parsePackageLock = (text) => {
+    const lock = JSON.parse(text);
+    const out = [];
+    if (lock.packages) {
+        for (const [path, entry] of Object.entries(lock.packages)) {
+            const at = path.lastIndexOf('node_modules/');
+            if (at < 0 || entry.link || !entry.version || !entry.resolved || !PUBLIC_NPM.test(entry.resolved))
+                continue;
+            out.push({ ecosystem: 'npm', name: path.slice(at + 'node_modules/'.length), version: entry.version });
+        }
+        addViaFromLock(lock.packages, out);
+    }
+    else if (lock.dependencies) {
+        collectV1(lock.dependencies, out);
+    }
+    else {
+        throw new Error('no packages listed');
+    }
+    return out;
+};
+/** Walks down from each direct package, so an indirect one can name who brought it in. */
+function addViaFromLock(packages, out) {
+    const root = packages[''];
+    const direct = Object.keys({ ...root?.dependencies, ...root?.devDependencies });
+    const via = new Map();
+    for (const top of direct) {
+        const queue = [top];
+        const seen = new Set(queue);
+        while (queue.length) {
+            const name = queue.shift();
+            for (const child of Object.keys(packages[`node_modules/${name}`]?.dependencies ?? {})) {
+                if (seen.has(child))
+                    continue;
+                seen.add(child);
+                if (!via.has(child) && !direct.includes(child))
+                    via.set(child, top);
+                queue.push(child);
+            }
+        }
+    }
+    for (const dep of out)
+        if (via.has(dep.name))
+            dep.via = via.get(dep.name);
+}
+function collectV1(deps, out) {
+    for (const [name, entry] of Object.entries(deps)) {
+        if (entry.version && entry.resolved && PUBLIC_NPM.test(entry.resolved))
+            out.push({ ecosystem: 'npm', name, version: entry.version });
+        if (entry.dependencies)
+            collectV1(entry.dependencies, out);
+    }
+}
+export const parsePnpmLock = (text) => {
+    const out = [];
+    const lines = text.split(/\r?\n/);
+    const start = lines.findIndex((l) => /^packages:\s*$/.test(l));
+    if (start < 0)
+        throw new Error('no packages section');
+    for (let i = start + 1; i < lines.length; i++) {
+        const line = lines[i];
+        if (/^\S/.test(line))
+            break;
+        const key = line.match(/^ {2}'?\/?((?:@[^/]+\/)?[^@/\s']+)[@/](\d[^:(\s']*)[^:]*'?:/);
+        if (!key)
+            continue;
+        // The next line says where it came from. A tarball means not the registry.
+        if (/tarball:|type: git|directory:/.test(lines[i + 1] ?? ''))
+            continue;
+        out.push({ ecosystem: 'npm', name: key[1], version: key[2] });
+    }
+    return out;
+};
+export const parseYarnLock = (text) => {
+    const out = [];
+    for (const block of text.split(/\r?\n\r?\n/)) {
+        const head = block.split(/\r?\n/).find((l) => /^\S.*:\s*$/.test(l) && !l.startsWith('#') && !l.startsWith('__metadata'));
+        if (!head)
+            continue;
+        const name = head.replace(/^"/, '').match(/^(@?[^@]+)@/)?.[1];
+        const version = block.match(/^\s+version:?\s+"?([^"\s]+)"?/m)?.[1];
+        if (!name || !version)
+            continue;
+        const resolved = block.match(/^\s+resolved\s+"([^"]+)"/m)?.[1];
+        const berry = block.match(/^\s+resolution:\s+"[^"]*@(npm):/m);
+        if (resolved ? !PUBLIC_NPM.test(resolved) : !berry)
+            continue;
+        out.push({ ecosystem: 'npm', name, version });
+    }
+    return out;
+};
+export const parseRequirements = (text) => {
+    // A custom index means these names may be private, so none of them leave.
+    if (/^\s*(--index-url|-i\s|--extra-index-url|--find-links)/m.test(text))
+        throw new Error('uses a custom package index');
+    const out = [];
+    for (const raw of text.split(/\r?\n/)) {
+        const m = raw.split('#')[0].trim().match(/^([A-Za-z0-9][\w.-]*)(?:\[[^\]]*\])?\s*==\s*([\w.!+-]+)/);
+        if (m)
+            out.push({ ecosystem: 'PyPI', name: m[1], version: m[2], direct: true });
+    }
+    return out;
+};
+export const parseGoMod = (text, ownOwner) => {
+    const out = [];
+    const replaced = new Set([...text.matchAll(/^\s*(?:replace\s+)?(\S+)(?:\s+v\S+)?\s+=>/gm)].map((m) => m[1]));
+    const add = (mod, version, direct) => {
+        if (replaced.has(mod))
+            return;
+        // Modules of the same GitHub account are as likely private as not.
+        if (ownOwner && mod.toLowerCase().startsWith(`github.com/${ownOwner.toLowerCase()}/`))
+            return;
+        out.push({ ecosystem: 'Go', name: mod, version: version.replace(/^v/, ''), direct });
+    };
+    let inBlock = false;
+    for (const raw of text.split(/\r?\n/)) {
+        const line = raw.split('//')[0].trim();
+        if (/^require\s*\($/.test(line))
+            inBlock = true;
+        else if (line === ')')
+            inBlock = false;
+        else {
+            const m = inBlock ? line.match(/^(\S+)\s+(v\S+)$/) : line.match(/^require\s+(\S+)\s+(v\S+)$/);
+            if (m)
+                add(m[1], m[2], !/\/\/\s*indirect/.test(raw));
+        }
+    }
+    return out;
+};
+const PARSERS = {
+    'package-lock.json': parsePackageLock,
+    'pnpm-lock.yaml': parsePnpmLock,
+    'yarn.lock': parseYarnLock,
+    'requirements.txt': parseRequirements,
+    'go.mod': parseGoMod,
+};
+/**
+ * The packages this folder's package.json asks for. Null when it cannot say: none
+ * there, or a workspace root, whose real lists are in each package's own file.
+ */
+function directNames(dir) {
+    try {
+        const pkg = JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8'));
+        if (pkg.workspaces)
+            return null;
+        return new Set(Object.keys({ ...pkg.dependencies, ...pkg.devDependencies, ...pkg.optionalDependencies }));
+    }
+    catch {
+        return null;
+    }
+}
+/** Every lockfile in the project, monorepo folders included, within a depth limit. */
+export function scanLockfiles(root, ownOwner) {
+    const seen = new Map();
+    const files = [];
+    const unchecked = [];
+    let dirs = 0;
+    const visit = (dir, depth) => {
+        if (++dirs > MAX_DIRS)
+            return;
+        let names;
+        try {
+            names = readdirSync(dir);
+        }
+        catch {
+            return;
+        }
+        for (const name of names) {
+            const path = join(dir, name);
+            const parser = PARSERS[name];
+            if (parser) {
+                const shown = relative(root, path).replace(/\\/g, '/');
+                try {
+                    const own = directNames(dir);
+                    for (const dep of parser(readFileSync(path, 'utf8'), ownOwner)) {
+                        const direct = dep.direct ?? (dep.ecosystem === 'npm' && own ? own.has(dep.name) : null);
+                        seen.set(`${dep.ecosystem}:${dep.name}@${dep.version}`, { ...dep, direct, lockfile: shown });
+                    }
+                    files.push(shown);
+                }
+                catch {
+                    unchecked.push(shown);
+                }
+            }
+            else if (depth < MAX_DEPTH && !SKIP_DIRS.has(name) && !name.startsWith('.')) {
+                try {
+                    if (statSync(path).isDirectory())
+                        visit(path, depth + 1);
+                }
+                catch {
+                    // Gone or unreadable: not a lockfile we can speak for.
+                }
+            }
+        }
+    };
+    visit(root, 0);
+    return { dependencies: [...seen.values()], files, unchecked };
+}

package/dist/project.d.ts

@@ -0,0 +1,119 @@
+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 codebase: CI's secret first, then what `connect` saved for this folder, then for its repository. */
+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 = {
+    /** The project to join: its slug, `owner/slug`, or name. */
+    project?: string;
+    frequency?: string;
+    type?: string;
+    backendDir?: string;
+    /** The section this codebase's docs go under in the project's space. Empty is the top level. */
+    section?: string;
+    noAudit: boolean;
+    yes: boolean;
+};
+/** A project `connect` can join: a space, with the codebases and docs folders already feeding it. */
+export type ProjectChoice = {
+    id: string;
+    name: string;
+    owner: string;
+    slug: string;
+    org: string | null;
+    sources: {
+        repo: string;
+        docsDir: string;
+        mount: string;
+    }[];
+    codebases: {
+        repo: string;
+        path: string;
+        type: string;
+    }[];
+};
+/**
+ * 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 declare function codebaseOf(root: string, git?: (args: string[], cwd: string) => string): {
+    repo: string;
+    path: string;
+};
+/** Where a codebase's project token is kept: the repository, and the folder when it is not the whole of it. */
+export declare const tokenKey: (repo: string, path: string) => string;
+/**
+ * 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 declare function sectionFor(type: ProjectType, sources: {
+    mount: string;
+}[]): string;
+/** The project someone named: by slug, `owner/slug` or name, in any case. */
+export declare function pickProject(choices: ProjectChoice[], wanted: string): ProjectChoice | undefined;
+/**
+ * `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 declare function connectCommand(root: string, args: ConnectArgs): Promise<number>;