dsh-mishu 0.5.0 → 0.5.4

package/lib/core/mail/sync.js

@@ -8,15 +8,18 @@
  */
 import { applyVerdict, closeReadElsewhere } from "../fold.js";
 import { bi } from "../i18n.js";
+import { presetById } from "./account.js";
 import { judgeMail } from "./rules.js";
 export const MAIL_SOURCE = 'mail';
 /** A connection or login failure, said so a person knows what to fix. */
 export function describeMailError(error, account) {
     const raw = error.responseText ?? error.message ?? String(error);
     const auth = /auth|login|password|credential|AUTHENTICATIONFAILED|LOGIN failed/i.test(raw);
-    return auth
-        ? bi(`登录失败：服务器不接受这个用户名或密码（${raw}）。多数邮箱要填客户端授权码或应用专用密码，不是网页登录密码。`, `Login failed: the server rejected the user name or password (${raw}). Most providers need an app password, not your web password.`)
-        : bi(`连接 ${account.host}:${account.port} 失败：${raw}`, `Could not reach ${account.host}:${account.port}: ${raw}`);
+    if (!auth)
+        return bi(`连接 ${account.host}:${account.port} 失败：${raw}`, `Could not reach ${account.host}:${account.port}: ${raw}`);
+    const preset = presetById(account.preset);
+    const howTo = preset.id === 'custom' ? undefined : preset.howTo;
+    return bi(`登录失败：服务器不接受这个用户名或密码（${raw}）。多数邮箱要先开启 IMAP，再填客户端授权码或应用专用密码，不是网页登录密码。${howTo === undefined ? '' : `\n${preset.label.zh}：${howTo.zh}`}`, `Login failed: the server rejected the user name or password (${raw}). Most providers need IMAP turned on and an app password, not your web password.${howTo === undefined ? '' : `\n${preset.label.en}: ${howTo.en}`}`);
 }
 export function mailReportKey(accountId) {
     return `mail.lastSync.${accountId}`;

package/lib/core/restart.js

@@ -0,0 +1,149 @@
+/**
+ * Restarting DSH after plugins were reinstalled or upgraded.
+ *
+ * In the desktop app, DSH runs as a child of the app's main process
+ * (Electron as Node, `ELECTRON_RUN_AS_NODE=1`). The `dsh` command runs on
+ * the same binary the same way, so the test is the parent: only when the
+ * parent process IS this app binary is there an app to restart (from a
+ * terminal the parent is a shell, and `__CFBundleIdentifier` names the
+ * terminal app — never trusted). A restart asks the app to
+ * quit the normal way — so it still asks first when a task is running — and
+ * opens it again once it is gone. That is done by a small detached helper,
+ * because this process ends with the app.
+ *
+ *   macOS    AppleScript `quit`, then `open -b <bundle id>`   (tested)
+ *   Windows  `taskkill /PID` without /F (a close request), then the app again
+ *   Linux    SIGTERM to the app, then the app again
+ *
+ * DSH started with the `dsh` command is not restarted from here: its web
+ * address (with a new sign-in token) is printed in that terminal, which a
+ * detached replacement could not reach. The page says what to do instead.
+ */
+import { execFileSync, spawn } from 'node:child_process';
+import { readlinkSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { findProgram } from "./exec.js";
+import { bi } from "./i18n.js";
+/** `<x>.app` holding a macOS executable, if any. */
+function appBundle(execPath) {
+    const at = execPath.indexOf('.app/');
+    return at < 0 ? undefined : execPath.slice(0, at + 4);
+}
+function parentExecutable(ppid, platform) {
+    try {
+        if (platform === 'linux')
+            return readlinkSync(`/proc/${ppid}/exe`);
+        if (platform === 'win32') {
+            const ps = findProgram('powershell');
+            return ps === undefined ? undefined : execFileSync(ps, ['-NoProfile', '-NonInteractive', '-Command', `(Get-Process -Id ${ppid}).Path`], { timeout: 10_000, windowsHide: true }).toString().trim();
+        }
+        return execFileSync('/bin/ps', ['-o', 'comm=', '-p', String(ppid)], { timeout: 5000 }).toString().trim();
+    }
+    catch {
+        return undefined;
+    }
+}
+function bundleIdOf(app) {
+    try {
+        return execFileSync('/usr/bin/defaults', ['read', `${app}/Contents/Info`, 'CFBundleIdentifier'], { timeout: 5000 }).toString().trim();
+    }
+    catch {
+        return undefined;
+    }
+}
+function here() {
+    const facts = { env: process.env, platform: process.platform, execPath: process.execPath, ppid: process.ppid, electron: process.versions.electron, parentExe: undefined, bundleId: undefined };
+    if (facts.electron === undefined || facts.env.ELECTRON_RUN_AS_NODE !== '1' || facts.ppid <= 1)
+        return facts;
+    facts.parentExe = parentExecutable(facts.ppid, facts.platform);
+    const app = facts.platform === 'darwin' ? appBundle(facts.execPath) : undefined;
+    if (app !== undefined)
+        facts.bundleId = bundleIdOf(app);
+    return facts;
+}
+function samePath(a, b, platform) {
+    return a !== undefined && (platform === 'win32' ? a.toLowerCase() === b.toLowerCase() : a === b);
+}
+const FROM_TERMINAL = bi('这个 DSH 是用 dsh 命令启动的，小秘书没法替它重启：回到运行 dsh 的那个终端按 Ctrl+C，再运行同一条命令。', 'This DSH was started with the dsh command, so the secretary cannot restart it: press Ctrl+C in the terminal running dsh, then run the same command again.');
+/** How DSH can be restarted from here, or why it cannot. */
+export function restartPlan(facts = here()) {
+    const desktop = facts.electron !== undefined && facts.env.ELECTRON_RUN_AS_NODE === '1' && facts.ppid > 1 && samePath(facts.parentExe, facts.execPath, facts.platform);
+    if (!desktop)
+        return { kind: 'none', why: FROM_TERMINAL };
+    if (facts.platform === 'darwin') {
+        const bundleId = facts.bundleId ?? '';
+        if (/^[\w.-]+$/.test(bundleId))
+            return { kind: 'macos-app', bundleId, appPid: facts.ppid };
+        return { kind: 'none', why: bi('没找到桌面版的应用标识，没法替它重启。请退出 DSH 再打开。', 'Could not tell which app this is, so it cannot be restarted from here. Quit DSH and open it again.') };
+    }
+    if (facts.platform === 'win32' || facts.platform === 'linux')
+        return { kind: 'desktop-app', platform: facts.platform, exe: facts.execPath, appPid: facts.ppid };
+    return { kind: 'none', why: bi('这个系统上没法替桌面版重启。请退出 DSH 再打开。', 'The desktop app cannot be restarted from here on this system. Quit DSH and open it again.') };
+}
+const MAC_TOOLS = { osascript: '/usr/bin/osascript', open: '/usr/bin/open' };
+/**
+ * Source of the detached helper: ask the app to quit, wait until it is gone
+ * (giving up quietly when you cancel the quit), open it again, and check it
+ * came back. Every step is noted in `log`, the only account of a restart
+ * once this process is gone.
+ *
+ * The helper itself runs as Node (`ELECTRON_RUN_AS_NODE=1`), and whatever it
+ * launches inherits its environment — `open` included ("Opened applications
+ * inherit environment variables", open(1)). So the app is always started
+ * without that variable; with it, the app starts as bare Node and exits.
+ */
+export function restartHelperSource(plan, log, tools = MAC_TOOLS) {
+    const mac = plan.kind === 'macos-app';
+    const app = mac ? `application id ${JSON.stringify(plan.bundleId)}` : '';
+    const quit = mac
+        ? `spawnSync(${JSON.stringify(tools.osascript)}, ['-e', ${JSON.stringify(`tell ${app} to quit`)}], { timeout: 180000 })`
+        : plan.platform === 'win32'
+            ? `spawnSync('taskkill', ['/PID', String(pid)], { windowsHide: true })`
+            : `process.kill(pid, 'SIGTERM')`;
+    // Answers whether the app runs again; only macOS can ask, elsewhere the launch is trusted.
+    const running = mac
+        ? `String(spawnSync(${JSON.stringify(tools.osascript)}, ['-e', ${JSON.stringify(`${app} is running`)}], { timeout: 10000 }).stdout).trim() === 'true'`
+        : 'true';
+    const open = mac
+        ? `const r = spawnSync(${JSON.stringify(tools.open)}, ['-b', ${JSON.stringify(plan.bundleId)}], { env: clean, timeout: 60000 }); note('open exited ' + r.status + (String(r.stderr || '').trim() ? ': ' + String(r.stderr).trim() : ''))`
+        : `spawn(${JSON.stringify(plan.exe)}, [], { detached: true, stdio: 'ignore', env: clean }).unref()`;
+    return [
+        "const { spawn, spawnSync } = require('node:child_process')",
+        "const fs = require('node:fs')",
+        `const pid = ${plan.appPid}`,
+        `const log = ${JSON.stringify(log)}`,
+        "const clean = Object.fromEntries(Object.entries(process.env).filter(([k]) => k !== 'ELECTRON_RUN_AS_NODE'))",
+        "const note = (line) => { try { fs.appendFileSync(log, new Date().toISOString() + ' ' + line + '\\n') } catch {} }",
+        'const sleep = (ms) => new Promise(r => setTimeout(r, ms))',
+        "const alive = () => { try { process.kill(pid, 0); return true } catch (e) { return e.code === 'EPERM' } }",
+        `const running = () => { try { return ${running} } catch { return false } }`,
+        `const open = () => { try { ${open} } catch (e) { note('could not open the app: ' + (e && e.message)) } }`,
+        'const main = async () => {',
+        // Let the page receive its answer before the app starts closing.
+        '  await sleep(400)',
+        "  note('asking the app (pid ' + pid + ') to quit')",
+        `  try { ${quit} } catch (e) { note('quit request failed: ' + (e && e.message)) }`,
+        '  const until = Date.now() + 180000',
+        '  while (alive() && Date.now() < until) await sleep(300)',
+        "  if (alive()) { note('the app is still running (the quit was cancelled?); not reopening'); return }",
+        '  await sleep(800)',
+        '  for (let attempt = 1; attempt <= 2; attempt++) {',
+        "    note('opening the app (attempt ' + attempt + ')')",
+        '    open()',
+        '    const by = Date.now() + 20000',
+        '    while (!running() && Date.now() < by) await sleep(500)',
+        "    if (running()) { note('the app is running again'); return }",
+        '  }',
+        "  note('the app did not come back; open it yourself')",
+        '}',
+        "main().catch(e => note('helper failed: ' + (e && e.stack || e)))",
+    ].join('\n');
+}
+/** Start the helper and return where it logs. Runs with this process's Node (Electron as Node in the app). */
+export function scheduleRestart(plan) {
+    const log = join(tmpdir(), `dsh-mishu-restart-${new Date().toISOString().replace(/[:.]/g, '-').slice(0, 19)}.log`);
+    const helper = spawn(process.execPath, ['-e', restartHelperSource(plan, log)], { detached: true, stdio: 'ignore', env: process.env, windowsHide: true });
+    helper.unref();
+    return { log };
+}

package/lib/core/secrets.js

@@ -10,17 +10,26 @@
  * stored under the service name "dsh-mishu". When no keychain is available,
  * `secretFromEnv` is the documented fallback.
  */
-import { execFile } from 'node:child_process';
+import { findProgram, runProgram } from "./exec.js";
+import { bi } from "./i18n.js";
 export const SERVICE = 'dsh-mishu';
-function run(file, args, input) {
-    return new Promise((resolve) => {
-        const child = execFile(file, args, { timeout: 15_000, windowsHide: true, maxBuffer: 1 << 20 }, (error, stdout, stderr) => {
-            const code = error === null ? 0 : typeof error.code === 'number' ? error.code : 1;
-            resolve({ code, stdout: String(stdout), stderr: String(stderr) });
-        });
-        child.stdin?.end(input ?? '');
-    });
+/** A helper program, found by full path so a short PATH does not hide it. */
+class Helper {
+    name;
+    path;
+    constructor(name) { this.name = name; }
+    find() {
+        this.path ??= findProgram(this.name);
+        return this.path;
+    }
+    async run(args, input) {
+        const path = this.find();
+        if (path === undefined)
+            return { code: 127, stdout: '', stderr: '', failure: `${this.name} not found` };
+        return runProgram(path, args, input);
+    }
 }
+const detail = (r) => (r.stderr.trim() || r.failure || `exit ${r.code}`).slice(0, 300);
 /** Accounts are plain ids we choose ("mail:3"); refuse anything else so they are safe in every helper. */
 function checkAccount(account) {
     if (!/^[\w:.-]{1,80}$/.test(account))
@@ -32,32 +41,47 @@ function checkSecret(secret) {
 }
 class MacKeychain {
     kind = 'macos';
-    async available() { return (await run('security', ['help'])).code === 0 || (await run('security', ['list-keychains'])).code === 0; }
+    security = new Helper('security');
+    async status() {
+        const r = await this.security.run(['list-keychains']);
+        if (r.code === 0)
+            return { available: true };
+        return { available: false, why: bi(`macOS 钥匙串用不了（${detail(r)}）`, `the macOS Keychain is not usable (${detail(r)})`) };
+    }
     async get(account) {
         checkAccount(account);
-        const r = await run('security', ['find-generic-password', '-s', SERVICE, '-a', account, '-w']);
+        const r = await this.security.run(['find-generic-password', '-s', SERVICE, '-a', account, '-w']);
         return r.code === 0 ? r.stdout.replace(/\n$/, '') : undefined;
     }
     async set(account, secret) {
         checkAccount(account);
         checkSecret(secret);
         // `-w` last: security prompts twice and reads both answers from stdin.
-        const r = await run('security', ['add-generic-password', '-U', '-s', SERVICE, '-a', account, '-l', `${SERVICE} ${account}`, '-w'], `${secret}\n${secret}\n`);
+        const r = await this.security.run(['add-generic-password', '-U', '-s', SERVICE, '-a', account, '-l', `${SERVICE} ${account}`, '-w'], `${secret}\n${secret}\n`);
         if (r.code !== 0)
             throw new Error(`Keychain refused to save the password (${r.stderr.trim() || r.code})`);
     }
     async delete(account) {
         checkAccount(account);
-        await run('security', ['delete-generic-password', '-s', SERVICE, '-a', account]);
+        await this.security.run(['delete-generic-password', '-s', SERVICE, '-a', account]);
     }
 }
 const PS_PRELUDE = '[void][Windows.Security.Credentials.PasswordVault,Windows.Security.Credentials,ContentType=WindowsRuntime];$v=New-Object Windows.Security.Credentials.PasswordVault;';
 class WindowsVault {
     kind = 'windows';
+    powershell = new Helper('powershell');
     ps(script, input) {
-        return run('powershell.exe', ['-NoProfile', '-NonInteractive', '-Command', PS_PRELUDE + script], input);
+        return this.powershell.run(['-NoProfile', '-NonInteractive', '-Command', PS_PRELUDE + script], input);
+    }
+    async status() {
+        if (this.powershell.find() === undefined) {
+            return { available: false, why: bi('没找到 Windows PowerShell（powershell.exe），小秘书靠它使用 Windows 凭据管理器', 'Windows PowerShell (powershell.exe) was not found; the secretary uses it to reach Windows Credential Manager') };
+        }
+        const r = await this.ps('exit 0');
+        if (r.code === 0)
+            return { available: true };
+        return { available: false, why: bi(`Windows 凭据管理器用不了（${detail(r)}）`, `Windows Credential Manager is not usable (${detail(r)})`) };
     }
-    async available() { return (await this.ps('exit 0')).code === 0; }
     async get(account) {
         checkAccount(account);
         const r = await this.ps(`try{$c=$v.Retrieve('${SERVICE}','${account}');$c.RetrievePassword();[Console]::Out.Write($c.Password)}catch{exit 3}`);
@@ -77,31 +101,55 @@ class WindowsVault {
 }
 class SecretTool {
     kind = 'linux';
-    async available() { return (await run('secret-tool', ['--version'])).code === 0; }
+    tool = new Helper('secret-tool');
+    async status() {
+        if (this.tool.find() === undefined) {
+            return {
+                available: false,
+                why: bi('没找到 secret-tool。Debian/Ubuntu 装 libsecret-tools（sudo apt install libsecret-tools），Fedora 装 libsecret（sudo dnf install libsecret），Arch 装 libsecret', 'secret-tool was not found. Install libsecret-tools on Debian/Ubuntu (sudo apt install libsecret-tools), libsecret on Fedora (sudo dnf install libsecret) or Arch'),
+            };
+        }
+        // A lookup that finds nothing exits 1 quietly; a missing keyring service complains on stderr.
+        const r = await this.tool.run(['lookup', 'service', SERVICE, 'account', 'probe']);
+        if (r.code === 0 || (r.code === 1 && r.stderr.trim() === '' && r.failure === undefined))
+            return { available: true };
+        return {
+            available: false,
+            why: bi(`secret-tool 连不上钥匙串服务（${detail(r)}）。要在桌面会话里运行着 GNOME Keyring 或 KWallet；没有桌面的服务器上一般没有`, `secret-tool cannot reach a keyring service (${detail(r)}). It needs GNOME Keyring or KWallet running in a desktop session; servers without a desktop usually have none`),
+        };
+    }
     async get(account) {
         checkAccount(account);
-        const r = await run('secret-tool', ['lookup', 'service', SERVICE, 'account', account]);
+        const r = await this.tool.run(['lookup', 'service', SERVICE, 'account', account]);
         return r.code === 0 && r.stdout !== '' ? r.stdout.replace(/\n$/, '') : undefined;
     }
     async set(account, secret) {
         checkAccount(account);
         checkSecret(secret);
-        const r = await run('secret-tool', ['store', '--label', `${SERVICE} ${account}`, 'service', SERVICE, 'account', account], secret);
+        const r = await this.tool.run(['store', '--label', `${SERVICE} ${account}`, 'service', SERVICE, 'account', account], secret);
         if (r.code !== 0)
             throw new Error(`Secret Service refused to save the password (${r.stderr.trim() || r.code})`);
     }
     async delete(account) {
         checkAccount(account);
-        await run('secret-tool', ['clear', 'service', SERVICE, 'account', account]);
+        await this.tool.run(['clear', 'service', SERVICE, 'account', account]);
     }
 }
-/** For tests: secrets in memory only. */
+/** For tests: secrets in memory only; `unavailable` plays a machine without a keychain. */
 export class MemorySecrets {
     kind = 'memory';
     map = new Map();
-    async available() { return true; }
-    async get(account) { return this.map.get(account); }
-    async set(account, secret) { checkAccount(account); checkSecret(secret); this.map.set(account, secret); }
+    unavailable;
+    constructor(unavailable) { this.unavailable = unavailable; }
+    async status() { return this.unavailable === undefined ? { available: true } : { available: false, why: this.unavailable }; }
+    async get(account) { return this.unavailable === undefined ? this.map.get(account) : undefined; }
+    async set(account, secret) {
+        checkAccount(account);
+        checkSecret(secret);
+        if (this.unavailable !== undefined)
+            throw new Error(this.unavailable.en);
+        this.map.set(account, secret);
+    }
     async delete(account) { this.map.delete(account); }
 }
 /** The keychain of the platform this runs on. */

package/lib/core/settings.js

@@ -9,6 +9,7 @@ import { MishuError, bi } from "./i18n.js";
 import { resolveAccount, secretAccount } from "./mail/account.js";
 import { MAIL_SOURCE } from "./mail/sync.js";
 import { CATEGORIES } from "./recur.js";
+import { secretFromEnv } from "./secrets.js";
 const SETTINGS_KEY = 'settings';
 const ACCOUNTS_KEY = 'mail.accounts';
 const NEXT_ID_KEY = 'mail.nextId';
@@ -56,7 +57,9 @@ export function mailAccounts(store) {
 /**
  * Add (no id) or update an account. A new password, when given, goes to the
  * keychain before the account is saved, so a failed keychain write leaves
- * nothing half-saved.
+ * nothing half-saved. Without a usable keychain the password is not kept
+ * anywhere: the account is saved and reads it from the environment variable
+ * shown on the settings page (`secretEnvName`).
  */
 export async function saveMailAccount(store, secrets, input, password, now) {
     const accounts = mailAccounts(store);
@@ -65,9 +68,10 @@ export async function saveMailAccount(store, secrets, input, password, now) {
         throw new MishuError(bi(`没有 #${input.id} 这个邮箱账户`, `there is no mail account #${input.id}`));
     const id = existing?.id ?? (store.get(NEXT_ID_KEY) ?? 1);
     const account = resolveAccount({ ...existing, ...input }, id);
-    if (password !== undefined && password !== '')
+    const keychain = (await secrets.status()).available;
+    if (keychain && password !== undefined && password !== '')
         await secrets.set(secretAccount(id), password);
-    else if (existing === undefined && await secrets.get(secretAccount(id)) === undefined) {
+    else if (keychain && existing === undefined && await secrets.get(secretAccount(id)) === undefined && secretFromEnv(secretAccount(id)) === undefined) {
         throw new MishuError(bi('新邮箱要填密码（授权码）', 'a new account needs its password (app password)'));
     }
     store.set(ACCOUNTS_KEY, existing === undefined ? [...accounts, account] : accounts.map(a => (a.id === id ? account : a)));

package/lib/dsh/api.js

@@ -9,7 +9,7 @@
  * travel inward: they go straight to the keychain, and no endpoint ever
  * returns one.
  */
-import { addDays, addSeries, buildAsk, buildBoard, buildDetail, dayOf, deleteMailAccount, describeMailError, MishuError, describeSeries, detectLang, errorText, GitHubClient, MAIL_PRESETS, mailReportKey, resolveGithubToken, resolveSeries, saveMailAccount, saveSettings, secretAccount, secretEnvName, setStatusByUser, snoozeByUser, stopSeries, tickManual, } from "../core/index.js";
+import { addDays, addSeries, bi, buildAsk, buildBoard, buildDetail, dayOf, deleteGithubToken, deleteMailAccount, describeMailError, MishuError, describeSeries, detectLang, errorText, GitHubClient, MAIL_PRESETS, mailReportKey, NEW_TOKEN_URL, resolveSeries, saveGithubToken, saveMailAccount, saveSettings, secretAccount, secretEnvName, setStatusByUser, snoozeByUser, stopSeries, tickManual, } from "../core/index.js";
 import { resolveAccount } from "../core/mail/account.js";
 export const API_BASE = '/api/dsh-mishu';
 class ApiError extends Error {
@@ -82,14 +82,8 @@ export function apiHandlers(runtime, clock = Date.now) {
     /** Everything the settings page shows. No secret is ever included. */
     const settingsView = async (lang) => {
         const store = need(lang);
-        const token = await resolveGithubToken(runtime.config.github.tokenEnv, runtime.config.github.useGhCli);
-        let available = false;
-        try {
-            available = await runtime.secrets.available();
-        }
-        catch {
-            available = false;
-        }
+        const token = await runtime.githubToken();
+        const secrets = await runtime.secrets.status().catch((error) => ({ available: false, why: bi(error.message, error.message) }));
         const accounts = await Promise.all(runtime.accounts().map(async (a) => ({
             ...a,
             hasPassword: (await runtime.mailPassword(a.id)) !== undefined,
@@ -102,9 +96,10 @@ export function apiHandlers(runtime, clock = Date.now) {
             github: {
                 tokenEnv: runtime.config.github.tokenEnv,
                 token: 'error' in token ? { found: false, text: token.error[lang] } : { found: true, from: token.from },
+                newTokenUrl: NEW_TOKEN_URL,
                 lastSync: store.get('github.lastSync') ?? null,
             },
-            secrets: { kind: runtime.secrets.kind, available },
+            secrets: { kind: runtime.secrets.kind, available: secrets.available, ...secrets.available ? {} : { why: secrets.why[lang] } },
             accounts,
             presets: MAIL_PRESETS.map(p => ({ id: p.id, label: p.label[lang], host: p.host, port: p.port, secure: p.secure, supported: p.supported, howTo: p.howTo[lang] })),
         };
@@ -187,6 +182,7 @@ export function apiHandlers(runtime, clock = Date.now) {
                 ...ask.id === undefined ? {} : { id: Number(ask.id) },
                 ...ask.accountId === undefined ? {} : { accountId: Number(ask.accountId) },
                 ...ask.preset === undefined ? {} : { preset: String(ask.preset) },
+                ...typeof ask.error === 'string' && ask.error !== '' ? { error: ask.error.slice(0, 1000) } : {},
             };
             const prompt = buildAsk(need(lang), request, { now: clock(), lang, markRead: runtime.settings().markRead, accounts: runtime.accounts() });
             return { prompt };
@@ -200,12 +196,22 @@ export function apiHandlers(runtime, clock = Date.now) {
         },
         '/github/test': async (body) => {
             const lang = langOf(body);
-            const token = await resolveGithubToken(runtime.config.github.tokenEnv, runtime.config.github.useGhCli);
+            const token = await runtime.githubToken();
             if ('error' in token)
                 throw new ApiError(token.error[lang]);
             const user = await new GitHubClient({ token: token.token }).user();
             return { login: user.login, from: token.from };
         },
+        /** A pasted token: checked with GitHub, then kept in the keychain only. */
+        '/github/token/save': async (body) => {
+            const lang = langOf(body);
+            const { login } = await saveGithubToken(runtime.secrets, typeof body.token === 'string' ? body.token : '');
+            return { login, view: await settingsView(lang) };
+        },
+        '/github/token/delete': async (body) => {
+            await deleteGithubToken(runtime.secrets);
+            return { view: await settingsView(langOf(body)) };
+        },
         '/mail/save': async (body) => {
             const lang = langOf(body);
             const account = await saveMailAccount(need(lang), runtime.secrets, accountInput(body.account), password(body), clock());
@@ -234,6 +240,18 @@ export function apiHandlers(runtime, clock = Date.now) {
             }
             return { view: await settingsView(lang) };
         },
+        /** Whether the page's "restart DSH" button can work here, and if not, what to do instead. */
+        '/restart/info': async (body) => {
+            const plan = runtime.restarter.plan();
+            return plan.kind === 'none' ? { supported: false, why: plan.why[langOf(body)] } : { supported: true };
+        },
+        '/restart': async (body) => {
+            const plan = runtime.restarter.plan();
+            if (plan.kind === 'none')
+                throw new ApiError(plan.why[langOf(body)]);
+            const { log } = runtime.restarter.schedule(plan);
+            return { restarting: true, log };
+        },
         '/mail/sync': async (body) => {
             const lang = langOf(body);
             const account = runtime.accounts().find(a => a.id === Number(body.id));

package/lib/dsh/runtime.js

@@ -4,7 +4,7 @@
  * what you set on the settings page on top), the keychain, and one sync of
  * every source at a time.
  */
-import { dayOf, detectLang, effectiveSettings, GitHubClient, ImapFetcher, mailAccounts, mailReportKey, renderBrief, resolveGithubToken, secretAccount, secretFromEnv, syncGithub, syncMail, systemSecrets, tickManual, bi, } from "../core/index.js";
+import { dayOf, detectLang, effectiveSettings, GitHubClient, ImapFetcher, mailAccounts, mailReportKey, renderBrief, resolveGithubToken, secretAccount, secretFromEnv, syncGithub, syncMail, systemSecrets, tickManual, bi, restartPlan, scheduleRestart, } from "../core/index.js";
 export class Runtime {
     store;
     config;
@@ -12,6 +12,8 @@ export class Runtime {
     fetcher;
     logger;
     syncing;
+    /** How DSH restarts; tests swap it so they never restart anything. */
+    restarter = { plan: () => restartPlan(), schedule: scheduleRestart };
     constructor(config, logger, secrets = systemSecrets(), fetcher = new ImapFetcher()) {
         this.config = config;
         this.logger = logger;
@@ -60,11 +62,15 @@ export class Runtime {
         }
         return secretFromEnv(secretAccount(id));
     }
+    /** The GitHub token: environment, then the keychain, then the GitHub CLI. */
+    githubToken() {
+        return resolveGithubToken({ envName: this.config.github.tokenEnv, useGhCli: this.config.github.useGhCli, secrets: this.secrets });
+    }
     async syncGithubNow(store) {
         const settings = this.settings();
         if (!settings.githubEnabled)
             return;
-        const token = await resolveGithubToken(this.config.github.tokenEnv, this.config.github.useGhCli);
+        const token = await this.githubToken();
         if ('error' in token) {
             const report = { at: Date.now(), notifications: 0, opened: 0, closed: 0, wouldMarkRead: 0, markedRead: 0, checkFailures: 0, apiCalls: 0, error: token.error };
             store.set('github.lastSync', report);

package/lib/types/core/ask.d.ts

@@ -28,6 +28,7 @@ export type AskRequest = {
 } | {
     kind: 'mail-setup';
     preset: string;
+    error?: string;
 };
 export interface AskOptions {
     now: number;

package/lib/types/core/exec.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Running the few helper programs the secretary uses (`security`,
+ * `secret-tool`, PowerShell, `gh`).
+ *
+ * An app started from the Dock, the Start menu or a service manager often
+ * gets a short PATH that misses where package managers put programs, so a
+ * program installed with Homebrew, winget or `~/.local/bin` looks missing.
+ * `findProgram` looks on PATH first, then in those usual places.
+ */
+export interface RunResult {
+    code: number;
+    stdout: string;
+    stderr: string;
+    /** Node's own message when the program could not start or was killed. */
+    failure?: string;
+}
+interface Where {
+    platform?: NodeJS.Platform;
+    env?: NodeJS.ProcessEnv;
+    home?: string;
+}
+/** The usual install places of command-line programs, after PATH. */
+export declare function usualDirs({ platform, env, home }?: Where): string[];
+/** The full path of a program, or `undefined` when it is not installed anywhere we know of. */
+export declare function findProgram(name: string, where?: Where): string | undefined;
+/** Run a program; `input` goes to its stdin (secrets never go on the command line). Never rejects. */
+export declare function runProgram(file: string, args: string[], input?: string, timeout?: number): Promise<RunResult>;
+export {};

package/lib/types/core/github/client.d.ts

@@ -131,6 +131,8 @@ export declare class GitHubClient {
     user(): Promise<{
         login: string;
     }>;
+    /** Whether this token may read notifications (fine-grained tokens get 403). */
+    canReadNotifications(): Promise<boolean>;
     repo(fullName: string): Promise<RepoInfo>;
     pull(apiUrl: string): Promise<PullInfo>;
     issue(apiUrl: string): Promise<IssueInfo>;

package/lib/types/core/github/token.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Where the GitHub token comes from, in this order:
+ *
+ *   1. the environment variable named in the config (GITHUB_TOKEN)
+ *   2. a token you pasted on the settings page, kept in the system keychain
+ *   3. the GitHub CLI (`gh auth token`), which keeps its own in the keychain
+ *
+ * A token is never written to the notebook or a file.
+ */
+import { type Bi } from '../i18n.ts';
+import type { SecretStore } from '../secrets.ts';
+import { type FetchLike } from './client.ts';
+/** The keychain entry for a token pasted on the settings page. */
+export declare const GITHUB_SECRET = "github";
+/** Opens GitHub's "new classic token" page with the two scopes ticked. */
+export declare const NEW_TOKEN_URL = "https://github.com/settings/tokens/new?scopes=notifications,repo&description=DSH%20mishu";
+export type TokenSource = 'env' | 'keychain' | 'gh';
+export type TokenResult = {
+    token: string;
+    from: TokenSource;
+} | {
+    error: Bi;
+};
+/** `ghPath` is for tests: a fixed path, or `null` for "not installed". */
+export declare function resolveGithubToken(options: {
+    envName: string;
+    useGhCli: boolean;
+    secrets?: SecretStore;
+    ghPath?: string | null;
+}): Promise<TokenResult>;
+/**
+ * Check a pasted token with GitHub, then keep it in the keychain. It must
+ * read notifications, which only classic tokens with the `notifications`
+ * scope can (fine-grained tokens cannot reach that API).
+ */
+export declare function saveGithubToken(secrets: SecretStore, raw: string, fetch?: FetchLike): Promise<{
+    login: string;
+}>;
+export declare function deleteGithubToken(secrets: SecretStore): Promise<void>;

package/lib/types/core/index.d.ts

@@ -2,7 +2,6 @@
  * mishu core — everything that does not depend on DSH.
  * Nothing under `src/core` may import DSH; `tests/boundary.test.ts` enforces it.
  */
-import { type Bi } from './i18n.ts';
 export { buildAsk, detailText, type AskRequest } from './ask.ts';
 export { buildBoard, buildDetail, type BoardCard, type BoardData, type CardAction, type DoneGroup, type MatterDetail } from './board.ts';
 export type { CardExplain } from './explain.ts';
@@ -11,6 +10,7 @@ export { GitHubClient, GitHubError, type FetchLike, type Notification } from './
 export { gatherFacts, Lookups, parseCheckSuiteTitle, type Facts } from './github/facts.ts';
 export { CLOSING_REASONS, judge, type Explain, type Verdict } from './github/rules.ts';
 export { syncGithub, type GithubSyncReport, type MarkReadMode } from './github/sync.ts';
+export { deleteGithubToken, GITHUB_SECRET, NEW_TOKEN_URL, resolveGithubToken, saveGithubToken, type TokenResult, type TokenSource } from './github/token.ts';
 export { bi, decode, detectLang, errorText, LANGS, MishuError, pick, type Bi, type Lang } from './i18n.ts';
 export { addSeries, describeActiveSeries, describeSeries, resolveSeries, stopSeries, tickManual, upcoming, type ResolvedSeries, type SeriesInput, } from './manual.ts';
 export { DEFAULT_DEMOTION, isActive, isDemoted, setStatusByUser, snoozeByUser, type DemotionPolicy } from './matters.ts';
@@ -21,7 +21,9 @@ export { MAIL_PRESETS, presetById, secretAccount, type MailAccount, type MailFet
 export { ImapFetcher } from './mail/imap.ts';
 export { judgeMail } from './mail/rules.ts';
 export { describeMailError, MAIL_SOURCE, mailReportKey, syncMail, type MailSyncReport } from './mail/sync.ts';
-export { MemorySecrets, secretEnvName, secretFromEnv, systemSecrets, type SecretStore } from './secrets.ts';
+export { findProgram } from './exec.ts';
+export { restartPlan, scheduleRestart, type RestartPlan } from './restart.ts';
+export { MemorySecrets, secretEnvName, secretFromEnv, systemSecrets, type SecretStatus, type SecretStore } from './secrets.ts';
 export { deleteMailAccount, effectiveSettings, mailAccounts, saveMailAccount, saveSettings, type Defaults, type UserSettings } from './settings.ts';
 export declare const DEFAULT_HOME = "~/.mishu";
 /** `~` and `~/…` expand to the home directory on every platform. */
@@ -30,13 +32,3 @@ export declare function mishuPaths(home: string): {
     root: string;
     db: string;
 };
-/**
- * A GitHub token without storing one: the named environment variable, else
- * the GitHub CLI (`gh auth token`, which reads the system credential store).
- */
-export declare function resolveGithubToken(envName: string, useGhCli: boolean): Promise<{
-    token: string;
-    from: 'env' | 'gh';
-} | {
-    error: Bi;
-}>;

package/lib/types/core/mail/sync.d.ts

@@ -8,7 +8,7 @@
  */
 import { type Bi } from '../i18n.ts';
 import type { MishuStore } from '../store.ts';
-import type { MailAccount, MailFetcher } from './account.ts';
+import { type MailAccount, type MailFetcher } from './account.ts';
 export declare const MAIL_SOURCE = "mail";
 export interface MailSyncReport {
     at: number;
@@ -19,7 +19,7 @@ export interface MailSyncReport {
     error?: Bi;
 }
 /** A connection or login failure, said so a person knows what to fix. */
-export declare function describeMailError(error: unknown, account: Pick<MailAccount, 'host' | 'port'>): Bi;
+export declare function describeMailError(error: unknown, account: Pick<MailAccount, 'host' | 'port' | 'preset'>): Bi;
 export declare function mailReportKey(accountId: number): string;
 export declare function syncMail(options: {
     store: MishuStore;