dsh-mishu 0.5.4 → 0.6.2

package/lib/dsh/config.js

@@ -1,5 +1,5 @@
 import Schema from '@deepseek-ai/schemastery';
-import { CLOSING_REASONS, DEFAULT_HOME, DEFAULT_LEAD_DAYS } from "../core/index.js";
+import { CLOSING_REASONS, DEFAULT_HOME, GITHUB_CLIENT_ID, DEFAULT_LEAD_DAYS } from "../core/index.js";
 export const Config = Schema.object({
     home: Schema.string().default(DEFAULT_HOME).description('Notebook directory (mishu.db)'),
     language: Schema.union(['auto', 'zh', 'en']).default('auto').description('Language: auto (system locale), zh (中文) or en (English)'),
@@ -8,6 +8,7 @@ export const Config = Schema.object({
         intervalMinutes: Schema.natural().min(5).default(15).description('Minutes between GitHub syncs'),
         tokenEnv: Schema.string().default('GITHUB_TOKEN').description('Environment variable with a GitHub token'),
         useGhCli: Schema.boolean().default(true).description('Fall back to `gh auth token`'),
+        clientId: Schema.string().default(GITHUB_CLIENT_ID).description('GitHub OAuth App client id for "Sign in with GitHub" (device flow)'),
         markRead: Schema.union(['off', 'shadow', 'on']).default('shadow').description('Mark resolved notifications read on GitHub: off / shadow (only record) / on'),
         markReadReasons: Schema.array(Schema.union([...CLOSING_REASONS])).default(['merged', 'closed', 'recovered', 'superseded', 'ref-gone'])
             .description('Closing reasons allowed to mark read'),

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, restartPlan, scheduleRestart, } from "../core/index.js";
+import { dayOf, detectLang, effectiveSettings, GitHubClient, ImapFetcher, mailAccounts, mailReportKey, renderBrief, FileSecrets, GithubDeviceLogin, KeychainOrFile, mishuPaths, resolveGithubToken, secretAccount, secretFromEnv, syncGithub, syncMail, systemSecrets, tickManual, bi, restartPlan, scheduleRestart, } from "../core/index.js";
 export class Runtime {
     store;
     config;
@@ -12,12 +12,15 @@ export class Runtime {
     fetcher;
     logger;
     syncing;
+    /** "Sign in with GitHub" in progress, if any; tests swap it to replay GitHub. */
+    githubLogin;
     /** How DSH restarts; tests swap it so they never restart anything. */
-    restarter = { plan: () => restartPlan(), schedule: scheduleRestart };
-    constructor(config, logger, secrets = systemSecrets(), fetcher = new ImapFetcher()) {
+    restarter = { plan: () => restartPlan(), schedule: plan => scheduleRestart(plan) };
+    constructor(config, logger, secrets = new KeychainOrFile(systemSecrets(), new FileSecrets(mishuPaths(config.home).secrets)), fetcher = new ImapFetcher()) {
         this.config = config;
         this.logger = logger;
         this.secrets = secrets;
+        this.githubLogin = new GithubDeviceLogin({ clientId: config.github.clientId, secrets });
         this.fetcher = fetcher;
     }
     defaults() {
@@ -92,7 +95,7 @@ export class Runtime {
         if (password === undefined) {
             const report = {
                 at: Date.now(), account: account.id, messages: 0, opened: 0, closed: 0,
-                error: bi('没有找到这个邮箱的密码（授权码）。到设置页重新填一次。', 'No password (app password) found for this account. Enter it again on the settings page.'),
+                error: bi('没有找到这个邮箱的密码（授权码）。在设置页点这个邮箱的「编辑」，重新填一次。', 'No password (app password) found for this account. On the settings page, click Edit on this account and enter it again.'),
             };
             store.set(mailReportKey(account.id), report);
             return report;

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

@@ -0,0 +1,64 @@
+/**
+ * "Sign in with GitHub" without pasting a token: GitHub's device flow.
+ *
+ * The secretary asks GitHub for a short code, you enter it at
+ * github.com/login/device (on any computer) and approve, and the secretary
+ * receives a token, checks it like a pasted one and keeps it in the
+ * keychain (or the secrets file). It needs the client id of a GitHub OAuth
+ * App with device flow enabled; the id is public, there is no secret.
+ *
+ * https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/authorizing-oauth-apps#device-flow
+ */
+import { type Bi } from '../i18n.ts';
+import type { SecretStore } from '../secrets.ts';
+import type { FetchLike } from './client.ts';
+/** Notifications, and repo so CI runs, pull requests and issues of private repositories can be looked up. */
+export declare const DEVICE_SCOPES = "notifications repo";
+export type DeviceState = {
+    state: 'idle';
+} | {
+    state: 'waiting';
+    userCode: string;
+    verificationUri: string;
+    expiresAt: number;
+} | {
+    state: 'done';
+    login: string;
+} | {
+    state: 'failed';
+    message: Bi;
+};
+/** `fetch` with a form body, which the device flow endpoints take. */
+export type PostLike = (url: string, init: {
+    method: 'POST';
+    headers: Record<string, string>;
+    body: string;
+}) => Promise<{
+    status: number;
+    text(): Promise<string>;
+}>;
+interface Options {
+    clientId: string;
+    secrets: SecretStore;
+    post?: PostLike;
+    /** For checking the token once it arrives; tests replay GitHub. */
+    fetch?: FetchLike;
+    sleep?: (ms: number) => Promise<void>;
+    now?: () => number;
+}
+export declare class GithubDeviceLogin {
+    private readonly options;
+    private current;
+    /** Bumped by every start and cancel, so an older poll loop stops quietly. */
+    private generation;
+    constructor(options: Options);
+    status(): DeviceState;
+    cancel(): void;
+    /** Ask GitHub for a code; polling for your approval runs in the background. */
+    start(): Promise<DeviceState>;
+    private poll;
+    private form;
+    private now;
+    private sleep;
+}
+export {};

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

@@ -12,6 +12,8 @@ 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";
+/** The OAuth App behind "Sign in with GitHub" (device flow, "DSH 小秘书"); public, not a secret. */
+export declare const GITHUB_CLIENT_ID = "Ov23liejlNOyARQKgy5x";
 /** 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';

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

@@ -10,20 +10,21 @@ 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 { DEVICE_SCOPES, GithubDeviceLogin, type DeviceState } from './github/device.ts';
+export { deleteGithubToken, GITHUB_CLIENT_ID, 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';
 export { CATEGORIES, CATEGORY_LABELS, DEFAULT_LEAD_DAYS, REPEATS, type Category, type Repeat } from './recur.ts';
 export { MishuStore, type Matter, type MatterStatus, type Series } from './store.ts';
 export { addDays, dayOf, formatMoment } from './time.ts';
-export { MAIL_PRESETS, presetById, secretAccount, type MailAccount, type MailFetcher, type MailMessage, type MailPreset } from './mail/account.ts';
+export { MAIL_PRESETS, normalizePassword, presetById, presetForAddress, providerMismatch, secretAccount, type MailAccount, type MailFetcher, type MailMessage, type MailPreset } from './mail/account.ts';
 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 { 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 { restartPlan, scheduleRestart, type RestartPlan, type RestartStarted } from './restart.ts';
+export { FileSecrets, KeychainOrFile, 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. */
@@ -31,4 +32,5 @@ export declare function expandHome(path: string): string;
 export declare function mishuPaths(home: string): {
     root: string;
     db: string;
+    secrets: string;
 };

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

@@ -6,6 +6,14 @@
  * system keychain under `mail:<id>`, never in the notebook.
  */
 import { type Bi } from '../i18n.ts';
+/** One step of getting a provider's app password, with the page it happens on. */
+export interface MailStep {
+    text: Bi;
+    link?: {
+        url: string;
+        label: Bi;
+    };
+}
 export interface MailPreset {
     id: string;
     label: Bi;
@@ -14,12 +22,28 @@ export interface MailPreset {
     secure: boolean;
     /** False when the provider no longer allows password logins over IMAP. */
     supported: boolean;
-    /** Where to get the password this provider expects. */
+    /** Numbered steps to the password this provider expects, each with its page to open. */
+    steps: MailStep[];
+    /** The same as one paragraph, for error messages and "+AI"; a short note where there are no steps. */
     howTo: Bi;
+    /** Address domains that belong to this provider, for picking it from the address. */
+    domains: string[];
+    /** Length of the app password or code, when the provider fixes it (spaces aside). */
+    passwordLength?: number;
     /** A web link that finds one message by Message-ID, when the provider has one. */
     findMessage?: (messageId: string) => string;
 }
 export declare const MAIL_PRESETS: readonly MailPreset[];
+/** The provider an address belongs to, from its domain; `undefined` when we do not know it. */
+export declare function presetForAddress(address: string): MailPreset | undefined;
+/**
+ * The password as the server wants it. App passwords and codes are shown in
+ * groups ("abcd efgh ijkl mnop") and copied with the spaces; they never
+ * contain one, so spaces go when the provider fixes the length.
+ */
+export declare function normalizePassword(presetId: string, password: string): string;
+/** An account whose address belongs to another provider than its server ("…@gmail.com" on imap.qq.com). */
+export declare function providerMismatch(account: Pick<MailAccount, 'address' | 'preset' | 'host'>): Bi | undefined;
 export declare function presetById(id: string): MailPreset;
 export interface MailAccount {
     id: number;

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

@@ -18,8 +18,14 @@ export interface MailSyncReport {
     closed: number;
     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' | 'preset'>): Bi;
+/**
+ * A connection or login failure, said so a person knows what to fix. With
+ * `steps` (the default) a login failure also repeats where the provider's
+ * app password comes from; the add-account dialog shows those steps already.
+ */
+export declare function describeMailError(error: unknown, account: Pick<MailAccount, 'host' | 'port' | 'preset'>, options?: {
+    steps?: boolean;
+}): Bi;
 export declare function mailReportKey(accountId: number): string;
 export declare function syncMail(options: {
     store: MishuStore;

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

@@ -15,6 +15,11 @@
  *   Windows  `taskkill /PID` without /F (a close request), then the app again
  *   Linux    SIGTERM to the app, then the app again
  *
+ * On a server set up with dsh-vps, DSH is a child of the dsh-gate login
+ * gateway (`$GATE_HOME/gate/server.js`, run by systemd), which starts DSH
+ * again whenever it exits and picks up the new sign-in token itself. There
+ * a restart is simply DSH exiting cleanly; the page reconnects.
+ *
  * 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.
@@ -29,10 +34,17 @@ export type RestartPlan = {
     platform: 'win32' | 'linux';
     exe: string;
     appPid: number;
+} | {
+    kind: 'gate';
+    gate: string;
 } | {
     kind: 'none';
     why: Bi;
 };
+/** Plans carried out by the detached helper (the desktop app quits and reopens). */
+export type AppRestartPlan = Extract<RestartPlan, {
+    kind: 'macos-app' | 'desktop-app';
+}>;
 export interface ProcessFacts {
     env: NodeJS.ProcessEnv;
     platform: NodeJS.Platform;
@@ -43,6 +55,8 @@ export interface ProcessFacts {
     parentExe: string | undefined;
     /** macOS: CFBundleIdentifier from the Info.plist of the .app holding `execPath`. */
     bundleId: string | undefined;
+    /** Linux: the parent's command line, to recognise the dsh-gate supervisor. */
+    parentArgs: string[] | undefined;
 }
 /** How DSH can be restarted from here, or why it cannot. */
 export declare function restartPlan(facts?: ProcessFacts): RestartPlan;
@@ -62,12 +76,13 @@ export interface MacTools {
  * 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 declare function restartHelperSource(plan: Exclude<RestartPlan, {
-    kind: 'none';
-}>, log: string, tools?: MacTools): string;
-/** Start the helper and return where it logs. Runs with this process's Node (Electron as Node in the app). */
+export declare function restartHelperSource(plan: AppRestartPlan, log: string, tools?: MacTools): string;
+/** What the page is told: where the helper logs, or that it should wait and reconnect. */
+export interface RestartStarted {
+    log?: string;
+    reconnect?: boolean;
+}
+/** Start the restart: under dsh-gate, exit; in the desktop app, start the helper and say where it logs. Runs with this process's Node (Electron as Node in the app). */
 export declare function scheduleRestart(plan: Exclude<RestartPlan, {
     kind: 'none';
-}>): {
-    log: string;
-};
+}>, exit?: () => void): RestartStarted;

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

@@ -7,21 +7,34 @@
  *
  * Secrets travel to the helper on stdin only, never as command-line
  * arguments, which other processes on the machine could read. Everything is
- * stored under the service name "dsh-mishu". When no keychain is available,
- * `secretFromEnv` is the documented fallback.
+ * stored under the service name "dsh-mishu".
+ *
+ * A computer without a usable keychain (a Linux server with no desktop,
+ * say) keeps them in `secrets.json` in the notebook directory instead:
+ * mode 600, so only your own system account can read it. That is how gh,
+ * git and Thunderbird manage on such machines, and it is said plainly on
+ * the settings page: protected by file permissions, not encrypted.
+ * `secretFromEnv` remains a last resort.
  */
 import { type Bi } from './i18n.ts';
 export declare const SERVICE = "dsh-mishu";
-/** Whether secrets can be kept here, and if not, why and what to do. */
+/**
+ * Whether secrets can be kept here, and if not, why and what to do. `file`
+ * says they go to a file because the keychain could not be used.
+ */
 export type SecretStatus = {
     available: true;
+    file?: {
+        path: string;
+        why: Bi;
+    };
 } | {
     available: false;
     why: Bi;
 };
 export interface SecretStore {
     /** Where secrets go, for the settings page ("macOS 钥匙串"). */
-    readonly kind: 'macos' | 'windows' | 'linux' | 'memory';
+    readonly kind: 'macos' | 'windows' | 'linux' | 'file' | 'memory';
     status(): Promise<SecretStatus>;
     get(account: string): Promise<string | undefined>;
     set(account: string, secret: string): Promise<void>;
@@ -43,3 +56,36 @@ export declare function systemSecrets(platform?: NodeJS.Platform): SecretStore;
 /** Fallback when no keychain is available: `DSH_MISHU_SECRET_MAIL_3` for account "mail:3". */
 export declare function secretEnvName(account: string): string;
 export declare function secretFromEnv(account: string): string | undefined;
+/**
+ * Secrets in one JSON file, readable by your system account only (600).
+ * Written to a temporary file first and renamed, so a crash never leaves
+ * half a file; a file that cannot be read is never overwritten.
+ */
+export declare class FileSecrets implements SecretStore {
+    readonly kind: "file";
+    readonly path: string;
+    constructor(path: string);
+    status(): Promise<SecretStatus>;
+    private read;
+    private write;
+    get(account: string): Promise<string | undefined>;
+    set(account: string, secret: string): Promise<void>;
+    delete(account: string): Promise<void>;
+}
+/**
+ * The keychain when it works, else the file. Reads look in both, so a
+ * secret saved to the file before a keychain was set up is still found;
+ * saving to the keychain removes the file's copy.
+ */
+export declare class KeychainOrFile implements SecretStore {
+    private readonly keychain;
+    private readonly file;
+    private usable;
+    constructor(keychain: SecretStore, file: FileSecrets);
+    get kind(): "linux" | "macos" | "windows" | "file" | "memory";
+    private keychainStatus;
+    status(): Promise<SecretStatus>;
+    get(account: string): Promise<string | undefined>;
+    set(account: string, secret: string): Promise<void>;
+    delete(account: string): Promise<void>;
+}

package/lib/types/dsh/config.d.ts

@@ -12,6 +12,8 @@ export interface MishuConfig {
         tokenEnv: string;
         /** Fall back to `gh auth token` (the GitHub CLI's keychain entry). */
         useGhCli: boolean;
+        /** Client id of the GitHub OAuth App used by "Sign in with GitHub"; empty hides the button. */
+        clientId: string;
         /** off: never touch GitHub; shadow: record what would be marked read; on: mark it. */
         markRead: MarkReadMode;
         /** Which closing reasons may mark read when `markRead` is on. */

package/lib/types/dsh/runtime.d.ts

@@ -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 { type Defaults, type Lang, type MailAccount, type MailFetcher, type MailSyncReport, type MishuStore, type RestartPlan, type SecretStore, type TokenResult } from '../core/index.ts';
+import { GithubDeviceLogin, type Defaults, type Lang, type MailAccount, type MailFetcher, type MailSyncReport, type MishuStore, type RestartPlan, type RestartStarted, type SecretStore, type TokenResult } from '../core/index.ts';
 import type { MishuConfig } from './config.ts';
 interface Logger {
     info(message: string): void;
@@ -17,14 +17,14 @@ export declare class Runtime {
     readonly fetcher: MailFetcher;
     private readonly logger;
     private syncing;
+    /** "Sign in with GitHub" in progress, if any; tests swap it to replay GitHub. */
+    githubLogin: GithubDeviceLogin;
     /** How DSH restarts; tests swap it so they never restart anything. */
     restarter: {
         plan(): RestartPlan;
         schedule(plan: Exclude<RestartPlan, {
             kind: 'none';
-        }>): {
-            log: string;
-        };
+        }>): RestartStarted;
     };
     constructor(config: MishuConfig, logger: Logger, secrets?: SecretStore, fetcher?: MailFetcher);
     defaults(): Defaults;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-mishu",
-  "version": "0.5.4",
+  "version": "0.6.2",
   "description": "DSH secretary (小秘书) for DeepSeek Harness (dsh): watches GitHub notifications and the dated things you tell it (bills, renewals, documents, birthdays), closes what is already resolved, and keeps a short list of what actually needs you. Bilingual (中文 / English), macOS / Windows / Linux. · DSH 小秘书：提醒、通知、待办、消息、收件箱、秘书。GitHub 通知按当前状态分诊，交代一句就记下到期和周期事项。",
   "type": "module",
   "main": "lib/index.js",