papilot 0.1.1 → 0.3.0

package/README.md

@@ -53,17 +53,17 @@ Each edit comes back as a typeset diff. Accept, reject or comment on it, and und
 <td width="50%" valign="top">
 <img src="docs/assets/feature-contents.png" alt="The PDF viewer with its contents menu open">
 <h3>📖 Read it like a real PDF</h3>
-Jump around with the contents menu, search every page and zoom in sharply. Selecting text picks exactly the printed words.
+Jump to any section from the contents, search every page and zoom in sharply. Selecting text picks exactly the printed words.
 </td>
 <td width="50%" valign="top">
 <img src="docs/assets/feature-git.png" alt="The Git panel with a diff and a commit message">
 <h3>🌿 Commit when you're happy</h3>
-Diff files, commit the ones you choose, then pull and push without leaving the page.
+Diff files and commit the ones you choose, with a commit message an agent writes. Pull and push, or merge a coauthor's changes and let an agent resolve the conflicts.
 </td>
 </tr>
 </table>
 
-Also: 🤖 **Codex, Claude or Antigravity**, each with your own login · 🌳 **every task in its own Git worktree**, up to two at once · 📱 **runs on your computer**, and you can open it from your phone.
+Also: ✨ **skills** such as Polish, Proofread and Check math, one `/` away, plus your own · 🤖 **Codex, Claude or Antigravity**, each with your own login · 🌳 **every task in its own Git worktree**, up to two at once · 🌗 **light and dark** · 📱 **runs on your computer**, and you can open it from your phone.
 
 ## 🚀 Quick start
 
@@ -87,6 +87,8 @@ Open **http://127.0.0.1:7274** and choose **PDF** in the sidebar. The demo adds
 
 Papilot never reads, stores or forwards your credentials. An agent that isn't installed or signed in shows as unavailable.
 
+Having trouble getting started? Run `papilot doctor` for environment checks and fixes, or `papilot doctor --repo /path/to/paper` to check a paper too. Add `--json` for a machine-readable report. Diagnostics do not install software, start the server or change your paper. See the [diagnostics guide](docs/guide.md#diagnostics) for what is checked.
+
 <details>
 <summary><b>⚙️ Options and remote access</b></summary>
 
@@ -120,7 +122,17 @@ Run `npm run typecheck`, `npm test` and `npm run test:ui` before sending a pull
 
 ## 📚 Documentation
 
-The **[guide](docs/guide.md)** covers every part of the workspace, the configuration variables, recovery after restarts, and development. The example paper in [`examples/papilot-paper`](examples/papilot-paper) explains the design in depth, with proofs.
+The **[guide](docs/guide.md)** covers every part of the workspace, the configuration variables, recovery after restarts, and development. The example paper in [`examples/papilot-paper`](examples/papilot-paper) explains the design in depth, with proofs. What changed in each release is in the [changelog](CHANGELOG.md).
+
+## 💬 Community
+
+- 💡 **Questions and ideas**: [Discussions](https://github.com/cu1ch3n/papilot/discussions)
+- 🐛 **Something broke**: [open an issue](https://github.com/cu1ch3n/papilot/issues/new/choose)
+- 🤝 **Want to help**: pick a [good first issue](https://github.com/cu1ch3n/papilot/labels/good%20first%20issue) and read [CONTRIBUTING.md](CONTRIBUTING.md)
+
+If Papilot saves you time on a paper, a ⭐ helps other researchers find it.
+
+<a href="https://github.com/cu1ch3n/papilot/graphs/contributors"><img src="https://contrib.rocks/image?repo=cu1ch3n/papilot" alt="Papilot contributors"></a>
 
 ## 📄 License
 

package/README.zh-CN.md

@@ -58,12 +58,12 @@
 <td width="50%" valign="top">
 <img src="docs/assets/feature-git.png" alt="带差异和提交信息的 Git 面板">
 <h3>🌿 满意了再提交</h3>
-查看差异，只提交你勾选的文件，pull 和 push 都不用离开页面。
+查看差异，只提交你勾选的文件，提交信息可以让 agent 来写。可以 pull、push，也可以合并合作者的改动，冲突交给 agent 解决。
 </td>
 </tr>
 </table>
 
-此外：🤖 **Codex、Claude 或 Antigravity**，各用你自己的登录 · 🌳 **每个任务都有独立的 Git 工作树**，最多两个同时运行 · 📱 **运行在你的电脑上**，也能用手机打开。
+此外：✨ **技能（skill）**，如润色、校对、检查数学，输入 `/` 即可选用，也能添加你自己的 · 🤖 **Codex、Claude 或 Antigravity**，各用你自己的登录 · 🌳 **每个任务都有独立的 Git 工作树**，最多两个同时运行 · 🌗 **浅色与深色** · 📱 **运行在你的电脑上**，也能用手机打开。
 
 ## 🚀 快速开始
 
@@ -87,6 +87,8 @@ papilot demo
 
 Papilot 从不读取、保存或转发你的凭据。没有安装或没有登录的智能体会显示为不可用。
 
+启动遇到问题？运行 `papilot doctor` 检查环境并查看修复建议，或用 `papilot doctor --repo /path/to/paper` 一并检查论文。加上 `--json` 可输出机器可读的报告。诊断不会安装软件、启动服务或修改论文。检查范围见[诊断指南](docs/guide.md#diagnostics)。
+
 <details>
 <summary><b>⚙️ 选项与远程访问</b></summary>
 
@@ -120,7 +122,17 @@ npm run build && npm start
 
 ## 📚 文档
 
-**[指南](docs/guide.md)**（英文）介绍工作台的每个部分、配置变量、重启后的恢复以及开发流程。[`examples/papilot-paper`](examples/papilot-paper) 中的示例论文深入讲解了设计，并附有证明。
+**[指南](docs/guide.md)**（英文）介绍工作台的每个部分、配置变量、重启后的恢复以及开发流程。[`examples/papilot-paper`](examples/papilot-paper) 中的示例论文深入讲解了设计，并附有证明。每个版本的变化见[更新日志](CHANGELOG.md)。
+
+## 💬 社区
+
+- 💡 **提问和想法**：[Discussions](https://github.com/cu1ch3n/papilot/discussions)
+- 🐛 **遇到问题**：[提交 issue](https://github.com/cu1ch3n/papilot/issues/new/choose)
+- 🤝 **想参与**：从 [good first issue](https://github.com/cu1ch3n/papilot/labels/good%20first%20issue) 开始，并阅读 [CONTRIBUTING.md](CONTRIBUTING.md)
+
+如果 Papilot 帮你省下了改论文的时间，点个 ⭐ 能让更多研究者发现它。
+
+<a href="https://github.com/cu1ch3n/papilot/graphs/contributors"><img src="https://contrib.rocks/image?repo=cu1ch3n/papilot" alt="Papilot 贡献者"></a>
 
 ## 📄 许可证
 

package/bin/doctor.mjs

@@ -0,0 +1,239 @@
+// Deliberately uses only Node built-ins: diagnostics must work before npm setup.
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { execFile } from 'node:child_process';
+import { createRequire } from 'node:module';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const pkg = JSON.parse(fs.readFileSync(path.join(root, 'package.json'), 'utf8'));
+const help = `Usage: papilot doctor [--repo <folder>] [--json] [--data <folder>] [--port <number>]
+
+  --repo <folder>  Also check a LaTeX Git repository and its root document
+  --json           Print one JSON report, suitable for scripts
+  --data <folder>  Check this data folder (default: PAPILOT_DATA or ~/.papilot)
+  --port <number>  Check this local server port (default: PAPILOT_PORT or 7274)
+  --help           Show this help
+
+Checks the current environment and, on macOS, installed service tool paths.
+Does not install software, start Papilot, compile papers or send model prompts.
+Exit codes: 0 = no blocking errors (warnings may remain), 1 = blocking errors,
+2 = invalid command-line options. Agent configuration is not a live API test.`;
+
+const expand = value => path.resolve(value.startsWith('~/') ? path.join(os.homedir(), value.slice(2)) : value);
+const supportedNode = version => { const [major, minor] = version.split('.').map(Number); return major > 22 || (major === 22 && minor >= 22); };
+const atLeast = (version, minimum) => {
+  const a = version.split('.').map(Number), b = minimum.split('.').map(Number);
+  return (a[0] - b[0] || a[1] - b[1] || a[2] - b[2]) >= 0;
+};
+function executable(command, env = process.env) {
+  const candidates = command.includes('/') || command.includes('\\') ? [path.resolve(command)]
+    : (env.PATH || '').split(path.delimiter).map(dir => path.resolve(dir || '.', command));
+  return candidates.find(file => {
+    try { fs.accessSync(file, fs.constants.X_OK); return fs.statSync(file).isFile(); } catch { return false; }
+  });
+}
+function command(file, args, options = {}) {
+  return new Promise(resolve => {
+    // Never return raw stderr: login commands can print credentials or account data.
+    const child = execFile(file, args, { cwd: os.homedir(), timeout: 5000, killSignal: 'SIGKILL', maxBuffer: 128 * 1024, ...options }, (error, stdout, stderr) => {
+      resolve({ ok: !error, stdout, stderr, reason: error?.killed ? 'timed out' : error ? `failed (${error.code || 'unknown error'})` : '' });
+    });
+    child.stdin?.end();
+  });
+}
+function writableDirectory(target) {
+  let existing = target;
+  while (!fs.existsSync(existing) && path.dirname(existing) !== existing) existing = path.dirname(existing);
+  try {
+    if (!fs.statSync(existing).isDirectory()) return false;
+    fs.accessSync(existing, fs.constants.W_OK | fs.constants.X_OK);
+    return true;
+  } catch { return false; }
+}
+function installedModule(name, directory = root) {
+  try { return createRequire(path.join(directory, 'package.json')).resolve(name); } catch { return null; }
+}
+
+export async function doctor(args) {
+  if (args.includes('--help') || args.includes('-h')) { console.log(help); return 0; }
+  const json = args.includes('--json');
+  let data = expand(process.env.PAPILOT_DATA || path.join(os.homedir(), '.papilot'));
+  let port = Number(process.env.PAPILOT_PORT || 7274), repo = null;
+  try {
+    for (let i = 0; i < args.length; i++) {
+      const arg = args[i];
+      if (arg === '--json') continue;
+      if (!['--data', '--port', '--repo'].includes(arg)) throw new Error(`Unknown option: ${arg}`);
+      const value = args[++i];
+      if (!value || value.startsWith('--')) throw new Error(`${arg} needs a value.`);
+      if (arg === '--data') data = expand(value);
+      if (arg === '--repo') repo = expand(value);
+      if (arg === '--port') port = Number(value);
+    }
+    if (!Number.isInteger(port) || port < 1 || port > 65535) throw new Error('--port or PAPILOT_PORT must be an integer from 1 to 65535.');
+  } catch (error) {
+    if (json) console.log(JSON.stringify({ name: 'Papilot', version: pkg.version, ok: false, checks: [], error: error.message }));
+    else console.error(`${error.message}\n\n${help}`);
+    return 2;
+  }
+  const checks = [];
+  // Redact known secret values even when they appear in a path or configuration error.
+  const secrets = Object.entries(process.env).filter(([key, value]) => /KEY|TOKEN|SECRET|PASSWORD/i.test(key) && value?.length >= 4).map(([, value]) => value);
+  const clean = value => secrets.reduce((text, secret) => text.split(secret).join('[redacted]'), String(value))
+    .replace(/\x1b\[[0-9;]*[A-Za-z]/g, '').replace(/[\x00-\x08\x0b-\x1f\x7f]/g, '');
+  const check = (id, ok, severity, detail, fix = null) => checks.push({ id, ok: Boolean(ok), severity, detail: clean(detail), fix: ok || !fix ? null : clean(fix) });
+  const engine = expand(process.env.PAPILOT_REVIEW_ENGINE || path.join(root, 'vendor/latex-review'));
+  const sourceCheckout = fs.existsSync(path.join(root, '.git'));
+  const repair = sourceCheckout ? 'Run npm ci in the Papilot checkout.' : 'Reinstall Papilot with npm install -g papilot.';
+
+  check('node', supportedNode(process.versions.node), 'error', `Node.js ${process.versions.node} (${process.execPath})`, 'Install Node.js 22.22 or newer, then run papilot doctor again.');
+  const missing = Object.keys(pkg.dependencies).filter(name => !installedModule(name));
+  check('dependencies', !missing.length, 'error', missing.length ? `Missing packages: ${missing.join(', ')}.` : 'Runtime packages are installed.', repair);
+  const frontend = fs.existsSync(path.join(root, 'dist/index.html'));
+  check('frontend', frontend, 'error', frontend ? 'Papilot frontend build is present.' : 'Papilot frontend build is missing: dist/index.html.', sourceCheckout ? 'Run npm run build.' : repair);
+  const missingEngine = ['src/client.ts', 'src/core/config.ts', 'dist/web/index.html'].filter(file => !fs.existsSync(path.join(engine, file)));
+  check('review-engine', !missingEngine.length, 'error', `Review engine: ${engine}${missingEngine.length ? `; missing ${missingEngine.join(', ')}` : ''}`, process.env.PAPILOT_REVIEW_ENGINE ? 'Check PAPILOT_REVIEW_ENGINE and build that review engine.' : sourceCheckout ? 'Run npm run setup:review.' : repair);
+  check('data', writableDirectory(data), 'error', `Data folder: ${data}${fs.existsSync(data) ? '' : ' (will be created on startup)'}`, 'Choose a writable directory with --data <folder>.');
+
+  async function tool(name, args, fix, id = name, env = process.env, severity = 'error') {
+    const file = executable(name, env);
+    if (!file) { check(id, false, severity, `${name} was not found on PATH.`, fix); return null; }
+    const result = await command(file, args, { env });
+    check(id, result.ok, severity, `${file}${result.ok ? '' : `: ${result.reason}`}`, fix);
+    return result.ok ? file : null;
+  }
+  const [git] = await Promise.all([
+    tool('git', ['--version'], 'Install Git and open a new terminal.'),
+    tool('latexmk', ['-v'], 'Install a full TeX distribution (MacTeX or TeX Live), and add its binaries to PATH.'),
+    tool('synctex', ['--version'], 'Install SyncTeX from your TeX distribution and add its binaries to PATH.'),
+  ]);
+  const texEngines = await Promise.all(['pdflatex', 'xelatex', 'lualatex'].map(async name => {
+    const file = executable(name);
+    return file && (await command(file, ['--version'])).ok ? name : null;
+  }));
+  const availableEngines = texEngines.filter(Boolean);
+  check('tex-engines', availableEngines.length > 0, 'error', availableEngines.length ? `TeX engines: ${availableEngines.join(', ')}.` : 'No working pdflatex, xelatex or lualatex was found.', 'Install a full TeX distribution and add its binaries to PATH.');
+
+  async function codexCheck() {
+    const minimum = pkg.devDependencies['@openai/codex'];
+    const configured = process.env.PAPILOT_CODEX_BIN;
+    const candidates = configured ? [configured] : ['codex', path.join(data, 'agents/node_modules/.bin/codex')];
+    let found = false;
+    for (const candidate of candidates) {
+      const file = executable(candidate);
+      if (!file) continue;
+      found = true;
+      const result = await command(file, ['--version']);
+      const version = result.stdout.match(/\d+\.\d+\.\d+/)?.[0];
+      if (!result.ok || !version || !atLeast(version, minimum)) {
+        if (!configured) continue;
+        check('agent.codex', false, 'warn', `Configured Codex ${result.ok ? 'is older than the supported version or its version is unknown' : result.reason}.`, `Set PAPILOT_CODEX_BIN to Codex ${minimum} or newer.`);
+        return false;
+      }
+      const login = await command(file, ['login', 'status']);
+      const ready = login.ok && /^\s*logged in\b/im.test(login.stdout + '\n' + login.stderr);
+      check('agent.codex', ready, 'warn', `Codex ${version} (${file}): ${ready ? 'signed in' : login.reason || 'login could not be confirmed'}.`, 'Run papilot codex login, then rerun doctor.');
+      return ready;
+    }
+    check('agent.codex', false, 'warn', configured ? 'PAPILOT_CODEX_BIN does not point to an executable.' : found ? `No installed Codex meets version ${minimum}.` : 'Codex is not installed.', configured ? 'Correct PAPILOT_CODEX_BIN or unset it to use automatic installation.' : 'Run papilot codex login; it installs the supported Codex when needed.');
+    return false;
+  }
+  async function claudeCheck() {
+    const sdk = installedModule('@anthropic-ai/claude-agent-sdk') || installedModule('@anthropic-ai/claude-agent-sdk', path.join(data, 'agents'));
+    const configured = ['ANTHROPIC_API_KEY', 'ANTHROPIC_AUTH_TOKEN', 'CLAUDE_CODE_USE_BEDROCK', 'CLAUDE_CODE_USE_VERTEX', 'CLAUDE_CODE_USE_FOUNDRY'].some(key => Boolean(process.env[key]));
+    check('agent.claude', Boolean(sdk && configured), 'warn', !configured ? 'Claude API credentials are not configured in this environment; SDK-managed credentials were not checked.' : sdk ? 'Claude SDK installed; API credentials configured (not validated).' : 'Claude API credentials configured; the Agent SDK is not installed yet.', !configured ? 'Start Papilot with ANTHROPIC_API_KEY or a supported cloud provider configured. A Claude subscription alone cannot be used by this adapter.' : 'Start papilot once to install the Claude Agent SDK.');
+    return Boolean(sdk && configured);
+  }
+  async function agyCheck() {
+    const file = executable(process.env.PAPILOT_AGY_BIN || 'agy');
+    if (!file) { check('agent.antigravity', false, 'warn', 'Antigravity CLI is not installed or PAPILOT_AGY_BIN is invalid.', 'Install Antigravity and sign in to agy, or choose another agent.'); return false; }
+    const proxy = process.env.PAPILOT_AGY_PROXY;
+    const env = proxy ? { ...process.env, HTTPS_PROXY: proxy, HTTP_PROXY: proxy, https_proxy: proxy, http_proxy: proxy, NO_PROXY: '127.0.0.1,localhost' } : process.env;
+    const result = await command(file, ['models'], { env });
+    const ready = result.ok && result.stdout.split('\n').some(line => /^\S+\t\S/.test(line));
+    check('agent.antigravity', ready, 'warn', `${file}: ${ready ? 'model listing succeeded (no generation tested)' : result.reason || 'no models returned'}.`, 'Sign in to agy and try agy models. If your region requires a proxy, set PAPILOT_AGY_PROXY.');
+    return ready;
+  }
+  const agents = await Promise.all([codexCheck(), claudeCheck(), agyCheck()]);
+  check('agents', agents.some(Boolean), 'warn', agents.some(Boolean) ? 'At least one agent passed its configuration check; live editing was not tested.' : 'No agent passed its configuration check. PDF reading can still be used with a working TeX installation.', 'Configure one agent before starting editing tasks.');
+
+  if (repo) {
+    if (!fs.existsSync(repo) || !fs.statSync(repo).isDirectory()) check('project', false, 'error', `Paper folder does not exist: ${repo}`, 'Pass the Git repository root with --repo <folder>.');
+    else if (git) {
+      const top = await command(git, ['-C', repo, 'rev-parse', '--show-toplevel']);
+      let atRoot = false;
+      try { atRoot = top.ok && fs.realpathSync(top.stdout.trim()) === fs.realpathSync(repo); } catch { /* Missing repository. */ }
+      check('project.git', atRoot, 'error', atRoot ? `Git repository: ${repo}` : 'The paper folder is not a Git repository root.', 'Pass the repository root; initialize Git first if the paper is not yet versioned.');
+      if (atRoot) {
+        const head = await command(git, ['-C', repo, 'rev-parse', '--verify', 'HEAD']);
+        check('project.head', head.ok, 'error', head.ok ? 'The repository has an initial commit.' : 'The repository has no initial commit.', 'Create the first Git commit before adding this paper to Papilot.');
+        try {
+          const { register } = await import('tsx/esm/api');
+          const unregister = register();
+          let project;
+          try { project = (await import(pathToFileURL(path.join(engine, 'src/core/config.ts')).href)).loadProject(repo); }
+          finally { unregister(); }
+          check('project.main', true, 'error', `${project.main} (${project.engine}); configuration loaded without compiling.`);
+          await tool(project.engine, ['--version'], `Install ${project.engine} through your TeX distribution.`, 'project.engine');
+          check('project.worktrees', writableDirectory(project.worktrees), 'error', `Task worktrees: ${project.worktrees}`, 'Choose a writable worktrees directory outside the repository in .latex-review.json.');
+        } catch (error) {
+          check('project.main', false, 'error', `Could not load the paper configuration: ${error.message}`, 'Check .latex-review.json, its main/source_dir settings, and the review-engine/dependencies checks above.');
+        }
+      }
+    }
+  } else check('project', true, 'info', 'No paper selected. Use --repo <folder> to check its Git history, main document and TeX engine.');
+
+  const origin = process.env.PAPILOT_PUBLIC_ORIGIN || '', owner = process.env.PAPILOT_TAILSCALE_LOGIN || '';
+  let remoteValid = !origin && !owner;
+  if (origin && owner) {
+    try { const url = new URL(origin); remoteValid = ['http:', 'https:'].includes(url.protocol) && url.origin === origin && !url.username && !url.password; } catch { /* Invalid origin. */ }
+  }
+  check('remote', remoteValid, 'error', origin || owner ? 'Tailscale origin and owner configuration.' : 'Local access only; remote access is optional.', 'Set both PAPILOT_PUBLIC_ORIGIN (scheme and host, optional port, no path) and PAPILOT_TAILSCALE_LOGIN, or unset both for local access.');
+  try {
+    const response = await fetch(`http://127.0.0.1:${port}/api/health`, { signal: AbortSignal.timeout(1500), redirect: 'error' });
+    const health = await response.json();
+    const ok = response.ok && health?.ok === true && health?.name === 'Papilot';
+    check('server', ok, 'warn', ok ? `Papilot is responding on port ${port}.` : `Port ${port} is not serving a healthy Papilot instance.`, 'Check the running service or choose another --port.');
+  } catch (error) {
+    const offline = error.cause?.code === 'ECONNREFUSED';
+    check('server', offline, offline ? 'info' : 'warn', offline ? `Papilot is not running on port ${port}; this is fine before startup.` : `Could not verify Papilot on port ${port}.`, 'Check the running service or choose another --port.');
+  }
+
+  if (process.platform === 'darwin') {
+    const plist = path.join(os.homedir(), 'Library/LaunchAgents/local.papilot.plist');
+    if (!fs.existsSync(plist)) check('service', true, 'info', 'macOS background service is not installed (optional).');
+    else {
+      const result = await command('/usr/bin/plutil', ['-convert', 'json', '-o', '-', plist]);
+      try {
+        if (!result.ok) throw new Error('Unreadable service configuration.');
+        const settings = JSON.parse(result.stdout), env = settings.EnvironmentVariables || {};
+        const tools = ['git', 'latexmk', 'synctex', ...availableEngines];
+        const missing = tools.filter(name => !executable(name, env));
+        const different = tools.filter(name => executable(name, env) !== executable(name));
+        const node = settings.ProgramArguments?.[2];
+        const validNode = typeof node === 'string' && executable(node, env);
+        check('service.tools', !missing.length && !different.length && validNode, 'warn', !validNode ? 'The service Node executable is missing.' : missing.length ? `The saved service PATH is missing: ${missing.join(', ')}.` : different.length ? `Service and terminal resolve different tools: ${different.join(', ')}.` : 'The saved service paths match the terminal tools.', 'Reinstall with papilot service install from the intended environment; use PAPILOT_SERVICE_PATH for your TeX/Python directory.');
+        const serviceData = expand(env.PAPILOT_DATA || path.join(settings.WorkingDirectory || root, '.papilot'));
+        check('service.data', serviceData === data, 'warn', serviceData === data ? 'The service data folder matches this diagnostic target.' : `The service uses a different data folder: ${serviceData}`, 'Run doctor with the service data folder (--data), or reinstall the service with the intended PAPILOT_DATA.');
+      } catch { check('service', false, 'warn', 'The installed service configuration could not be read.', 'Run papilot service install to recreate the service configuration.'); }
+    }
+  }
+  // Keep reports stable even though independent probes finish in any order.
+  const order = ['node', 'dependencies', 'frontend', 'review-engine', 'data', 'git', 'latexmk', 'synctex', 'tex-engines', 'agent.codex', 'agent.claude', 'agent.antigravity', 'agents', 'project', 'project.git', 'project.head', 'project.main', 'project.engine', 'project.worktrees', 'remote', 'server', 'service', 'service.tools', 'service.data'];
+  checks.sort((a, b) => order.indexOf(a.id) - order.indexOf(b.id));
+  const report = { name: 'Papilot', version: pkg.version, ok: !checks.some(item => !item.ok && item.severity === 'error'), checks };
+  if (json) console.log(JSON.stringify(report, null, 2));
+  else {
+    console.log(`Papilot ${pkg.version} doctor\n`);
+    for (const item of checks) {
+      console.log(`${item.ok ? '✓' : item.severity === 'error' ? '✗' : '!'} ${item.id}: ${item.detail}`);
+      if (item.fix) console.log(`  Fix: ${item.fix}`);
+    }
+    const errors = checks.filter(item => !item.ok && item.severity === 'error').length;
+    const warnings = checks.filter(item => !item.ok && item.severity === 'warn').length;
+    console.log(`\n${errors} blocking error(s), ${warnings} warning(s).${report.ok ? ' Environment checks passed.' : ' Fix blocking errors and run doctor again.'}`);
+  }
+  return report.ok ? 0 : 1;
+}

package/bin/papilot.mjs

@@ -6,9 +6,10 @@ import os from 'node:os';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 
-const usage = `Usage: papilot [demo | codex <args> | service install | service stop] [--port <number>] [--data <folder>]
+const usage = `Usage: papilot [doctor | demo | codex <args> | service install | service stop] [--port <number>] [--data <folder>]
 
   papilot                  Start Papilot at http://127.0.0.1:7274
+  papilot doctor           Check the environment; use doctor --help for options
   papilot demo             Add the example paper, then start
   papilot codex login      Sign in to Codex with the Codex that Papilot uses
   papilot service install  Run Papilot in the background after login (macOS)
@@ -19,95 +20,103 @@ const usage = `Usage: papilot [demo | codex <args> | service install | service s
 
 const pkg = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
 const args = process.argv.slice(2);
-let demo = false, service = '', codexArgs = null;
-for (let i = 0; i < args.length; i++) {
-  const arg = args[i];
-  if (arg === 'demo') demo = true;
-  else if (arg === 'codex') { codexArgs = args.slice(i + 1); break; }
-  else if (arg === 'service' && ['install', 'stop'].includes(args[i + 1])) service = args[++i];
-  else if (arg === '--port') {
-    const port = Number(args[++i]);
-    if (!Number.isInteger(port) || port < 1 || port > 65535) { console.error('--port needs a number from 1 to 65535.'); process.exit(1); }
-    process.env.PAPILOT_PORT = String(port);
+async function main() {
+  const doctor = args[0] === 'doctor';
+  // Doctor parses its own options and must never reach the installation/startup path.
+  if (doctor && (args.includes('--help') || args.includes('-h'))) return (await import('./doctor.mjs')).doctor(args.slice(1));
+  let demo = false, service = '', codexArgs = null;
+  for (let i = 0; !doctor && i < args.length; i++) {
+    const arg = args[i];
+    if (arg === 'demo') demo = true;
+    else if (arg === 'codex') { codexArgs = args.slice(i + 1); break; }
+    else if (arg === 'service' && ['install', 'stop'].includes(args[i + 1])) service = args[++i];
+    else if (arg === '--port') {
+      const port = Number(args[++i]);
+      if (!Number.isInteger(port) || port < 1 || port > 65535) { console.error('--port needs a number from 1 to 65535.'); process.exit(1); }
+      process.env.PAPILOT_PORT = String(port);
+    }
+    else if (arg === '--data' && args[i + 1]) process.env.PAPILOT_DATA = path.resolve(args[++i]);
+    else if (arg === '--version' || arg === '-v') {
+      console.log(pkg.version);
+      process.exit(0);
+    } else {
+      if (arg !== '--help' && arg !== '-h') console.error(`Unknown argument: ${arg}\n`);
+      console.log(usage);
+      process.exit(arg === '--help' || arg === '-h' ? 0 : 1);
+    }
   }
-  else if (arg === '--data' && args[i + 1]) process.env.PAPILOT_DATA = path.resolve(args[++i]);
-  else if (arg === '--version' || arg === '-v') {
-    console.log(pkg.version);
-    process.exit(0);
-  } else {
-    if (arg !== '--help' && arg !== '-h') console.error(`Unknown argument: ${arg}\n`);
-    console.log(usage);
-    process.exit(arg === '--help' || arg === '-h' ? 0 : 1);
-  }
-}
 
-// Papilot needs Node 22.22+. When an older Node runs this command, use a newer
-// one from nvm or PATH, preferring LTS releases, without changing the default.
-const parse = version => version.replace(/^v/, '').split('.').map(Number);
-const supported = version => { const [major, minor] = parse(version); return major > 22 || (major === 22 && minor >= 22); };
-if (!supported(process.versions.node)) {
-  const versions = path.join(process.env.NVM_DIR || path.join(os.homedir(), '.nvm'), 'versions/node');
-  const nvm = existsSync(versions) ? readdirSync(versions).map(v => ({ file: path.join(versions, v, 'bin/node'), version: v })) : [];
-  const others = [...new Set([...(process.env.PATH || '').split(path.delimiter).map(dir => path.join(dir, 'node')), '/opt/homebrew/bin/node', '/usr/local/bin/node'])]
-    .filter(file => existsSync(file)).map(file => ({ file, version: (spawnSync(file, ['--version'], { encoding: 'utf8' }).stdout || '0').trim() }));
-  // nvm's versions come first, then any other Node; even majors are LTS releases,
-  // and among those the newest wins.
-  const rank = ({ version }) => { const [major, minor, patch] = parse(version); return (major % 2 === 0 ? 1e9 : 0) + major * 1e6 + minor * 1e3 + patch; };
-  const best = list => list.filter(c => existsSync(c.file) && supported(c.version)).sort((a, b) => rank(b) - rank(a))[0];
-  const node = best(nvm) || best(others);
-  if (!node) {
-    console.error(`Papilot needs Node.js 22.22 or newer; this is ${process.versions.node}. Install it with \`nvm install 22\` or from https://nodejs.org, then run papilot again.`);
-    process.exit(1);
+  // Papilot needs Node 22.22+. When an older Node runs this command, use a newer
+  // one from nvm or PATH, preferring LTS releases, without changing the default.
+  const parse = version => version.replace(/^v/, '').split('.').map(Number);
+  const supported = version => { const [major, minor] = parse(version); return major > 22 || (major === 22 && minor >= 22); };
+  if (!supported(process.versions.node)) {
+    const versions = path.join(process.env.NVM_DIR || path.join(os.homedir(), '.nvm'), 'versions/node');
+    const nvm = existsSync(versions) ? readdirSync(versions).map(v => ({ file: path.join(versions, v, 'bin/node'), version: v })) : [];
+    const others = [...new Set([...(process.env.PATH || '').split(path.delimiter).map(dir => path.join(dir, 'node')), '/opt/homebrew/bin/node', '/usr/local/bin/node'])]
+      .filter(file => existsSync(file)).map(file => ({ file, version: (spawnSync(file, ['--version'], { encoding: 'utf8', timeout: 5000, killSignal: 'SIGKILL' }).stdout || '0').trim() }));
+    // nvm's versions come first, then any other Node; even majors are LTS releases,
+    // and among those the newest wins.
+    const rank = ({ version }) => { const [major, minor, patch] = parse(version); return (major % 2 === 0 ? 1e9 : 0) + major * 1e6 + minor * 1e3 + patch; };
+    const best = list => list.filter(c => existsSync(c.file) && supported(c.version)).sort((a, b) => rank(b) - rank(a))[0];
+    const node = best(nvm) || best(others);
+    if (!node) {
+      if (doctor) return (await import('./doctor.mjs')).doctor(args.slice(1));
+      console.error(`Papilot needs Node.js 22.22 or newer; this is ${process.versions.node}. Install it with \`nvm install 22\` or from https://nodejs.org, then run papilot again.`);
+      process.exit(1);
+    }
+    console.error(`Papilot needs Node.js 22.22+; using ${node.version.replace(/^v/, '')} from ${path.dirname(node.file)}.`);
+    const child = spawn(node.file, [fileURLToPath(import.meta.url), ...args], { stdio: 'inherit', env: { ...process.env, PATH: path.dirname(node.file) + path.delimiter + process.env.PATH } });
+    // Pass stop signals on, so stopping papilot also stops the server it started.
+    for (const signal of ['SIGINT', 'SIGTERM', 'SIGHUP']) process.on(signal, () => child.kill(signal));
+    await new Promise(() => child.on('exit', code => process.exit(code ?? 1)));
   }
-  console.error(`Papilot needs Node.js 22.22+; using ${node.version.replace(/^v/, '')} from ${path.dirname(node.file)}.`);
-  const child = spawn(node.file, [fileURLToPath(import.meta.url), ...args], { stdio: 'inherit', env: { ...process.env, PATH: path.dirname(node.file) + path.delimiter + process.env.PATH } });
-  // Pass stop signals on, so stopping papilot also stops the server it started.
-  for (const signal of ['SIGINT', 'SIGTERM', 'SIGHUP']) process.on(signal, () => child.kill(signal));
-  await new Promise(() => child.on('exit', code => process.exit(code ?? 1)));
-}
-const tex = !spawnSync('latexmk', ['-v'], { stdio: 'ignore' }).error;
+  if (doctor) return (await import('./doctor.mjs')).doctor(args.slice(1));
+  const tex = !spawnSync('latexmk', ['-v'], { stdio: 'ignore' }).error;
 
-// Node 22 marks node:sqlite as experimental; that notice is noise for users.
-const emitWarning = process.emitWarning;
-process.emitWarning = (warning, ...rest) => String(warning).includes('SQLite') ? undefined : emitWarning.call(process, warning, ...rest);
-process.env.PAPILOT_DATA ||= path.join(os.homedir(), '.papilot');
+  // Node 22 marks node:sqlite as experimental; that notice is noise for users.
+  const emitWarning = process.emitWarning;
+  process.emitWarning = (warning, ...rest) => String(warning).includes('SQLite') ? undefined : emitWarning.call(process, warning, ...rest);
+  process.env.PAPILOT_DATA ||= path.join(os.homedir(), '.papilot');
 
-// Papilot drives Codex through its app server. A codex on PATH at least as new
-// as the tested version is used as it is; otherwise that version is installed
-// once into the data folder.
-function findCodex() {
-  if (process.env.PAPILOT_CODEX_BIN) return process.env.PAPILOT_CODEX_BIN;
-  const tested = pkg.devDependencies['@openai/codex'];
-  const version = file => (spawnSync(file, ['--version'], { encoding: 'utf8' }).stdout || '').match(/\d+\.\d+\.\d+/)?.[0] || '0.0.0';
-  const recent = file => { const [a, b] = [parse(version(file)), parse(tested)]; return (a[0] - b[0] || a[1] - b[1] || a[2] - b[2]) >= 0; };
-  const onPath = (process.env.PATH || '').split(path.delimiter).map(dir => path.join(dir, 'codex')).find(file => existsSync(file));
-  if (onPath && recent(onPath)) return onPath;
-  const prefix = path.join(process.env.PAPILOT_DATA, 'agents'), installed = path.join(prefix, 'node_modules/.bin/codex');
-  if (existsSync(installed) && recent(installed)) return installed;
-  console.log(`Installing Codex ${tested} for Papilot (first run only)...`);
-  const result = spawnSync('npm', ['install', '--prefix', prefix, `@openai/codex@${tested}`, '--no-audit', '--no-fund', '--loglevel=error'], { stdio: 'inherit' });
-  if (result.status === 0 && existsSync(installed)) return installed;
-  console.warn('Codex could not be installed, so Codex tasks are unavailable. Install it with npm install -g @openai/codex and run papilot again.');
-  return '';
-}
-if (codexArgs) {
-  const codex = findCodex();
-  process.exit(codex ? spawnSync(codex, codexArgs, { stdio: 'inherit' }).status ?? 1 : 1);
-}
-if (service !== 'stop') process.env.PAPILOT_CODEX_BIN = findCodex() || 'codex';
-const { register } = await import('tsx/esm/api');
-register();
-if (service) {
-  process.argv.splice(2, Infinity, service);
-  await import('../scripts/service.ts');
-} else {
-  if (demo) await import('../scripts/demo.ts');
-  try {
-    await import('../src/server/main.ts');
-  } catch (error) {
-    if (error?.code !== 'EADDRINUSE') throw error;
-    console.error(`Port ${process.env.PAPILOT_PORT || 7274} is already in use. Is Papilot already running? Start another copy with --port <number>.`);
-    process.exit(1);
+  // Papilot drives Codex through its app server. A codex on PATH at least as new
+  // as the tested version is used as it is; otherwise that version is installed
+  // once into the data folder.
+  function findCodex() {
+    if (process.env.PAPILOT_CODEX_BIN) return process.env.PAPILOT_CODEX_BIN;
+    const tested = pkg.devDependencies['@openai/codex'];
+    const version = file => (spawnSync(file, ['--version'], { encoding: 'utf8' }).stdout || '').match(/\d+\.\d+\.\d+/)?.[0] || '0.0.0';
+    const recent = file => { const [a, b] = [parse(version(file)), parse(tested)]; return (a[0] - b[0] || a[1] - b[1] || a[2] - b[2]) >= 0; };
+    const onPath = (process.env.PATH || '').split(path.delimiter).map(dir => path.join(dir, 'codex')).find(file => existsSync(file));
+    if (onPath && recent(onPath)) return onPath;
+    const prefix = path.join(process.env.PAPILOT_DATA, 'agents'), installed = path.join(prefix, 'node_modules/.bin/codex');
+    if (existsSync(installed) && recent(installed)) return installed;
+    console.log(`Installing Codex ${tested} for Papilot (first run only)...`);
+    const result = spawnSync('npm', ['install', '--prefix', prefix, `@openai/codex@${tested}`, '--no-audit', '--no-fund', '--loglevel=error'], { stdio: 'inherit' });
+    if (result.status === 0 && existsSync(installed)) return installed;
+    console.warn('Codex could not be installed, so Codex tasks are unavailable. Install it with npm install -g @openai/codex and run papilot again.');
+    return '';
+  }
+  if (codexArgs) {
+    const codex = findCodex();
+    process.exit(codex ? spawnSync(codex, codexArgs, { stdio: 'inherit' }).status ?? 1 : 1);
+  }
+  if (service !== 'stop') process.env.PAPILOT_CODEX_BIN = findCodex() || 'codex';
+  const { register } = await import('tsx/esm/api');
+  register();
+  if (service) {
+    process.argv.splice(2, Infinity, service);
+    await import('../scripts/service.ts');
+  } else {
+    if (demo) await import('../scripts/demo.ts');
+    try {
+      await import('../src/server/main.ts');
+    } catch (error) {
+      if (error?.code !== 'EADDRINUSE') throw error;
+      console.error(`Port ${process.env.PAPILOT_PORT || 7274} is already in use. Is Papilot already running? Start another copy with --port <number>.`);
+      process.exit(1);
+    }
+    if (!tex) console.warn('\nlatexmk was not found, so PDFs cannot be built yet. Install MacTeX or TeX Live (the full distribution), open a new terminal and run papilot again.');
   }
-  if (!tex) console.warn('\nlatexmk was not found, so PDFs cannot be built yet. Install MacTeX or TeX Live (the full distribution), open a new terminal and run papilot again.');
 }
+process.exitCode = await main();