@smartdoc/cli 0.0.0-stage → 0.4.0

package/README.md

@@ -1,3 +1,44 @@
-# Temporary Holding Version
+# SmartDoc
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Review your documents with your own AI. SmartDoc is a desktop app that shows your document (a PDF); your AI reads it, marks up the text and writes findings, and you decide on each one in the app. The AI then writes the next draft from your decisions.
+
+This package is the `smartdoc` command.
+
+## Install the app
+
+```sh
+npx @smartdoc/cli install
+```
+
+Downloads the latest SmartDoc for your Mac from the project's [GitHub releases](https://github.com/tw050x/smartdoc/releases), checks it against the release's checksum, and puts it in Applications (asking before it replaces an older one), then offers to set up your agents. Or download it from the [website](https://tw050x.github.io/smartdoc/). Once installed, SmartDoc keeps itself up to date.
+
+## Set up your agents
+
+```sh
+npx @smartdoc/cli setup
+```
+
+Finds SmartDoc on your Mac and adds it to Claude Desktop and Claude Code, asking before each. (`--yes` doesn't ask.) Claude Desktop's settings file keeps everything else in it, and a copy of the file as it was is saved beside it. Agents run the connection built into the app, so they don't need Node.js once they're set up. You can do the same from the app: click its MCP server status, at the top right.
+
+## Check the connection
+
+```sh
+npx @smartdoc/cli doctor
+```
+
+Checks that SmartDoc is installed and answering, and that Claude Desktop and Claude Code are set up for it where it is now, and says what to fix.
+
+## Run the connection with npx
+
+For agents you'd rather set up with `npx`, the command `npx -y @smartdoc/cli mcp` runs SmartDoc's MCP connection. It opens the installed app when your agent first uses it, wherever the app is, and if the app isn't installed it tells your agent to send you to the website. For example:
+
+```sh
+claude mcp add --scope user smartdoc -- npx -y @smartdoc/cli mcp
+```
+
+## Requirements
+
+- macOS (Apple silicon or Intel); Windows is planned.
+- Node.js 18 or later, which runs `npx`.
+
+SmartDoc keeps your document and its drafts on your computer. Your agent reads the document through SmartDoc's tools, so what it reads goes wherever your agent sends it.

package/cli.js

@@ -0,0 +1,32 @@
+#!/usr/bin/env node
+// The smartdoc command (npx @smartdoc/cli <command>): installs the SmartDoc app, sets up AI apps to
+// use it, checks the connection, and runs SmartDoc's MCP connection for agents set up with npx.
+
+const HELP = `Usage: npx @smartdoc/cli <command>
+
+Commands:
+  install [--yes] Download the latest SmartDoc app into Applications, then offer setup
+  setup [--yes]   Add SmartDoc to Claude Desktop and Claude Code (asks first; --yes doesn't)
+  doctor          Check SmartDoc and its connections, and say what to fix
+  mcp             Run SmartDoc's MCP connection (what agents set up with npx run)
+
+SmartDoc itself is a Mac app: install it with the install command, or download it from
+https://tw050x.github.io/smartdoc/.`;
+
+const [command, ...rest] = process.argv.slice(2);
+
+if (command === 'mcp') {
+  await import('./mcp.js');
+} else if (['install', 'setup', 'doctor'].includes(command)) {
+  const commands = await import('./lib/commands.js');
+  const ask = commands.terminalAsk({ yes: rest.includes('--yes') || rest.includes('-y') });
+  try {
+    process.exitCode = await commands[command]({ ask });
+  } catch (error) {
+    console.error(error.message);
+    process.exitCode = 1;
+  }
+} else {
+  console.log(HELP);
+  process.exitCode = command && !['help', '--help', '-h'].includes(command) ? 1 : 0;
+}

package/lib/agents.js

@@ -0,0 +1,98 @@
+import { existsSync } from 'node:fs';
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { isDeepStrictEqual } from 'node:util';
+
+// Setting up AI apps to reach SmartDoc, shared by the app (its MCP panel, see the app's
+// connect.js) and the smartdoc command (setup and doctor). Each AI app runs `entry`: SmartDoc's
+// MCP launcher (mcp.js), which is inside the app, run with the app's own executable as Node, so
+// the AI app needs nothing else installed.
+
+// The entry for an installed app, from its bundle's path.
+export function launcherFor(appBundle) {
+  return {
+    command: path.join(appBundle, 'Contents', 'MacOS', 'SmartDoc'),
+    args: [path.join(appBundle, 'Contents', 'Resources', 'cli', 'mcp.js')],
+    env: { ELECTRON_RUN_AS_NODE: '1' },
+  };
+}
+
+// A word for a shell, quoted only if it needs it.
+const shellWord = (word) => (/^[\w@%+=:,./-]+$/.test(word) ? word : `'${word.replaceAll("'", "'\\''")}'`);
+
+// Claude Code's command to add it, for every project (user scope).
+export const claudeCodeCommand = ({ command, args, env }) => [
+  'claude mcp add --scope user smartdoc',
+  ...Object.entries(env).map(([k, v]) => `-e ${shellWord(`${k}=${v}`)}`),
+  '--',
+  ...[command, ...args].map(shellWord),
+].join(' ');
+
+// The JSON config entry that Claude Desktop and most other agents take.
+export const configJson = (entry) => JSON.stringify({ mcpServers: { smartdoc: entry } }, null, 2);
+
+// --- Claude Desktop ---------------------------------------------------------------------------
+
+// Claude Desktop keeps its MCP servers in this file. Tests and development point SmartDoc at
+// another with SMARTDOC_CLAUDE_CONFIG (which the packaged app ignores), so they never touch the
+// real one.
+export function claudeDesktopConfig({ env = process.env, home = os.homedir(), allowOverride = true } = {}) {
+  if (allowOverride && env.SMARTDOC_CLAUDE_CONFIG) return path.resolve(env.SMARTDOC_CLAUDE_CONFIG);
+  return path.join(home, 'Library', 'Application Support', 'Claude', 'claude_desktop_config.json');
+}
+
+// The config file's contents: {} if there's no file yet; null if it isn't JSON SmartDoc can
+// safely change (then it's left alone).
+async function readConfig(file) {
+  let text;
+  try {
+    text = await fs.readFile(file, 'utf8');
+  } catch (error) {
+    if (error.code === 'ENOENT') return {};
+    return null;
+  }
+  if (!text.trim()) return {};
+  try {
+    const config = JSON.parse(text);
+    return config && typeof config === 'object' && !Array.isArray(config) ? config : null;
+  } catch {
+    return null;
+  }
+}
+
+// Whether Claude Desktop also has SmartDoc installed as an extension (the .mcpb from earlier
+// versions), which would show SmartDoc's tools twice.
+async function hasExtension(file) {
+  try {
+    const names = await fs.readdir(path.join(path.dirname(file), 'Claude Extensions'));
+    return names.some((name) => name.toLowerCase().includes('smartdoc'));
+  } catch {
+    return false;
+  }
+}
+
+// Where Claude Desktop stands: 'not-installed' (no Claude Desktop folder), 'unreadable' (its config
+// file isn't JSON), 'not-added', 'added', or 'different' (SmartDoc is set up differently, say from
+// before the app moved); and whether the old extension is installed too.
+export async function claudeDesktopStatus(file, entry) {
+  if (!existsSync(path.dirname(file))) return { state: 'not-installed' };
+  const config = await readConfig(file);
+  const extension = await hasExtension(file);
+  if (!config) return { state: 'unreadable', file, extension };
+  const current = config.mcpServers?.smartdoc;
+  if (!current) return { state: 'not-added', extension };
+  return { state: isDeepStrictEqual(current, entry) ? 'added' : 'different', extension };
+}
+
+// Adds SmartDoc to Claude Desktop's config file, or brings its entry up to date, keeping
+// everything else in the file. The file as it was is copied beside it first.
+export async function addToClaudeDesktop(file, entry) {
+  const config = await readConfig(file);
+  if (!config) throw new Error(`Claude Desktop’s settings file isn’t in a form SmartDoc can safely change, so it was left alone: ${file}`);
+  if (existsSync(file)) await fs.copyFile(file, `${file}.before-smartdoc`);
+  const updated = { ...config, mcpServers: { ...(config.mcpServers ?? {}), smartdoc: entry } };
+  await fs.mkdir(path.dirname(file), { recursive: true });
+  await fs.writeFile(file, `${JSON.stringify(updated, null, 2)}\n`);
+  return claudeDesktopStatus(file, entry);
+}

package/lib/apps.js

@@ -0,0 +1,41 @@
+import { execFile } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { promisify } from 'node:util';
+import { APP_ID, APP_NAME } from './platform.js';
+
+// Finding the installed SmartDoc app, for the smartdoc command's setup and doctor.
+
+const run = promisify(execFile);
+
+// Copies that aren't installed: on a disk image, in the Bin, or a download kept by an earlier
+// version's launcher.
+const notInstalled = (p) => p.startsWith('/Volumes/') || p.includes('/.Trash/') || p.includes('/Library/Caches/');
+
+// The installed app's bundle: the one in Applications if there is one, else wherever macOS has
+// seen one (Spotlight, by the app's ID). Null if there's none.
+export async function findApp({ home = os.homedir() } = {}) {
+  for (const p of [`/Applications/${APP_NAME}.app`, path.join(home, 'Applications', `${APP_NAME}.app`)]) {
+    if (existsSync(p)) return p;
+  }
+  try {
+    const { stdout } = await run('mdfind', [`kMDItemCFBundleIdentifier == '${APP_ID}'`]);
+    return stdout.split('\n').map((p) => p.trim()).find((p) => p.endsWith('.app') && !notInstalled(p)) ?? null;
+  } catch {
+    return null;
+  }
+}
+
+// The app's version, from its Info.plist; null if it can't be read.
+export async function appVersion(appBundle) {
+  try {
+    const { stdout } = await run('plutil', ['-extract', 'CFBundleShortVersionString', 'raw', path.join(appBundle, 'Contents', 'Info.plist')]);
+    return stdout.trim();
+  } catch {
+    return null;
+  }
+}
+
+// Whether the app carries the MCP launcher AI apps run (SmartDoc 0.4.0 and later).
+export const hasLauncher = (appBundle) => existsSync(path.join(appBundle, 'Contents', 'Resources', 'cli', 'mcp.js'));

package/lib/bridge.js

@@ -0,0 +1,107 @@
+import readline from 'node:readline';
+import { mcpUrl } from './platform.js';
+
+// Carries MCP messages between an AI app, which talks to this launcher over stdio (one JSON-RPC
+// message per line), and the app's MCP server over HTTP. The first message the app has to
+// answer opens it, and waits until it's running. If the app goes away (say the user quits it),
+// the next message opens it again.
+//
+// `ensure()` makes sure the app is running; `token()` reads its current token.
+//
+// With `offline` (server.json: what the app's server says about itself, see
+// scripts/server-snapshot.mjs), the bridge answers the AI app's handshake itself, and its requests
+// for the lists of tools and prompts until the app is running, so an AI app isn't kept waiting,
+// and nothing is opened until the AI uses a tool.
+export function runBridge({ input = process.stdin, output = process.stdout, env = process.env, ensure, token, log = () => {}, offline = null, version = '0.0.0' }) {
+  let ready = null;
+  let running = false;
+  const whenReady = () => (ready ??= ensure().then(() => {
+    running = true;
+  }, (error) => {
+    ready = null; // try again with the next message
+    throw error;
+  }));
+
+  const write = (message) => output.write(`${JSON.stringify(message)}\n`);
+  const fail = (id, message) => id !== undefined && write({ jsonrpc: '2.0', id, error: { code: -32000, message } });
+  const answer = (id, result) => write({ jsonrpc: '2.0', id, result });
+
+  // The reply the bridge gives itself, if it does, to a message the app would otherwise answer.
+  function local(message) {
+    if (!offline) return undefined;
+    const { method, params } = message;
+    if (method === 'initialize') {
+      const asked = params?.protocolVersion;
+      return {
+        protocolVersion: offline.protocolVersions.includes(asked) ? asked : offline.protocolVersions[0],
+        capabilities: offline.capabilities,
+        serverInfo: { name: 'smartdoc', version },
+        instructions: offline.instructions,
+      };
+    }
+    if (running) return undefined;
+    if (method === 'ping') return {};
+    if (method === 'tools/list') return { tools: offline.tools };
+    if (method === 'prompts/list') return { prompts: offline.prompts };
+    return undefined;
+  }
+
+  async function post(line) {
+    const res = await fetch(mcpUrl(env), {
+      method: 'POST',
+      headers: { 'content-type': 'application/json', accept: 'application/json, text/event-stream', authorization: `Bearer ${token() ?? ''}` },
+      body: line,
+    });
+    return { status: res.status, text: (await res.text()).trim() };
+  }
+
+  async function forward(line, message) {
+    await whenReady();
+    let reply;
+    try {
+      reply = await post(line);
+    } catch {
+      // Nothing listening: the app was closed since. Open it again and retry once.
+      ready = null;
+      running = false;
+      await whenReady();
+      reply = await post(line);
+    }
+    if (reply.status >= 400) {
+      let reason = `The app refused the request (HTTP ${reply.status}).`;
+      try {
+        reason = JSON.parse(reply.text).error ?? reason;
+      } catch {}
+      return fail(message.id, reason);
+    }
+    if (reply.text) output.write(`${reply.text}\n`);
+  }
+
+  const pending = new Set();
+  const lines = readline.createInterface({ input });
+  lines.on('line', (line) => {
+    if (!line.trim()) return;
+    let message;
+    try {
+      message = JSON.parse(line);
+    } catch {
+      return;
+    }
+    // Notifications (no id) mean nothing to the app's server until it's running: it keeps no state
+    // between requests.
+    if (offline && message.id === undefined && !running) return;
+    const reply = local(message);
+    if (reply !== undefined) return answer(message.id, reply);
+    const job = forward(line, message).catch((error) => {
+      log(error.message);
+      // A tool call gets the reason as its result, which the AI reads and can pass on (say, that
+      // the app isn't installed).
+      if (message.method === 'tools/call') answer(message.id, { isError: true, content: [{ type: 'text', text: error.message }] });
+      else fail(message.id, error.message);
+    });
+    pending.add(job);
+    job.finally(() => pending.delete(job));
+  });
+
+  return new Promise((resolve) => lines.on('close', () => Promise.allSettled([...pending]).then(resolve)));
+}

package/lib/claude-code.js

@@ -0,0 +1,35 @@
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+
+// Claude Code, through its own `claude mcp` commands (it keeps its MCP servers itself).
+
+const run = promisify(execFile);
+
+// Whether the claude command is on this computer.
+export async function hasClaudeCode() {
+  try {
+    await run('claude', ['--version']);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// SmartDoc's entry in Claude Code: null if there's none, else what `claude mcp get` says about it.
+export async function claudeCodeEntry() {
+  try {
+    const { stdout } = await run('claude', ['mcp', 'get', 'smartdoc'], { timeout: 60 * 1000 });
+    return stdout;
+  } catch {
+    return null; // `claude mcp get` fails when there's no such server
+  }
+}
+
+// Whether that entry runs `entry`.
+export const claudeCodeRuns = (details, entry) => Boolean(details?.includes(entry.command) && details.includes(entry.args[0]));
+
+// Adds SmartDoc for every project (user scope), replacing an entry it had.
+export async function addToClaudeCode(entry, { replace = false } = {}) {
+  if (replace) await run('claude', ['mcp', 'remove', 'smartdoc']);
+  await run('claude', ['mcp', 'add-json', '--scope', 'user', 'smartdoc', JSON.stringify({ type: 'stdio', ...entry })]);
+}

package/lib/commands.js

@@ -0,0 +1,183 @@
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import readline from 'node:readline/promises';
+import { addToClaudeDesktop, claudeDesktopConfig, claudeDesktopStatus, launcherFor } from './agents.js';
+import { appVersion, findApp, hasLauncher } from './apps.js';
+import { addToClaudeCode, claudeCodeEntry, claudeCodeRuns, hasClaudeCode } from './claude-code.js';
+import { appRunning, installDir, installRelease, latestRelease, quitApp } from './install.js';
+import { probe } from './launch.js';
+import { APP_NAME, WEBSITE } from './platform.js';
+
+// The smartdoc command's install, setup and doctor. install puts the latest release of the app
+// in Applications, then offers setup. setup and doctor find the installed app, then look at each
+// AI app SmartDoc can set up itself (Claude Desktop and Claude Code): setup adds SmartDoc to them,
+// asking first; doctor only looks, and says what to fix. `out` is where they write;
+// `ask(question)` resolves true for yes.
+
+const ok = (text) => `  ✓ ${text}`;
+const bad = (text) => `  ✗ ${text}`;
+const note = (text) => `    ${text}`;
+
+// The installed app and the entry for it, or a reason there's none.
+async function installedApp() {
+  const app = await findApp();
+  if (!app) return { problem: `${APP_NAME} isn't installed. Install it with: npx @smartdoc/cli install (or download it from ${WEBSITE}), then run this again.` };
+  const version = await appVersion(app);
+  if (!hasLauncher(app)) return { app, version, problem: `${APP_NAME} ${version ?? ''} in ${app} is too old to connect this way. Update it with: npx @smartdoc/cli install, then run this again.` };
+  return { app, version, entry: launcherFor(app) };
+}
+
+// Asks on the terminal; with --yes, or with no terminal to ask on, says yes.
+export function terminalAsk({ yes = false } = {}) {
+  return async (question) => {
+    if (yes || !process.stdin.isTTY) return true;
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    const answer = (await rl.question(`${question} [Y/n] `)).trim().toLowerCase();
+    rl.close();
+    return answer === '' || answer === 'y' || answer === 'yes';
+  };
+}
+
+// The download's progress on one line of the terminal, if there is one.
+function progressLine(stream = process.stdout) {
+  if (!stream.isTTY) return { update() {}, done() {} };
+  let shown = -1;
+  return {
+    update(received, total) {
+      const percent = total ? Math.floor((received / total) * 100) : null;
+      if (percent === shown) return;
+      shown = percent;
+      const mb = (n) => Math.round(n / 1e6);
+      stream.write(`\r  ${percent ?? '…'}%  ${mb(received)}${total ? ` of ${mb(total)}` : ''} MB   `);
+    },
+    done: () => stream.write('\r\x1b[K'),
+  };
+}
+
+export async function install({ out = console.log, ask = terminalAsk() } = {}) {
+  if (process.platform !== 'darwin') {
+    out(`${APP_NAME} runs on macOS for now.`);
+    return 1;
+  }
+  const { version, zip } = await latestRelease();
+  if (!zip) {
+    out(`The latest release (${version}) has no build for this Mac (${process.arch}).`);
+    return 1;
+  }
+  const dir = await installDir();
+  const target = path.join(dir, `${APP_NAME}.app`);
+  const current = existsSync(target) ? await appVersion(target) : null;
+  if (current === version) out(ok(`${APP_NAME} ${version} is already installed in ${target}`));
+  else {
+    if (existsSync(target) && !(await ask(`Replace ${APP_NAME} ${current ?? ''} in ${dir} with ${version}?`))) {
+      out('Left as it is.');
+      return 0;
+    }
+    if (await appRunning()) {
+      if (!(await ask(`${APP_NAME} is open. Quit it, to install ${version}?`))) {
+        out(`Quit ${APP_NAME}, then run this again.`);
+        return 1;
+      }
+      await quitApp();
+    }
+    out(`Downloading ${APP_NAME} ${version} for this Mac…`);
+    const line = progressLine();
+    try {
+      await installRelease(zip, dir, { progress: line.update });
+    } finally {
+      line.done();
+    }
+    out(ok(`Installed ${APP_NAME} ${version} in ${target}`));
+  }
+  if (await ask('\nSet up Claude Desktop and Claude Code to use it now?')) {
+    out('');
+    return setup({ out, ask });
+  }
+  out('Set them up later with: npx @smartdoc/cli setup');
+  return 0;
+}
+
+export async function setup({ out = console.log, ask = terminalAsk() } = {}) {
+  const found = await installedApp();
+  if (found.problem) {
+    out(found.problem);
+    return 1;
+  }
+  out(`Setting up ${APP_NAME} ${found.version} (${found.app}).`);
+  let failed = false;
+
+  out('\nClaude Desktop');
+  const file = claudeDesktopConfig();
+  const desktop = await claudeDesktopStatus(file, found.entry);
+  if (desktop.state === 'not-installed') out(note('Not on this Mac.'));
+  else if (desktop.state === 'added') out(ok('Already set up.'));
+  else if (desktop.state === 'unreadable') {
+    out(bad(`Its settings file isn't in a form SmartDoc can safely change, so it was left alone: ${file}`));
+    failed = true;
+  } else if (await ask(`  ${desktop.state === 'different' ? 'Update SmartDoc in' : 'Add SmartDoc to'} Claude Desktop's settings (a copy of the file is kept)?`)) {
+    await addToClaudeDesktop(file, found.entry);
+    out(ok('Done. Quit Claude Desktop and open it again to connect.'));
+  } else out(note('Skipped.'));
+  if (desktop.extension) out(note('SmartDoc is also installed as an extension in Claude Desktop. Remove it in Settings → Extensions, so its tools don’t show twice.'));
+
+  out('\nClaude Code');
+  if (!(await hasClaudeCode())) out(note('Not on this computer (no claude command).'));
+  else {
+    const details = await claudeCodeEntry();
+    if (claudeCodeRuns(details, found.entry)) out(ok('Already set up.'));
+    else if (await ask(`  ${details ? 'Replace SmartDoc’s setup in' : 'Add SmartDoc to'} Claude Code, for all your projects?`)) {
+      try {
+        await addToClaudeCode(found.entry, { replace: Boolean(details) });
+        out(ok('Done. Start a new Claude Code session to connect.'));
+      } catch (error) {
+        out(bad(`Claude Code didn't take it: ${error.stderr?.trim() || error.message}`));
+        failed = true;
+      }
+    } else out(note('Skipped.'));
+  }
+
+  out(`\nFor other agents, open ${APP_NAME} and click its MCP server status, at the top right.`);
+  return failed ? 1 : 0;
+}
+
+export async function doctor({ out = console.log } = {}) {
+  let problems = 0;
+  const fail = (text, fix) => {
+    problems++;
+    out(bad(text));
+    if (fix) out(note(fix));
+  };
+
+  out(`${APP_NAME}`);
+  const found = await installedApp();
+  if (found.problem) {
+    fail(found.problem);
+    return 1;
+  }
+  out(ok(`${APP_NAME} ${found.version} is installed in ${found.app}`));
+  const state = await probe();
+  if (state === 'up') out(ok(`${APP_NAME} is running, and its MCP server answers`));
+  else if (state === 'locked') fail(`Something answers on SmartDoc's port, but not with SmartDoc's token`, 'Quit SmartDoc and open it again.');
+  else out(note(`${APP_NAME} isn't running. That's fine: your agent opens it when it needs it.`));
+
+  out('\nClaude Desktop');
+  const desktop = await claudeDesktopStatus(claudeDesktopConfig(), found.entry);
+  if (desktop.state === 'not-installed') out(note('Not on this Mac.'));
+  else if (desktop.state === 'added') out(ok('Set up for SmartDoc where it is now'));
+  else if (desktop.state === 'not-added') fail('SmartDoc isn’t set up in Claude Desktop', 'Run: npx @smartdoc/cli setup');
+  else if (desktop.state === 'different') fail('Claude Desktop is set up for SmartDoc somewhere else (or the old way)', 'Run: npx @smartdoc/cli setup');
+  else fail(`Its settings file isn't valid JSON: ${desktop.file}`, 'Fix or remove the file, then run: npx @smartdoc/cli setup');
+  if (desktop.extension) fail('SmartDoc is also installed as an extension, so its tools may show twice', 'Remove it in Claude Desktop’s Settings → Extensions.');
+
+  out('\nClaude Code');
+  if (!(await hasClaudeCode())) out(note('Not on this computer (no claude command).'));
+  else {
+    const details = await claudeCodeEntry();
+    if (claudeCodeRuns(details, found.entry)) out(ok('Set up for SmartDoc where it is now'));
+    else if (details) fail('Claude Code is set up for SmartDoc somewhere else (or the old way)', 'Run: npx @smartdoc/cli setup');
+    else fail('SmartDoc isn’t set up in Claude Code', 'Run: npx @smartdoc/cli setup');
+  }
+
+  out(problems ? `\n${problems} thing${problems === 1 ? '' : 's'} to fix.` : '\nAll good.');
+  return problems ? 1 : 0;
+}

package/lib/install.js

@@ -0,0 +1,118 @@
+import { execFile } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { createWriteStream, existsSync } from 'node:fs';
+import { access, constants, mkdir, mkdtemp, rename, rm } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { Readable, Transform } from 'node:stream';
+import { pipeline } from 'node:stream/promises';
+import { promisify } from 'node:util';
+import { APP_ID, APP_NAME, REPOSITORY } from './platform.js';
+
+// Installing the app, for the smartdoc command's install: the latest release's build for this
+// Mac, as the app's own updater finds it (latest-mac.yml lists each zip with its SHA-512), checked
+// and unpacked into Applications. Tests point it at a stand-in release (SMARTDOC_DOWNLOADS) and
+// another folder (SMARTDOC_INSTALL_DIR).
+
+const run = promisify(execFile);
+
+export const downloadBase = (env = process.env) => (env.SMARTDOC_DOWNLOADS ?? `https://github.com/${REPOSITORY}/releases/latest/download`).replace(/\/$/, '');
+
+// The release's version and files, from latest-mac.yml (the few lines electron-builder writes).
+export function parseLatest(text) {
+  const files = [];
+  let version = null;
+  for (const line of text.split(/\r?\n/)) {
+    const field = line.match(/^\s*(-\s+)?(\w+):\s*'?([^']*?)'?\s*$/);
+    if (!field) continue;
+    const [, item, key, value] = field;
+    if (!item && !line.startsWith(' ') && key === 'version') version = value;
+    else if (item && key === 'url') files.push({ url: value });
+    else if (line.startsWith('    ') && files.length && (key === 'sha512' || key === 'size')) files.at(-1)[key] = key === 'size' ? Number(value) : value;
+  }
+  return { version, files };
+}
+
+// The zip for this Mac: arm64 or x64 in its name.
+export function zipFor(files, arch = process.arch) {
+  return files.find((f) => f.url.endsWith('.zip') && f.url.includes(`-mac-${arch}`)) ?? null;
+}
+
+// Where the app goes: Applications if the user can write there, else ~/Applications.
+export async function installDir({ env = process.env, home = os.homedir() } = {}) {
+  if (env.SMARTDOC_INSTALL_DIR) return path.resolve(env.SMARTDOC_INSTALL_DIR);
+  try {
+    await access('/Applications', constants.W_OK);
+    return '/Applications';
+  } catch {
+    return path.join(home, 'Applications');
+  }
+}
+
+async function get(url, signal) {
+  const res = await fetch(url, { redirect: 'follow', signal });
+  if (!res.ok) throw new Error(`Couldn’t download ${url} (HTTP ${res.status}).`);
+  return res;
+}
+
+// What the latest release offers this Mac: { version, zip } (zip null if there's no build for it).
+export async function latestRelease({ env = process.env, arch = process.arch } = {}) {
+  const { version, files } = parseLatest(await (await get(`${downloadBase(env)}/latest-mac.yml`)).text());
+  if (!version) throw new Error('The latest release doesn’t say its version.');
+  return { version, zip: zipFor(files, arch) };
+}
+
+// Downloads and checks the zip, unpacks it, and puts the app in `dir` (replacing one there). Calls
+// `progress(received, total)` as it downloads. Resolves to the app's path.
+export async function installRelease(zip, dir, { env = process.env, progress = () => {} } = {}) {
+  const work = await mkdtemp(path.join(os.tmpdir(), 'smartdoc-install-'));
+  try {
+    const file = path.join(work, path.basename(zip.url));
+    const res = await get(`${downloadBase(env)}/${zip.url}`);
+    const total = Number(res.headers.get('content-length')) || zip.size || null;
+    const hash = createHash('sha512');
+    let received = 0;
+    const tap = new Transform({
+      transform(chunk, _encoding, done) {
+        hash.update(chunk);
+        received += chunk.length;
+        progress(received, total);
+        done(null, chunk);
+      },
+    });
+    await pipeline(Readable.fromWeb(res.body), tap, createWriteStream(file));
+    if (hash.digest('base64') !== zip.sha512) throw new Error(`The download of ${zip.url} didn’t match the release’s checksum, so it wasn’t used.`);
+
+    // ditto keeps the app's code signature, permissions and links intact.
+    const unpacked = path.join(work, 'unpacked');
+    await run('ditto', ['-x', '-k', file, unpacked]);
+    const built = path.join(unpacked, `${APP_NAME}.app`);
+    if (!existsSync(built)) throw new Error(`${zip.url} doesn’t contain ${APP_NAME}.app.`);
+
+    await mkdir(dir, { recursive: true });
+    const target = path.join(dir, `${APP_NAME}.app`);
+    await rm(target, { recursive: true, force: true });
+    try {
+      await rename(built, target);
+    } catch {
+      await run('ditto', [built, target]); // another disk: copied instead
+    }
+    return target;
+  } finally {
+    await rm(work, { recursive: true, force: true });
+  }
+}
+
+// Whether the app is open (macOS knows it by its ID), and quitting it.
+export async function appRunning() {
+  try {
+    const { stdout } = await run('osascript', ['-e', `application id "${APP_ID}" is running`]);
+    return stdout.trim() === 'true';
+  } catch {
+    return false;
+  }
+}
+export async function quitApp() {
+  await run('osascript', ['-e', `tell application id "${APP_ID}" to quit`]);
+  for (let i = 0; i < 40 && (await appRunning()); i++) await new Promise((r) => setTimeout(r, 250));
+}