docugate 0.4.2 → 0.4.4

package/README.md

@@ -153,13 +153,15 @@ Everything it sets stays editable in the space's settings on [trydocugate.site](
 
 Documentation goes stale because updating it is a chore nobody owns. `docugate sync` does the chore: it reads what changed in the code, finds the pages those changes made wrong, asks an AI model to correct them, and gives you the edits to review.
 
+The easy way is the menu: run `docugate` and pick **Update the docs with recent changes**. It asks which changes to catch up on (since the last update, today, this week, this month, or since a commit you pick), shows the pages they touch, then writes the edits into your files or a pull request. The first time, it asks for an AI key and keeps it on your computer. That is `docugate sync --ask`. The commands below are the same thing for scripts, agents and CI.
+
 ```sh
 npx docugate sync --dry-run   # free and instant: which pages are probably out of date
 npx docugate sync             # write the edits into your docs folder
 npx docugate sync --pr        # push them and open a pull request instead
 ```
 
-`sync` needs an AI key of your own, in `ANTHROPIC_API_KEY` or `OPENAI_API_KEY` (set `DOCUGATE_AI_BASE_URL` to use another OpenAI-compatible service). It talks to the provider directly: nothing goes through DocuGate's servers, and it works without a DocuGate account.
+`sync` needs an AI key of your own, in `ANTHROPIC_API_KEY` or `OPENAI_API_KEY` (set `DOCUGATE_AI_BASE_URL` to use another OpenAI-compatible service), or the one you pasted in the menu, kept in `~/.docugate/ai.json`. It talks to the provider directly: nothing goes through DocuGate's servers, and it works without a DocuGate account.
 
 **What it does, step by step**
 
@@ -351,7 +353,7 @@ Pin the version in CI, as above. Without a pin, the rules being enforced can cha
 | --- | --- | --- |
 | `docugate` | | In a terminal: the menu. Elsewhere: the help. |
 | `docugate status` | `--json` | Where things stand: account, docs, sync and tour, and what to do next. |
-| `docugate sync` | `--dry-run`, `--since <when>`, `--pr`, `--yes`, `--max-files <n>`, `--model <name>`, `--quiet` | Update the docs from what changed in the code. |
+| `docugate sync` | `--ask`, `--dry-run`, `--since <when>`, `--pr`, `--yes`, `--max-files <n>`, `--model <name>`, `--quiet` | Update the docs from what changed in the code. |
 | `docugate sync init` | `--freshness push\|daily\|weekly\|off`, `--force` | Add the GitHub Action that runs sync on a schedule or on every push. |
 | `docugate sync hook install` | | Tell you after each commit which pages the code left behind. |
 | `docugate sync hook remove` | | Remove that hook. |

package/dist/commands.js

@@ -14,9 +14,10 @@ export const COMMANDS = [
             { name: 'max-files', value: 'n', description: 'Most pages one run may change (default: 10)' },
             { name: 'model', value: 'name', description: 'Model to use (default: sync.model in docugate.json)' },
             { name: 'quiet', description: 'Print one line only when pages are out of date (for the git hook)' },
+            { name: 'ask', description: 'Ask which changes, show the pages first, then ask where the edits go (what the menu runs)' },
             YES,
         ],
-        examples: ['docugate sync --dry-run', 'docugate sync --since 7d', 'docugate sync --pr --yes'],
+        examples: ['docugate sync --dry-run', 'docugate sync --since 7d', 'docugate sync --pr --yes', 'docugate sync --ask'],
         account: 'none',
     },
     {

package/dist/menu.js

@@ -20,6 +20,24 @@ export function buildChoices(s, now = new Date()) {
             keywords: 'login sign in account github',
         });
     }
+    if (signedIn && p.git) {
+        choices.push({
+            value: ['connect'],
+            label: p.connected ? 'Connect again, or to another project' : 'Connect this folder to a project',
+            status: p.connected ? 'connected' : 'not connected',
+            description: 'Links this codebase to a project on DocuGate: its docs, and a backend or frontend beside it. The dashboard then shows its packages, security and updates.',
+            keywords: 'connect link project codebase frontend backend',
+        });
+    }
+    if (p.connected) {
+        choices.push({
+            value: ['audit'],
+            label: 'Check packages for vulnerabilities',
+            status: '',
+            description: 'Reads your lockfiles and checks every package against the published advisories. The results show in the dashboard under Security.',
+            keywords: 'audit security packages vulnerabilities osv',
+        });
+    }
     choices.push({
         value: ['developers'],
         label: 'Set up a developer space',
@@ -33,10 +51,10 @@ export function buildChoices(s, now = new Date()) {
         description: 'A short guided setup: where the docs live, the kind of repository, and linking a DocuGate space. It never overwrites your files.',
         keywords: 'init setup configure',
     }, {
-        value: ['sync'],
-        label: 'Update the docs from the code',
+        value: ['sync', '--ask'],
+        label: 'Update the docs with recent changes',
         status: y.commits === null ? '' : y.commits === 0 ? 'up to date' : `${plural(y.commits, 'commit')} behind`,
-        description: 'Reads what changed in the code, asks your AI model for the docs edits, and writes them. Add --pr from the command line to open a pull request instead.',
+        description: 'Pick which changes (since the last update, today, this week), see the pages they touch, then write the edits into the files or a pull request. Uses your own AI key.',
         keywords: 'sync update docs changes ai',
         disabled: needsDocs,
     }, {
@@ -48,7 +66,7 @@ export function buildChoices(s, now = new Date()) {
         disabled: needsDocs,
     }, {
         value: ['sync', 'init'],
-        label: 'Keep the docs current automatically',
+        label: 'Update the docs automatically on GitHub',
         status: y.workflow ? `on · ${p.freshness}` : 'not set up',
         description: `Adds a GitHub Action that runs sync ${p.freshness === 'push' ? 'on every push' : p.freshness === 'daily' ? 'every day' : 'every week'} and opens a pull request with the edits. You review and merge.`,
         keywords: 'sync init github action workflow schedule freshness',
@@ -156,16 +174,17 @@ export function buildMenu(s, section) {
     if (section === 'more') {
         const hook = all.find((c) => c.value[0] === 'sync' && c.value[1] === 'hook');
         return [
-            ...pick('sync --dry-run', 'sync init', ...(hook ? [hook.value.join(' ')] : []), 'status', 'openapi', 'help'),
+            ...pick('developers', ...(s.project.setUp ? ['init'] : []), ...(s.project.connected ? ['connect'] : []), 'sync --dry-run', 'sync init', ...(hook ? [hook.value.join(' ')] : [])),
+            { value: [...GO.tours], label: 'Tours' },
+            ...pick('status', 'openapi', 'help', 'logout'),
             { value: [...GO.back], label: 'Back' },
         ];
     }
+    // The few things people come for. Everything else is one step away, under More.
     const signedIn = s.account.state === 'signed-in';
     return [
-        ...pick('developers', 'init', 'sync', 'check'),
-        { value: [...GO.tours], label: 'Tours' },
+        ...pick(...(signedIn ? [] : ['login']), ...(s.project.connected ? [] : ['connect']), ...(s.project.setUp ? [] : ['init']), 'sync --ask', 'audit', 'check'),
         { value: [...GO.more], label: 'More' },
-        ...pick(signedIn ? 'logout' : 'login'),
         { value: [...GO.quit], label: 'Quit' },
     ];
 }

package/dist/project.d.ts

@@ -1,3 +1,4 @@
+import type { Choice } from './select.js';
 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"];
@@ -110,6 +111,13 @@ export declare function sectionFor(type: ProjectType, sources: {
 }[]): string;
 /** The project someone named: by slug, `owner/slug` or name, in any case. */
 export declare function pickProject(choices: ProjectChoice[], wanted: string): ProjectChoice | undefined;
+/**
+ * One choice from a list: the arrow-key picker in a terminal that can draw it,
+ * else a typed answer. Null when the person pressed escape.
+ */
+export declare function pickOne<T extends string>(title: string, choices: Choice<T>[], fallback: T, ask: (q: string) => Promise<string>): Promise<T | null>;
+/** A typed answer. Each question has its own reader, so the picker owns the keyboard in between. */
+export declare function askLine(question: string): Promise<string>;
 /**
  * `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

package/dist/project.js

@@ -10,6 +10,7 @@ import { guessRole } from './init.js';
 import { scanLockfiles } from './lockfiles.js';
 import { defaultGit } from './sync/changes.js';
 import { repoFromRemote } from './sync/pr.js';
+import { canPick, select } from './select.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
@@ -60,9 +61,12 @@ export function detectType(root) {
     const role = guessRole(root);
     if (workspaces || role === 'both')
         return 'monorepo';
+    // Checked before the hosting files: a frontend on Vercel or Netlify has one too.
+    if (role === 'frontend')
+        return 'frontend';
     if (['serverless.yml', 'serverless.ts', 'wrangler.toml', 'wrangler.jsonc', 'netlify.toml', 'vercel.json', 'template.yaml'].some(has))
         return 'serverless';
-    return role === 'frontend' ? 'frontend' : 'backend';
+    return 'backend';
 }
 /** Where the backend lives in a monorepo, which is where the key-check package installs. */
 export function detectBackendDir(root) {
@@ -206,9 +210,39 @@ 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;
+/** What each kind of codebase and each cadence means, for the picker. */
+const TYPE_HINT = {
+    frontend: 'What people see and click: a web or mobile app',
+    backend: 'An API or server the frontend calls',
+    serverless: 'Functions on Lambda, Workers or similar, with no server of their own',
+    monorepo: 'A frontend and a backend in this one folder',
+};
+const FREQUENCY_HINT = {
+    push: 'On every push to the default branch',
+    daily: 'Once a day',
+    weekly: 'Once a week',
+    off: 'Only when you run docugate sync',
+};
+/**
+ * One choice from a list: the arrow-key picker in a terminal that can draw it,
+ * else a typed answer. Null when the person pressed escape.
+ */
+export async function pickOne(title, choices, fallback, ask) {
+    if (canPick())
+        return select({ title, choices, rows: Math.min(choices.length, 10), legend: false });
+    const values = choices.map((c) => c.value);
+    const answer = (await ask(`  ${title} ${dim(`(${values.join(', ')})`)} [${fallback}] `)).trim().toLowerCase();
+    return values.includes(answer) ? answer : fallback;
+}
+/** A typed answer. Each question has its own reader, so the picker owns the keyboard in between. */
+export async function askLine(question) {
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    try {
+        return await rl.question(question);
+    }
+    finally {
+        rl.close();
+    }
 }
 const codeOf = (error) => error.code;
 /**
@@ -228,20 +262,17 @@ export async function connectCommand(root, args) {
     }
     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 ask = async (q) => (interactive ? askLine(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())) {
+            if (!interactive || !/^(|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();
@@ -261,15 +292,28 @@ export async function connectCommand(root, args) {
                 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') {
+        else if (interactive) {
+            // The codebases already in a project say what it is better than its name does.
+            const options = [
+                ...choices.map((p) => {
+                    const here = p.codebases.some((c) => c.repo.toLowerCase() === repo.toLowerCase() && c.path === path);
+                    const parts = p.codebases.map((c) => `${c.type} ${c.repo.split('/').at(-1)}${c.path ? `/${c.path}` : ''}`);
+                    return {
+                        value: p.id,
+                        label: p.name,
+                        status: [p.org, here ? 'already has this codebase' : ''].filter(Boolean).join(' · '),
+                        description: parts.length ? `Fed by ${parts.join(', ')}` : 'No codebase yet',
+                        keywords: `${p.owner}/${p.slug} ${parts.join(' ')}`,
+                        recommended: here,
+                    };
+                }),
+                { value: 'new', label: 'A new project', description: hasDocs ? `Its docs come from ${docsDir}/ in this codebase` : `Needs a docs folder here first (${config.docsDir}/). Run docugate init`, disabled: hasDocs ? undefined : 'no docs folder here yet' },
+                { value: 'none', label: 'Not yet', description: 'Connect it now and choose its project later, in the dashboard' },
+            ];
+            const answer = await pickOne('Which project is this codebase part of?', options, 'none', ask);
+            if (answer === null)
+                return 1;
+            if (answer === 'new') {
                 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;
@@ -281,19 +325,30 @@ export async function connectCommand(root, args) {
                 console.log(`  ${green('✓')} Created ${space.name}, published from ${docsDir}/.`);
             }
             else {
-                project = choices[Number(answer) - 1];
+                project = choices.find((p) => p.id === answer);
             }
         }
         else if (choices.length === 1) {
             project = choices[0];
         }
-        const type = args.type ?? (await choose('What is this codebase?', PROJECT_TYPES, detectType(root), ask));
+        const guessed = detectType(root);
+        const type = args.type ??
+            (interactive
+                ? await pickOne('What is this codebase?', PROJECT_TYPES.map((t) => ({ value: t, label: t, description: TYPE_HINT[t], recommended: t === guessed, status: t === guessed ? 'detected' : undefined })), guessed, ask)
+                : guessed);
+        if (type === null)
+            return 1;
         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 frequency = args.frequency ??
+            (interactive
+                ? await pickOne('How often should its docs be checked?', FREQUENCIES.map((f) => ({ value: f, label: f, description: FREQUENCY_HINT[f], recommended: f === 'weekly' })), 'weekly', ask)
+                : 'weekly');
+        if (frequency === null)
+            return 1;
         const res = await apiFetch('/api/projects', {
             method: 'POST',
             body: JSON.stringify({ repo, path, type, backendDir, frequency, spaceId: project?.id ?? null, audit: !args.noAudit }),
@@ -320,7 +375,7 @@ export async function connectCommand(root, args) {
                     // 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;
+                        section = interactive ? (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;
@@ -346,16 +401,24 @@ export async function connectCommand(root, args) {
             console.log(`  ${green('Connected')} ${where}. Choose its project in the dashboard, under Projects, or run docugate connect again.`);
         }
         console.log();
+        // The first check now, so the dashboard's Security column is filled from the start.
+        // After this, each docugate sync checks again, and docugate audit does on demand.
+        if (!args.noAudit) {
+            const answer = await runAudit(root, token);
+            console.log(`  ${bold('Dependency check')}  ${dim(`${plural(answer.files.length, 'lockfile')} read`)}`);
+            printFindings(answer);
+            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(`  ${dim(`Only if you use DocuGate API keys: install the package ${inside} with`)} 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.')}`);
+        // Nothing else to set up: updates run from this computer, and report to the dashboard on their own.
+        console.log(`  ${green('Done.')} Whenever you want this codebase's changes in the docs, run ${bold('docugate')} and pick ${bold('Update the docs')}.`);
+        console.log(`  ${dim('To have GitHub do it on every push instead: docugate, then More, then Update the docs automatically on GitHub.')}`);
         console.log();
         return 0;
     }
@@ -363,7 +426,4 @@ export async function connectCommand(root, args) {
         console.error(`${red('error')} ${error.message}`);
         return 1;
     }
-    finally {
-        rl?.close();
-    }
 }

package/dist/status.d.ts

@@ -10,6 +10,8 @@ export type Status = {
     project: {
         git: boolean;
         setUp: boolean;
+        /** Linked to a DocuGate project with `docugate connect`, so the dashboard sees it. */
+        connected: boolean;
         docsDir: string;
         pages: number;
         role?: string;

package/dist/status.js

@@ -2,6 +2,8 @@ import { loadConfig } from './config.js';
 import { accountState } from './session.js';
 import { collectChanges, defaultGit } from './sync/changes.js';
 import { hookInstalled } from './sync/hook.js';
+import { withSavedKey } from './sync/ai.js';
+import { projectToken } from './project.js';
 import { loadPages, scoreImpact } from './sync/impact.js';
 import { readSyncState } from './sync/state.js';
 import { workflowInstalled } from './sync/workflow.js';
@@ -66,6 +68,7 @@ export async function gatherStatus(root, deps = {}) {
         project: {
             git: inGit,
             setUp: loaded.found,
+            connected: Boolean(projectToken(root, env)),
             docsDir,
             pages: pages.length,
             role: loaded.config.role,
@@ -75,7 +78,10 @@ export async function gatherStatus(root, deps = {}) {
         sync: {
             workflow: workflowInstalled(root),
             hook: inGit && hookInstalled(root, git),
-            key: env.ANTHROPIC_API_KEY ? 'anthropic' : env.OPENAI_API_KEY ? 'openai' : null,
+            key: (() => {
+                const withKey = withSavedKey(env);
+                return withKey.ANTHROPIC_API_KEY ? 'anthropic' : withKey.OPENAI_API_KEY ? 'openai' : null;
+            })(),
             lastRunAt: state.lastRunAt,
             commits,
             affected,
@@ -90,14 +96,15 @@ export function nextStep(s) {
     if (s.account.state === 'signed-out') {
         return { command: 'login', why: 'Connect your DocuGate account so your docs can be published' };
     }
+    // Connected first: it is what makes the dashboard see this codebase, its packages and its runs.
+    if (s.account.state === 'signed-in' && s.project.git && !s.project.connected) {
+        return { command: 'connect', why: 'Link this folder to a project, so the dashboard sees it' };
+    }
     if (!s.project.setUp)
         return { command: 'init', why: 'Set this repository up for DocuGate' };
-    if (s.project.git && s.project.freshness !== 'off' && !s.sync.workflow) {
-        return { command: 'sync init', why: `Keep the docs current automatically (${s.project.freshness})` };
-    }
     if (s.project.git && s.sync.commits && s.sync.commits > 0) {
         return {
-            command: 'sync',
+            command: 'sync --ask',
             why: s.sync.affected
                 ? `${plural(s.sync.affected, 'page')} may be out of date after ${plural(s.sync.commits, 'commit')}`
                 : `${plural(s.sync.commits, 'commit')} since the last sync`,
@@ -148,7 +155,7 @@ export function renderStatus(s, now = new Date()) {
             p.freshness === 'off' ? 'automatic sync off' : `checks ${p.freshness}`,
             y.workflow ? 'workflow installed' : 'no workflow',
             y.hook ? 'hook on' : null,
-            y.key ? `${y.key === 'anthropic' ? 'Anthropic' : 'OpenAI'} key found` : 'no AI key in this shell',
+            y.key ? `${y.key === 'anthropic' ? 'Anthropic' : 'OpenAI'} key found` : 'no AI key yet',
         ].filter(Boolean);
         lines.push(row('Sync', y.workflow ? ok : off, `${bits.join(dim(' · '))}`));
         const behind = y.commits === null

package/dist/sync/ai.d.ts

@@ -26,6 +26,16 @@ export type AiRequest = {
 export type AiFn = (request: AiRequest) => Promise<string>;
 /** Which provider and key to use: the configured one, else whichever key is set. */
 export declare function resolveProvider(env: NodeJS.ProcessEnv, sync?: SyncConfig, modelOverride?: string): Provider | null;
+export type SavedKey = {
+    provider: 'anthropic' | 'openai';
+    key: string;
+};
+export declare function readSavedKey(): SavedKey | null;
+export declare function saveKey(saved: SavedKey): void;
+/** Which provider a pasted key belongs to, from its shape. */
+export declare function providerOfKey(key: string): SavedKey['provider'];
+/** The environment, with the saved key filled in when it has none of its own. */
+export declare function withSavedKey(env: NodeJS.ProcessEnv, saved?: SavedKey | null): NodeJS.ProcessEnv;
 export declare const KEY_HELP: string;
 /** The call to a real provider. */
 export declare function providerAiFn(provider: Provider): AiFn;

package/dist/sync/ai.js

@@ -1,4 +1,7 @@
 import { randomBytes } from 'node:crypto';
+import { chmodSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
 import { SyncError } from './changes.js';
 const DEFAULT_MODELS = { anthropic: 'claude-sonnet-5-5', openai: 'gpt-4o' };
 /** Which provider and key to use: the configured one, else whichever key is set. */
@@ -20,8 +23,44 @@ export function resolveProvider(env, sync = {}, modelOverride) {
             : (env.DOCUGATE_AI_BASE_URL ?? env.OPENAI_BASE_URL ?? 'https://api.openai.com/v1'),
     };
 }
+/*
+ * A key pasted once in the menu, kept on this computer next to the sign-in, so
+ * nobody has to export it in every terminal. The environment still wins: CI
+ * and a developer's own shell setup are never overridden.
+ */
+const KEY_FILE = () => join(process.env.DOCUGATE_HOME ?? join(homedir(), '.docugate'), 'ai.json');
+export function readSavedKey() {
+    try {
+        const saved = JSON.parse(readFileSync(KEY_FILE(), 'utf8'));
+        return (saved.provider === 'anthropic' || saved.provider === 'openai') && typeof saved.key === 'string' && saved.key ? saved : null;
+    }
+    catch {
+        return null;
+    }
+}
+export function saveKey(saved) {
+    const file = KEY_FILE();
+    mkdirSync(dirname(file), { recursive: true });
+    writeFileSync(file, JSON.stringify(saved), { mode: 0o600 });
+    try {
+        chmodSync(file, 0o600);
+    }
+    catch {
+        // Windows keeps its own permissions.
+    }
+}
+/** Which provider a pasted key belongs to, from its shape. */
+export function providerOfKey(key) {
+    return key.trim().startsWith('sk-ant-') ? 'anthropic' : 'openai';
+}
+/** The environment, with the saved key filled in when it has none of its own. */
+export function withSavedKey(env, saved = readSavedKey()) {
+    if (env.ANTHROPIC_API_KEY || env.OPENAI_API_KEY || !saved)
+        return env;
+    return { ...env, [saved.provider === 'anthropic' ? 'ANTHROPIC_API_KEY' : 'OPENAI_API_KEY']: saved.key };
+}
 export const KEY_HELP = 'Set ANTHROPIC_API_KEY (or OPENAI_API_KEY, optionally with DOCUGATE_AI_BASE_URL for another OpenAI-compatible service) ' +
-    'in your environment, or as a secret in GitHub Actions.';
+    'in your environment, or as a secret in GitHub Actions. Or run `docugate`, pick Update the docs, and paste a key once.';
 /** The call to a real provider. */
 export function providerAiFn(provider) {
     return async ({ system, user, maxTokens }) => {

package/dist/sync/ask.d.ts

@@ -0,0 +1,26 @@
+import type { Choice } from '../select.js';
+import type { GitFn } from './changes.js';
+import type { SavedKey } from './ai.js';
+export type Since = 'last' | '1d' | '7d' | '30d' | 'commit';
+export type Destination = 'files' | 'pr' | 'stop';
+export type AskDeps = {
+    /** One arrow-key question. Tests answer it themselves. */
+    pick: <T extends string>(title: string, choices: Choice<T>[], fallback: T) => Promise<T | null>;
+    /** A typed answer, for the AI key. */
+    line: (question: string) => Promise<string>;
+    git?: GitFn;
+    now?: Date;
+    save?: (key: SavedKey) => void;
+};
+/** Which changes to read. Null when the person backed out. */
+export declare function askSince(root: string, lastRunAt: string | undefined, deps: AskDeps): Promise<string | null>;
+/** The latest commits, newest first, for picking a starting point. */
+export declare function recentCommits(root: string, git: GitFn, count?: number): {
+    sha: string;
+    subject: string;
+    when: string;
+}[];
+/** Where the edits go, after the preview. */
+export declare function askDestination(pages: number, canOpenPr: boolean, deps: AskDeps): Promise<Destination | null>;
+/** Asks for an AI key once and keeps it on this computer. Null when none was given. */
+export declare function askForKey(deps: AskDeps): Promise<SavedKey | null>;

package/dist/sync/ask.js

@@ -0,0 +1,55 @@
+import { ago } from '../status.js';
+import { dim } from '../ui.js';
+import { defaultGit } from './changes.js';
+import { providerOfKey, saveKey } from './ai.js';
+/** Which changes to read. Null when the person backed out. */
+export async function askSince(root, lastRunAt, deps) {
+    const since = await deps.pick('Which changes should the docs catch up on?', [
+        { value: 'last', label: 'Since the last update', status: lastRunAt ? ago(lastRunAt, deps.now) : 'none yet', recommended: true },
+        { value: '1d', label: 'Today' },
+        { value: '7d', label: 'This week' },
+        { value: '30d', label: 'This month' },
+        { value: 'commit', label: 'Since a commit I pick' },
+    ], 'last');
+    if (since !== 'commit')
+        return since;
+    const commits = recentCommits(root, deps.git ?? defaultGit);
+    if (!commits.length)
+        return 'last';
+    return deps.pick('Since which commit? Everything after it is read.', commits.map((c, i) => ({ value: c.sha, label: c.subject, status: `${c.sha} · ${c.when}`, recommended: i === 0 })), commits[0].sha);
+}
+/** The latest commits, newest first, for picking a starting point. */
+export function recentCommits(root, git, count = 15) {
+    try {
+        return git(['log', '--no-merges', `-${count}`, '--format=%h%x1f%s%x1f%ar'], root)
+            .trim()
+            .split('\n')
+            .filter(Boolean)
+            .map((line) => {
+            const [sha, subject, when] = line.split('\x1f');
+            return { sha, subject: subject.length > 60 ? `${subject.slice(0, 57)}...` : subject, when };
+        });
+    }
+    catch {
+        return [];
+    }
+}
+/** Where the edits go, after the preview. */
+export async function askDestination(pages, canOpenPr, deps) {
+    return deps.pick(pages ? `Write the edits for ${pages === 1 ? 'this page' : 'these pages'}?` : 'No page names these changes. Ask the AI anyway?', [
+        { value: 'files', label: 'Yes, into the files here', description: 'You read them, then commit them like any change.', recommended: true },
+        ...(canOpenPr ? [{ value: 'pr', label: 'Yes, as a pull request', description: 'Pushed to the docugate/sync branch for someone to review.' }] : []),
+        { value: 'stop', label: 'Not now' },
+    ], 'files');
+}
+/** Asks for an AI key once and keeps it on this computer. Null when none was given. */
+export async function askForKey(deps) {
+    console.log(`\n  ${dim('Writing the edits uses your own AI model. The key stays on this computer and never goes through DocuGate.')}`);
+    const key = (await deps.line('  Paste an Anthropic or OpenAI key (Enter to skip): ')).trim();
+    if (!key)
+        return null;
+    const saved = { provider: providerOfKey(key), key };
+    (deps.save ?? saveKey)(saved);
+    console.log(`  ${dim(`Saved. Later runs use it without asking.`)}`);
+    return saved;
+}

package/dist/sync/command.js

@@ -10,8 +10,11 @@ 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 { askLine, pickOne, printFindings, projectToken, readSettings, reportRun, runAudit } from '../project.js';
 import { writeWorkflow, WORKFLOW_FILE } from './workflow.js';
+import { KEY_HELP, resolveProvider, withSavedKey } from './ai.js';
+import { askDestination, askForKey, askSince } from './ask.js';
+import { readSyncState } from './state.js';
 const out = (line = '') => console.log(line);
 /** `docugate sync ...`. Returns the exit code. */
 export async function syncCommand(root, args, deps = {}) {
@@ -24,6 +27,9 @@ export async function syncCommand(root, args, deps = {}) {
         if (args.sub)
             throw new SyncError(`Unknown sync command "${args.sub}". Try: sync, sync init, sync hook install, sync hook remove.`);
         const interactive = Boolean(process.stdin.isTTY && process.stdout.isTTY) && !process.env.CI && !args.bools.has('no-input');
+        deps = { ...deps, env: withSavedKey(deps.env ?? process.env) };
+        if (args.bools.has('ask') && interactive)
+            return askedSync(root, args, deps);
         const options = {
             since: args.since,
             dryRun: args.bools.has('dry-run'),
@@ -78,6 +84,44 @@ export async function syncCommand(root, args, deps = {}) {
         throw error;
     }
 }
+/**
+ * The menu's "Update the docs": which changes, a free preview of the pages they
+ * touch, then where the edits go. The answers become an ordinary sync.
+ */
+async function askedSync(root, args, deps) {
+    const askDeps = { pick: (title, choices, fallback) => pickOne(title, choices, fallback, askLine), line: askLine };
+    const since = await askSince(root, readSyncState(root).lastRunAt, askDeps);
+    if (!since)
+        return 0;
+    const preview = await runSync(root, { since, dryRun: true }, deps);
+    report(preview, false, false);
+    if (preview.skipped)
+        return 0;
+    let env = deps.env ?? process.env;
+    if (!resolveProvider(env, loadConfig(root).config.sync)) {
+        const saved = await askForKey(askDeps);
+        if (!saved) {
+            out(`  ${dim(KEY_HELP)}`);
+            return 0;
+        }
+        env = withSavedKey(env, saved);
+    }
+    let remote = '';
+    try {
+        remote = repoFromRemote(defaultGit(['remote', 'get-url', 'origin'], root)) ?? '';
+    }
+    catch {
+        // No remote: the edits can only go into the files.
+    }
+    const destination = await askDestination(preview.impact?.pages.length ?? 0, Boolean(remote), askDeps);
+    if (!destination || destination === 'stop')
+        return 0;
+    const bools = new Set([...args.bools].filter((b) => b !== 'ask'));
+    bools.add('yes');
+    if (destination === 'pr')
+        bools.add('pr');
+    return syncCommand(root, { ...args, since, bools }, { ...deps, env });
+}
 function headCommit(root) {
     try {
         return defaultGit(['rev-parse', '--short', 'HEAD'], root).trim();
@@ -100,7 +144,7 @@ async function ask(question) {
         rl.close();
     }
 }
-function report(r, quiet) {
+function report(r, quiet, next = true) {
     const affected = r.impact?.pages ?? [];
     if (quiet) {
         if (affected.length) {
@@ -138,7 +182,8 @@ function report(r, quiet) {
         }
         staleTour(r);
         out();
-        out(`  ${dim('Next:')} docugate sync`);
+        if (next)
+            out(`  ${dim('Next:')} docugate sync`);
         out();
         return 0;
     }
@@ -228,12 +273,17 @@ function syncInit(root, args) {
         /* no remote yet */
     }
     const key = loaded.config.sync?.provider === 'openai' ? 'OPENAI_API_KEY' : 'ANTHROPIC_API_KEY';
+    const managed = Boolean(projectToken(root));
     out();
-    out(`  ${bold('Two things to do on GitHub, once:')}`);
+    out(`  ${bold(`${managed ? 'Three' : 'Two'} things to do on GitHub, once:`)}`);
     out(`    1. Add your AI key as a repository secret named ${gold(key)}`);
     out(`       ${dim(repo ? `https://github.com/${repo}/settings/secrets/actions` : 'Settings > Secrets and variables > Actions')}`);
     out(`    2. Allow Actions to open pull requests: Settings > Actions > General > Workflow permissions`);
     out(`       ${dim('and tick "Allow GitHub Actions to create and approve pull requests"')}`);
+    if (managed) {
+        out(`    3. Add a secret named ${gold('DOCUGATE_PROJECT_TOKEN')}, so the dashboard sees each run`);
+        out(`       ${dim("Make one on the codebase's page in the dashboard: Settings, Access, Replace the token")}`);
+    }
     out();
     out(`  Then commit the workflow. ${dim('Next:')} docugate sync hook install ${dim('(optional: a heads-up after each commit)')}`);
     out();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "docugate",
-  "version": "0.4.2",
+  "version": "0.4.4",
   "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": {