cotutor 0.3.0 → 0.4.1

package/dist/app/cli/tray.d.ts

@@ -0,0 +1,236 @@
+/**
+ * 托盘图标(macOS 菜单栏、Windows 任务栏;Linux 没做,GNOME 缺省不显示托盘):家长不开终端也看得到服务好不好、点得开家长端。
+ * 三层:
+ *   node 进程(cotutor tray run,tray-run.ts 是它的轻入口):隔几秒问每个后台服务的 /api/health,判断状态,决定显示什么、要不要通知;这里全是能测的 TS。
+ *   显示脚本(tray-mac.ts 的 JXA、tray-windows.ts 的 PowerShell,都是系统自带、不用签名):只管画和回报点击,不判断。
+ *   登录项:macOS 一个 LaunchAgent,Windows 一条 Run 项 + wscript 隐藏启动器;service install 时一起装(--no-tray 不装,cotutor tray off 关掉并记住)。
+ * 为什么不放在 serve 里:服务挂了图标也没了,就说不出「没在跑」;多个孩子时一台电脑也只该有一个图标。
+ * 为什么不用 npm 的托盘库、Electron:见 docs/wip;systray2 只有 x86 的 Mac 二进制且没签名,Electron 要多下一百多 MB。
+ * 状态:正常只有 logo(和菜单栏别的图标一样单色);有事才出状态点,橙 = 要处理,红 = 没在跑(logo 同时变淡)。正常 → 有事、→ 没在跑时通知一次,恢复不通知。
+ * 「退出 cotutor」= 停掉所有后台服务并退出图标,下次登录自己回来;正开着电话时先问一声。
+ */
+import { type SpawnOptions } from 'node:child_process';
+import { type Health, type InstalledService, type ServiceHost } from './service.ts';
+import { HELPER_NO_SESSION, TRAY_AUMID, TRAY_LABEL, TRAY_RUN_VALUE } from './tray-ids.ts';
+export { HELPER_NO_SESSION, TRAY_AUMID, TRAY_LABEL, TRAY_RUN_VALUE };
+/** 多久问一次 */
+export declare const TRAY_POLL_MS = 5000;
+/** 连着几次问不到才算没在跑:重起一下、网络抖一下不报 */
+export declare const TRAY_STRIKES = 2;
+/** 图标刚起来时服务可能还没起来:这么久里问不到算「正在启动」(Windows 登录后约一分钟才跑 Run 项) */
+export declare const TRAY_START_GRACE_MS = 90000;
+/** 点了启动、重启以后等多久 */
+export declare const TRAY_RESTART_GRACE_MS = 30000;
+/** 两次问之间隔太久 = 刚睡醒:网络还没回来,先别报 */
+export declare const TRAY_WAKE_GAP_MS = 30000;
+export declare const TRAY_WAKE_GRACE_MS = 30000;
+export type TrayLevel = 'ok' | 'warn' | 'bad';
+export type RowLevel = TrayLevel | 'starting';
+export type TrayFix = {
+    kind: 'open';
+    target: string;
+} | {
+    kind: 'restart';
+};
+/** 一个服务这一轮问到的 */
+export interface TrayProbe {
+    name: string;
+    kid: string;
+    root: string;
+    logDir: string | null;
+    port: number;
+    health: Health | null;
+    /** 问不到时端口被谁占着(「nginx」);不知道 → null */
+    holder: string | null;
+}
+/** 一个服务现在的样子 */
+export interface TrayRow {
+    name: string;
+    kid: string;
+    logDir: string | null;
+    level: RowLevel;
+    /** 家长端地址;服务没答应 → null */
+    url: string | null;
+    /** 第二行小字 */
+    detail: string;
+    /** 有几件事要处理 */
+    issues: number;
+    fix: TrayFix | null;
+    calls: number;
+    /** npm 上有比装的新的版本 → 版本号;不算有事,不出状态点 */
+    update: string | null;
+}
+export type TrayEntry = {
+    kind: 'info';
+    title: string;
+    level?: TrayLevel;
+} | {
+    kind: 'sub';
+    title: string;
+} | {
+    kind: 'sep';
+} | {
+    kind: 'action';
+    id: string;
+    title: string;
+    primary?: boolean;
+};
+export interface TrayShow {
+    type: 'show';
+    icon: TrayLevel;
+    tip: string;
+    menu: TrayEntry[];
+}
+export interface TrayNote {
+    type: 'notify';
+    title: string;
+    body: string;
+}
+/** 跑了多久,给家长看 */
+export declare function uptimeText(startedMs: number, now: number): string;
+/** 服务在跑,但有事要家长处理:先后就是轻重,菜单上只说第一件 */
+export declare function issuesOf(p: TrayProbe, o: {
+    platform: NodeJS.Platform;
+    version: string;
+}): {
+    text: string;
+    fix: TrayFix;
+}[];
+/** 记着每个服务上一轮的样子,算这一轮的样子和要不要通知;不碰任何系统,测试直接喂 */
+export declare class TrayModel {
+    private readonly mem;
+    private last;
+    private readonly o;
+    constructor(o: {
+        platform: NodeJS.Platform;
+        version: () => string;
+    });
+    /** 刚点了启动、重启:这一阵问不到是正常的 */
+    expect(name: string, now: number): void;
+    update(probes: TrayProbe[], now: number): {
+        rows: TrayRow[];
+        notes: TrayNote[];
+    };
+    private healthy;
+    private placeholder;
+}
+/** 有新版本的通知:每个版本最多一次,记在托盘目录,重起、重新登录不再弹 */
+export declare function updateNote(version: string, platform: NodeJS.Platform): TrayNote;
+/** 这一轮显示什么 */
+export declare function trayShow(rows: TrayRow[]): TrayShow;
+export interface HelperMessage {
+    type: string;
+    id?: string;
+    yes?: boolean;
+    message?: string;
+}
+export interface TrayHelper {
+    send(m: unknown): void;
+    /** 关 stdin:显示脚本读到头自己退 */
+    close(): void;
+}
+export interface TrayDeps {
+    platform: NodeJS.Platform;
+    /** 现在装的是哪个版本:每轮问,程序可能刚被 npm 换了 */
+    version(): string;
+    /** 已经通知过的新版本 */
+    updateSeen(): string | null;
+    setUpdateSeen(version: string): void;
+    now(): number;
+    list(): Promise<InstalledService[]>;
+    /** 读 cotutor.json:孩子叫什么、哪个端口 */
+    inspect(s: InstalledService): Promise<{
+        kid: string;
+        port: number;
+    }>;
+    probe(port: number): Promise<Health | null>;
+    holder(port: number): Promise<string | null>;
+    control(root: string, what: 'start' | 'stop' | 'restart'): Promise<unknown>;
+    open(target: string): void;
+    spawnHelper(on: {
+        message(m: HelperMessage): void;
+        exit(code: number | null): void;
+    }): TrayHelper;
+    note(text: string): void;
+    pollMs?: number;
+    helperRestartMs?: number;
+}
+export declare const QUIT_CONFIRM: {
+    id: string;
+    title: string;
+    body: string;
+    yes: string;
+    no: string;
+};
+/** 主循环:问状态、发给显示脚本、接点击;都退了才返回退出码。0 = 不用再起(点了退出、没有服务了、没有桌面) */
+export declare function runTray(d: TrayDeps): Promise<number>;
+export declare const traySupported: (platform: NodeJS.Platform) => boolean;
+type HostPaths = Pick<ServiceHost, 'platform' | 'home' | 'env'>;
+/** 显示脚本、图标、日志放哪 */
+export declare function trayDir(host: HostPaths): string;
+/** 写显示脚本(每次起来都写,升级后马上生效)和图标(版本变了才画,画一次要几百毫秒) */
+export declare function writeTrayFiles(platform: NodeJS.Platform, dir: string): Promise<string>;
+/** 起显示脚本 */
+export declare function spawnTrayHelper(platform: NodeJS.Platform, file: string, dir: string, note: (t: string) => void, on: {
+    message(m: HelperMessage): void;
+    exit(code: number | null): void;
+}): TrayHelper;
+/**
+ * 打开地址或目录用什么命令。windowsHide 不弹黑窗口。
+ * detached 不能省:Windows 上非 detached 的子进程在「父进程退出就杀」的 job 里(libuv),cotutor open、service install 起完马上退,cmd 还没把地址交给浏览器就被一起杀了。
+ * 退出码是 0、地址也打印了,就是没打开,也不报错(2026-11-07 真机);托盘进程一直开着,所以光点图标看不出来。
+ */
+export declare function openCommand(platform: NodeJS.Platform, target: string): {
+    cmd: string;
+    args: string[];
+    options: SpawnOptions;
+};
+export declare function openTarget(platform: NodeJS.Platform, target: string): void;
+/** 日志:一个文件,过 1 MB 换一次,只留上一份 */
+export declare function trayNote(dir: string): (text: string) => void;
+/** 孩子叫什么、哪个端口:只读这两样,不加载 zod(托盘进程常驻,要轻);读不了就用服务名和缺省端口 */
+export declare function inspectService(s: InstalledService): Promise<{
+    kid: string;
+    port: number;
+}>;
+/** 真的依赖,给 runTray */
+export declare function realTrayDeps(host: ServiceHost, dir: string, file: string, version: () => string): TrayDeps;
+/** 登录项跑的命令 */
+export declare const trayArgs: (host: HostPaths, o?: {
+    node?: string;
+    bin?: string;
+}) => string[];
+/** macOS 的 LaunchAgent:登录就起,崩了拉起,以 0 退(点了退出)不拉 */
+export declare function trayPlist(args: string[], dir: string, path: string): string;
+/** 装上并起来;已经装过就照现在的 node、bin 重写一遍再起(升级后新代码才生效)。started = false:登录项写好了,这个会话里起不来,下次登录出现 */
+export declare function installTray(host: ServiceHost, o?: {
+    node?: string;
+    bin?: string;
+}): Promise<{
+    file: string;
+    started: boolean;
+}>;
+/** 卸掉:停下、删登录项。remember = 家长说不要(以后 service install 也不再装) */
+export declare function removeTray(host: ServiceHost, o?: {
+    remember?: boolean;
+}): Promise<boolean>;
+export interface TrayStatus {
+    supported: boolean;
+    installed: boolean;
+    running: boolean;
+    pid: number | null;
+    /** 家长关掉过(cotutor tray off) */
+    off: boolean;
+    /** Windows:下次登录还会不会起来;别的系统 null */
+    autostart: boolean | null;
+}
+export declare function trayStatus(host: ServiceHost): Promise<TrayStatus>;
+/** service install 时跟着装:没做的系统、家长关掉过都跳过;返回给人看的结果 */
+export declare function ensureTray(host: ServiceHost, o?: {
+    node?: string;
+    bin?: string;
+}): Promise<'unsupported' | 'off' | 'started' | 'later'>;
+/** service restart 时:图标进程也换上新代码(升级后跑的就是这条)。没开图标的不动,不能把 --no-tray 的装回来 */
+export declare function refreshTray(host: ServiceHost): Promise<boolean>;
+/** 服务卸完了:图标也撤(不算家长说不要,以后再装服务还会带上) */
+export declare function dropTrayIfNoServices(host: ServiceHost): Promise<boolean>;