cotutor 0.2.0 → 0.4.0

package/dist/app/cli/serve-log.d.ts

@@ -0,0 +1,13 @@
+export declare const LOG_KEEP_DAYS = 14;
+/** 删 keepDays 天以前的(按文件名的日期,不看修改时间);返回删了哪些 */
+export declare function pruneLogs(dir: string, now: Date, keepDays?: number): string[];
+/** 今天写的是哪个文件 */
+export declare const logFileFor: (dir: string, now: Date) => string;
+/**
+ * 把 process.stdout / stderr 改写进按天的文件(不再写到原来的地方,免得 launchd.log 里再有一份);返回撤掉的函数(测试用)。
+ * 一行开头加「时:分:秒 」;一次写进来的不一定是整行,接着上一次的不再加
+ */
+export declare function teeLogs(dir: string, opts?: {
+    now?: () => Date;
+    keepDays?: number;
+}): () => void;

package/dist/app/cli/serve-log.js

@@ -0,0 +1,90 @@
+/**
+ * 后台服务的日志(cotutor serve --log-dir <目录>,cotutor service 装的就带它):stdout / stderr 改写进 <目录>/<日期>.log,一天一个,每行带时分秒;
+ * 留 LOG_KEEP_DAYS 天,起来时、换天时删更早的。一跑几个星期,不按天切就一个文件越长越大(launchd、systemd 都不替你切)。
+ * 起来之前的输出(node 自己报的、模块没加载上)还是走原来的 stdout / stderr:macOS 是 launchd 接着的 <目录>/launchd.log,Linux 是 journal。
+ */
+import { closeSync, mkdirSync, openSync, readdirSync, rmSync, writeSync } from 'node:fs';
+import { join } from 'node:path';
+import { localDate } from "../../shared/time.js";
+export const LOG_KEEP_DAYS = 14;
+const LOG_RE = /^(\d{4}-\d{2}-\d{2})\.log$/;
+/** 删 keepDays 天以前的(按文件名的日期,不看修改时间);返回删了哪些 */
+export function pruneLogs(dir, now, keepDays = LOG_KEEP_DAYS) {
+    const oldest = localDate(new Date(now.getTime() - (keepDays - 1) * 86_400_000));
+    const gone = [];
+    let names = [];
+    try {
+        names = readdirSync(dir);
+    }
+    catch {
+        return gone;
+    }
+    for (const f of names) {
+        const m = LOG_RE.exec(f);
+        if (m && m[1] < oldest) {
+            rmSync(join(dir, f), { force: true });
+            gone.push(f);
+        }
+    }
+    return gone;
+}
+/** 今天写的是哪个文件 */
+export const logFileFor = (dir, now) => join(dir, `${localDate(now)}.log`);
+/**
+ * 把 process.stdout / stderr 改写进按天的文件(不再写到原来的地方,免得 launchd.log 里再有一份);返回撤掉的函数(测试用)。
+ * 一行开头加「时:分:秒 」;一次写进来的不一定是整行,接着上一次的不再加
+ */
+export function teeLogs(dir, opts = {}) {
+    const now = opts.now ?? (() => new Date());
+    mkdirSync(dir, { recursive: true });
+    let day = '';
+    let fd = null;
+    let atLineStart = true;
+    const open = (d) => {
+        const today = localDate(d);
+        if (fd !== null && today === day)
+            return fd;
+        if (fd !== null)
+            closeSync(fd);
+        day = today;
+        fd = openSync(logFileFor(dir, d), 'a');
+        pruneLogs(dir, d, opts.keepDays);
+        return fd;
+    };
+    const write = (chunk, encoding) => {
+        const text = typeof chunk === 'string' ? chunk : Buffer.isBuffer(chunk) || chunk instanceof Uint8Array ? Buffer.from(chunk).toString(typeof encoding === 'string' ? encoding : 'utf8') : String(chunk);
+        if (!text)
+            return;
+        const d = now();
+        const stamp = `${[d.getHours(), d.getMinutes(), d.getSeconds()].map((n) => String(n).padStart(2, '0')).join(':')} `;
+        let out = '';
+        for (const part of text.split(/(?<=\n)/)) {
+            out += (atLineStart ? stamp : '') + part;
+            atLineStart = part.endsWith('\n');
+        }
+        try {
+            writeSync(open(d), out);
+        }
+        catch { /* 写不了日志不能把服务带倒 */ }
+    };
+    const wrap = (stream) => {
+        const original = stream.write;
+        stream.write = ((chunk, encoding, cb) => {
+            write(chunk, encoding);
+            const done = typeof encoding === 'function' ? encoding : cb;
+            if (typeof done === 'function')
+                queueMicrotask(() => done());
+            return true;
+        });
+        return () => { stream.write = original; };
+    };
+    const undo = [wrap(process.stdout), wrap(process.stderr)];
+    open(now());
+    return () => {
+        for (const u of undo)
+            u();
+        if (fd !== null)
+            closeSync(fd);
+        fd = null;
+    };
+}

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

@@ -0,0 +1,51 @@
+import { type Server } from 'node:http';
+import { siteUrl } from '../../shared/site-url.ts';
+import type { ListenInfo } from '../../ui/parent/qr-page.ts';
+import { type AppContext } from '../http/app.ts';
+import { type ResolveOptions, type Workspace } from '../workspace.ts';
+export { siteUrl };
+export interface ServeOptions extends ResolveOptions {
+    workspace?: string;
+    port?: number;
+    host?: string;
+    /** 强制走 HTTP(哪怕证书在) */
+    http?: boolean;
+    /** 有事时拦着睡眠;缺省开 */
+    awake?: boolean;
+}
+export interface ServeResult {
+    server: Server;
+    ctx: AppContext;
+    ws: Workspace;
+    port: number;
+    https: boolean;
+    /** 本机名与局域网 IPv4 各一条 */
+    urls: string[];
+    /** 家长端首页:在这台电脑上打开的那条(localhost,证书里签了);serve 只打印它,扫码在它里面 */
+    parentPage: string;
+    warnings: string[];
+}
+/** 证书路径:cotutor.json 的 server.https 优先(相对 workspace 根),否则机器级 ~/.config/cotutor/certs/;都没有 → null */
+export declare function httpsFiles(ws: Workspace): {
+    cert: string;
+    key: string;
+} | null;
+/** 局域网 IPv4(iPad / iPhone 用它访问;.local 名不一定解析得到,有些设备还会挑中走不通的 IPv6) */
+export declare function lanAddresses(): string[];
+/**
+ * 这台电脑在局域网里的名字(不带 .local)。macOS 读「本地主机名」(系统设置 › 通用 › 共享 里那个,就是 Bonjour 名,改了系统才变);
+ * 别的系统用 os.hostname()。读不到退回 os.hostname()。serve、证书、二维码都从这里拿
+ */
+export declare function computerName(platform?: NodeJS.Platform, read?: () => string, fallback?: string): string;
+/** 本机的 mDNS 名(与 cotutor cert 签的那条同一个写法) */
+export declare function localName(name?: string): string;
+/** 证书认不认这个主机名;读不了当作不认 */
+export declare function certCovers(certFile: string, host: string): boolean;
+/** 扫码页要的三样;listen 之后才知道真端口 */
+export declare function listenInfo(https: boolean, port: number): ListenInfo;
+export declare function serveWorkspace(opts?: ServeOptions): Promise<ServeResult>;
+/**
+ * busy() 为真就起一个拦闲置睡眠的子进程,为假就停;serve 没了它自己退:macOS 是 caffeinate -i -w <pid>,Windows 是一段 PowerShell(service-windows.ts 的 awakeScript);Linux 什么都不做。
+ * 合盖照样睡(那是家长的事,iPad 那篇写着);返回停掉的函数
+ */
+export declare function holdAwake(busy: () => boolean, platform?: NodeJS.Platform, everyMs?: number): () => void;

package/dist/app/cli/serve.js

@@ -0,0 +1,168 @@
+/**
+ * cotutor serve:一 workspace 一进程,端口读 cotutor.json(--port 覆盖)。
+ * 启动打印解析结果与体检警告(配置坏了直接不起,骨架缺失只警告)。
+ * 扫码页:/qr 现画一张二维码(编 <电脑名>.local 那条,不随 Wi-Fi 变),iPad 用相机扫;listen 之后把真端口交给 ctx.listen。端口是 443 时地址里不写端口(siteUrl)。
+ * HTTPS(iPad 上录音要):server.https 指了证书就用它(单个 workspace 的例外);没指就看机器级 ~/.config/cotutor/certs/(cotutor cert 用 mkcert 建);都没有走 HTTP。
+ * 有通话开着、或有老师在写,就拦着这台电脑闲置睡眠(macOS caffeinate -i,Windows SetThreadExecutionState);闲着不拦(家长定)。网络流量挡不住闲置睡眠,上着课没人碰电脑也会睡过去。
+ */
+import { execFileSync, spawn } from 'node:child_process';
+import { X509Certificate } from 'node:crypto';
+import { readFileSync } from 'node:fs';
+import { createServer as createHttp } from 'node:http';
+import { createServer as createHttps } from 'node:https';
+import { hostname, networkInterfaces } from 'node:os';
+import { join } from 'node:path';
+import { siteUrl } from "../../shared/site-url.js";
+import { doctorWorkspace } from "./doctor.js";
+import { answersLocally } from "./port.js";
+import { awakeScript, psArgs } from "./service-windows.js";
+import { createContext, createHandler } from "../http/app.js";
+import { liveUpgrade } from "../ws/route.js";
+import { AUTO_BOOKKEEP_EVERY_MS, autoBookkeep } from "../../runtime/auto-bookkeep.js";
+import { USER_CERT_DIR, expandPath, loadWorkspace } from "../workspace.js";
+export { siteUrl };
+/** 证书路径:cotutor.json 的 server.https 优先(相对 workspace 根),否则机器级 ~/.config/cotutor/certs/;都没有 → null */
+export function httpsFiles(ws) {
+    const h = ws.config.server.https;
+    if (h)
+        return { cert: expandPath(h.cert, ws.root), key: expandPath(h.key, ws.root) };
+    const cert = join(USER_CERT_DIR, 'cert.pem');
+    const key = join(USER_CERT_DIR, 'key.pem');
+    try {
+        readFileSync(cert);
+        readFileSync(key);
+        return { cert, key };
+    }
+    catch {
+        return null;
+    }
+}
+/** 局域网 IPv4(iPad / iPhone 用它访问;.local 名不一定解析得到,有些设备还会挑中走不通的 IPv6) */
+export function lanAddresses() {
+    const out = [];
+    for (const list of Object.values(networkInterfaces()))
+        for (const i of list ?? [])
+            if (i.family === 'IPv4' && !i.internal)
+                out.push(i.address);
+    return out;
+}
+/**
+ * 这台电脑在局域网里的名字(不带 .local)。macOS 读「本地主机名」(系统设置 › 通用 › 共享 里那个,就是 Bonjour 名,改了系统才变);
+ * 别的系统用 os.hostname()。读不到退回 os.hostname()。serve、证书、二维码都从这里拿
+ */
+export function computerName(platform = process.platform, read = () => execFileSync('/usr/sbin/scutil', ['--get', 'LocalHostName'], { encoding: 'utf8', timeout: 2000, stdio: ['ignore', 'pipe', 'ignore'] }), fallback = hostname()) {
+    if (platform === 'darwin') {
+        try {
+            const name = read().trim();
+            if (name)
+                return name;
+        }
+        catch { /* 没设过本地主机名 */ }
+    }
+    return fallback.replace(/\.local$/i, '');
+}
+/** 读 scutil 要起一个进程,登录、发一条这些请求里都会问到:记一分钟 */
+let nameCache = null;
+function currentName() {
+    const now = Date.now();
+    if (!nameCache || now - nameCache.at > 60_000)
+        nameCache = { at: now, name: computerName() };
+    return nameCache.name;
+}
+/** 本机的 mDNS 名(与 cotutor cert 签的那条同一个写法) */
+export function localName(name = currentName()) {
+    return name.endsWith('.local') ? name : `${name}.local`;
+}
+/** 证书认不认这个主机名;读不了当作不认 */
+export function certCovers(certFile, host) {
+    try {
+        return new X509Certificate(readFileSync(certFile)).checkHost(host) !== undefined;
+    }
+    catch {
+        return false;
+    }
+}
+/** 扫码页要的三样;listen 之后才知道真端口 */
+export function listenInfo(https, port) {
+    const scheme = https ? 'https' : 'http';
+    const ip = lanAddresses()[0];
+    return { name: siteUrl(scheme, localName(), port), ip: ip ? siteUrl(scheme, ip, port) : null, https };
+}
+export async function serveWorkspace(opts = {}) {
+    const ws = loadWorkspace(opts.workspace, opts);
+    // 不探 CLI(起服务不用等它);防火墙要查:平板连不上时这里是家长唯一看得到提醒的地方
+    const report = await doctorWorkspace(ws.root, { ...opts, probeEnv: false, firewall: true });
+    const warnings = report.checks.filter((c) => !c.ok).map((c) => `${c.name}:${c.detail}${c.fix ? `(${c.fix})` : ''}`);
+    const port = opts.port ?? ws.config.server.port;
+    const ctx = createContext(ws);
+    ctx.openCalls = () => liveUpgrade.openCalls();
+    const handler = createHandler(ctx);
+    const tls = opts.http ? null : httpsFiles(ws);
+    const server = tls ? createHttps({ cert: readFileSync(tls.cert), key: readFileSync(tls.key) }, handler) : createHttp(handler);
+    // WebSocket:实时老师的那条线(src/app/ws/);不认就关掉
+    server.on('upgrade', (req, socket, head) => { void liveUpgrade(req, socket, head, ctx).then((took) => { if (!took)
+        socket.destroy(); }, () => socket.destroy()); });
+    // 别的程序只占着 127.0.0.1 时,绑通配地址照样成功:平板连到这边,这台电脑上开 localhost 却到了别的程序。先问一声,当被占处理(main.ts 接)
+    if (port !== 0 && (await answersLocally(port)))
+        throw Object.assign(new Error(`port ${port} answers on 127.0.0.1`), { code: 'EADDRINUSE', port });
+    await new Promise((resolveListen, reject) => {
+        server.once('error', reject);
+        server.listen(port, opts.host ?? '0.0.0.0', () => resolveListen());
+    });
+    const actual = server.address().port;
+    const scheme = tls ? 'https' : 'http';
+    const urls = [localName(), ...lanAddresses()].map((h) => siteUrl(scheme, h, actual));
+    ctx.listen = () => listenInfo(Boolean(tls), actual);
+    // 自动记账(cotutor.json vault.autoBookkeep,缺省关;src/runtime/auto-bookkeep.ts):隔一阵看一次,开关跟着 cotutor.json 热重载;上一次没跑完不叠
+    let booking = false;
+    const timer = setInterval(() => {
+        if (booking)
+            return;
+        booking = true;
+        void (async () => {
+            await ctx.reload();
+            await autoBookkeep(ctx.runner, ctx.ws, ctx.now());
+        })().catch(() => undefined).finally(() => { booking = false; });
+    }, AUTO_BOOKKEEP_EVERY_MS);
+    timer.unref();
+    server.once('close', () => clearInterval(timer));
+    if (opts.awake !== false) {
+        const stop = holdAwake(() => liveUpgrade.openCalls() > 0 || Object.keys(ctx.ws.config.tutors).some((t) => ctx.runner.running(t) !== null));
+        server.once('close', stop);
+    }
+    if (tls && !certCovers(tls.cert, localName()))
+        warnings.push(`证书不含 ${localName()}:多半是电脑名变了(改过名,或局域网里有同名设备时 macOS 会自动加 -2),扫码打开会报「不安全」。重跑 cotutor cert 再重启服务,平板重新扫码`);
+    return { server, ctx, ws, port: actual, https: Boolean(tls), urls, parentPage: siteUrl(scheme, 'localhost', actual, '/parent/home'), warnings };
+}
+/** 多久看一次有没有事 */
+const AWAKE_CHECK_MS = 15_000;
+/**
+ * busy() 为真就起一个拦闲置睡眠的子进程,为假就停;serve 没了它自己退:macOS 是 caffeinate -i -w <pid>,Windows 是一段 PowerShell(service-windows.ts 的 awakeScript);Linux 什么都不做。
+ * 合盖照样睡(那是家长的事,iPad 那篇写着);返回停掉的函数
+ */
+export function holdAwake(busy, platform = process.platform, everyMs = AWAKE_CHECK_MS) {
+    if (platform !== 'darwin' && platform !== 'win32')
+        return () => { };
+    const start = () => (platform === 'darwin'
+        ? spawn('/usr/bin/caffeinate', ['-i', '-w', String(process.pid)], { stdio: 'ignore' })
+        : spawn('powershell.exe', psArgs(awakeScript(process.pid)), { stdio: 'ignore', windowsHide: true }));
+    let child = null;
+    const tick = () => {
+        const b = busy();
+        if (b && !child) {
+            const c = start();
+            c.on('error', () => { if (child === c)
+                child = null; });
+            c.on('exit', () => { if (child === c)
+                child = null; });
+            child = c;
+        }
+        else if (!b && child) {
+            child.kill();
+            child = null;
+        }
+    };
+    const timer = setInterval(tick, everyMs);
+    timer.unref();
+    return () => { clearInterval(timer); child?.kill(); child = null; };
+}

package/dist/app/cli/service-windows.d.ts

@@ -0,0 +1,50 @@
+/**
+ * cotutor service 在 Windows 上要的几样(service.ts 接这里):
+ *   登录时起来:写用户自己的注册表 HKCU\...\Run(不要管理员)。不用计划任务:登录触发对普通令牌可能要管理员,缺省还有 3 天超时、低优先级要逐项改。
+ *   没有窗口:Run 里是 wscript.exe 跑一个 JScript 启动器,WScript.Shell.Run(命令, 0) 起 node,控制台藏着;node 的子进程跟着用这个藏着的控制台,不另弹窗。
+ *     不用 conhost --headless(2026-11-06 Windows 11 build 26300 上直接以 0 退、node 根本没起,本来也没写进文档);不用 VBScript(微软在逐步下线);不用 powershell -WindowStyle Hidden(会闪一下)。
+ *   崩了再起:看护进程 cotutor service run(service.ts 的 runKeeper,一个 node),起 serve,非 0 隔 10 秒再起,0 不起,和 launchd、systemd 同样的说法。
+ *   停:按命令行找这个 workspace 的看护进程与 serve(PowerShell,输出不随系统语言变),taskkill /T /F。
+ * 这里全是拼字符串与读输出的纯函数,真跑在 service.ts。
+ */
+/** 一个参数写进命令行(CommandLineToArgvW 的规矩:引号前的反斜杠翻倍再转义引号,结尾的反斜杠翻倍) */
+export declare function winQuote(a: string): string;
+export declare const winCommandLine: (args: string[]) => string;
+/** 启动器的内容:wscript 跑它,藏着窗口起 args;第二行记着 args,找服务时读回来 */
+export declare function windowsLauncher(args: string[], root: string): string;
+/** 启动器存成 UTF-16 带 BOM:wscript 按这个读,路径里的中文才对(UTF-8 它按系统代码页读) */
+export declare const encodeLauncher: (text: string) => Buffer;
+/** 读服务文件:带 UTF-16 的 BOM 就按它解,别的按 UTF-8 */
+export declare function decodeServiceFile(buf: Buffer): string;
+/** 从启动器里读回 args;不是启动器 → null */
+export declare function launcherArgs(text: string): string[] | null;
+export declare const RUN_KEY = "HKCU\\Software\\Microsoft\\Windows\\CurrentVersion\\Run";
+/**
+ * 任务管理器「启动应用」里关掉一条,Run 项还在,只在这里记一笔:值的第一个字节单数 = 关了(02 开、03 关;2026-11-06 那台机器上 Docker Desktop 就是 03)。
+ * 那里显示的名字是 wscript.exe 的文件描述(Microsoft ® Windows Based Script Host),不是 Run 项的名字,看不出是 cotutor,所以要靠 service status 来说
+ */
+export declare const STARTUP_APPROVED_KEY = "HKCU\\Software\\Microsoft\\Windows\\CurrentVersion\\Explorer\\StartupApproved\\Run";
+/** reg query 这个值的输出:被关掉了没有(没这个值 = 没关) */
+export declare function startupDisabled(regQuery: string): boolean;
+/** Run 里写的那条 */
+export declare const runValue: (wscript: string, file: string) => string;
+/** 跑一段 PowerShell 的参数:编码传进去不用管引号,输出定成 UTF-8,关掉进度(第一次用模块时它往 stderr 写一堆) */
+export declare function psArgs(script: string): string[];
+/** 找这个 workspace 的看护进程(service run)与它起的 serve(带 --log-dir;终端里的 cotutor serve 不算) */
+export declare function findProcsScript(root: string): string;
+export interface WinProc {
+    pid: number;
+    keeper: boolean;
+}
+/** 上面那段的输出;坏的、空的当没有 */
+export declare function parseProcs(text: string): WinProc[];
+/**
+ * 拦着闲置睡眠(同 macOS 的 caffeinate -i):SetThreadExecutionState(ES_CONTINUOUS | ES_SYSTEM_REQUIRED) 之后等 serve 退出。
+ * 状态跟着这个线程走:进程被杀或 serve 没了就撤掉
+ */
+export declare function awakeScript(pid: number): string;
+/**
+ * powercfg /query SCHEME_CURRENT SUB_SLEEP STANDBYIDLE:接着电源几秒没人碰就睡(0 = 不睡);读不出 → null。
+ * 输出的字随系统语言变,只认顺序:最后两个十六进制是接电源、用电池(前面三个是最小、最大、步长)
+ */
+export declare function winAcSleepSeconds(powercfg: string): number | null;

package/dist/app/cli/service-windows.js

@@ -0,0 +1,117 @@
+/**
+ * cotutor service 在 Windows 上要的几样(service.ts 接这里):
+ *   登录时起来:写用户自己的注册表 HKCU\...\Run(不要管理员)。不用计划任务:登录触发对普通令牌可能要管理员,缺省还有 3 天超时、低优先级要逐项改。
+ *   没有窗口:Run 里是 wscript.exe 跑一个 JScript 启动器,WScript.Shell.Run(命令, 0) 起 node,控制台藏着;node 的子进程跟着用这个藏着的控制台,不另弹窗。
+ *     不用 conhost --headless(2026-11-06 Windows 11 build 26300 上直接以 0 退、node 根本没起,本来也没写进文档);不用 VBScript(微软在逐步下线);不用 powershell -WindowStyle Hidden(会闪一下)。
+ *   崩了再起:看护进程 cotutor service run(service.ts 的 runKeeper,一个 node),起 serve,非 0 隔 10 秒再起,0 不起,和 launchd、systemd 同样的说法。
+ *   停:按命令行找这个 workspace 的看护进程与 serve(PowerShell,输出不随系统语言变),taskkill /T /F。
+ * 这里全是拼字符串与读输出的纯函数,真跑在 service.ts。
+ */
+/** 一个参数写进命令行(CommandLineToArgvW 的规矩:引号前的反斜杠翻倍再转义引号,结尾的反斜杠翻倍) */
+export function winQuote(a) {
+    if (a && !/[\s"]/.test(a))
+        return a;
+    let out = '"';
+    let slashes = 0;
+    for (const ch of a) {
+        if (ch === '\\') {
+            slashes++;
+            continue;
+        }
+        if (ch === '"') {
+            out += `${'\\'.repeat(slashes * 2 + 1)}"`;
+            slashes = 0;
+            continue;
+        }
+        out += '\\'.repeat(slashes) + ch;
+        slashes = 0;
+    }
+    return `${out}${'\\'.repeat(slashes * 2)}"`;
+}
+export const winCommandLine = (args) => args.map(winQuote).join(' ');
+/** 启动器的内容:wscript 跑它,藏着窗口起 args;第二行记着 args,找服务时读回来 */
+export function windowsLauncher(args, root) {
+    return `// cotutor service install 写的;改了会被下次 install 盖掉。卸掉:cotutor service uninstall --workspace ${root.replace(/[\r\n]/g, ' ')}
+// args: ${JSON.stringify(args)}
+new ActiveXObject("WScript.Shell").Run(${JSON.stringify(winCommandLine(args))}, 0, false);
+`;
+}
+/** 启动器存成 UTF-16 带 BOM:wscript 按这个读,路径里的中文才对(UTF-8 它按系统代码页读) */
+export const encodeLauncher = (text) => Buffer.concat([Buffer.from([0xff, 0xfe]), Buffer.from(text, 'utf16le')]);
+/** 读服务文件:带 UTF-16 的 BOM 就按它解,别的按 UTF-8 */
+export function decodeServiceFile(buf) {
+    return buf[0] === 0xff && buf[1] === 0xfe ? buf.subarray(2).toString('utf16le') : buf.toString('utf8');
+}
+/** 从启动器里读回 args;不是启动器 → null */
+export function launcherArgs(text) {
+    const m = /^\/\/ args: (\[.*\])\s*$/m.exec(text);
+    if (!m)
+        return null;
+    try {
+        const v = JSON.parse(m[1]);
+        return Array.isArray(v) && v.every((x) => typeof x === 'string') ? v : null;
+    }
+    catch {
+        return null;
+    }
+}
+export const RUN_KEY = 'HKCU\\Software\\Microsoft\\Windows\\CurrentVersion\\Run';
+/**
+ * 任务管理器「启动应用」里关掉一条,Run 项还在,只在这里记一笔:值的第一个字节单数 = 关了(02 开、03 关;2026-11-06 那台机器上 Docker Desktop 就是 03)。
+ * 那里显示的名字是 wscript.exe 的文件描述(Microsoft ® Windows Based Script Host),不是 Run 项的名字,看不出是 cotutor,所以要靠 service status 来说
+ */
+export const STARTUP_APPROVED_KEY = 'HKCU\\Software\\Microsoft\\Windows\\CurrentVersion\\Explorer\\StartupApproved\\Run';
+/** reg query 这个值的输出:被关掉了没有(没这个值 = 没关) */
+export function startupDisabled(regQuery) {
+    const m = /REG_BINARY\s+([0-9a-fA-F]{2})/.exec(regQuery);
+    return m ? (Number.parseInt(m[1], 16) & 1) === 1 : false;
+}
+/** Run 里写的那条 */
+export const runValue = (wscript, file) => `"${wscript}" //B //Nologo "${file}"`;
+/** 跑一段 PowerShell 的参数:编码传进去不用管引号,输出定成 UTF-8,关掉进度(第一次用模块时它往 stderr 写一堆) */
+export function psArgs(script) {
+    const full = `[Console]::OutputEncoding=[Text.Encoding]::UTF8\n$ProgressPreference='SilentlyContinue'\n$ErrorActionPreference='SilentlyContinue'\n${script}`;
+    return ['-NoProfile', '-NonInteractive', '-ExecutionPolicy', 'Bypass', '-EncodedCommand', Buffer.from(full, 'utf16le').toString('base64')];
+}
+/** 找这个 workspace 的看护进程(service run)与它起的 serve(带 --log-dir;终端里的 cotutor serve 不算) */
+export function findProcsScript(root) {
+    return [
+        `$root = '${root.replaceAll("'", "''")}'`,
+        `$found = @(Get-CimInstance Win32_Process -Filter "Name='node.exe'" | Where-Object { $c = $_.CommandLine; $c -and $c.Contains($root) -and ($c.Contains(' service run ') -or ($c.Contains(' serve ') -and $c.Contains('--log-dir'))) })`,
+        `ConvertTo-Json -Compress -InputObject @($found | ForEach-Object { @{ pid = $_.ProcessId; keeper = $_.CommandLine.Contains(' service run ') } })`,
+    ].join('\n');
+}
+/** 上面那段的输出;坏的、空的当没有 */
+export function parseProcs(text) {
+    let raw;
+    try {
+        raw = JSON.parse(text.trim() || '[]');
+    }
+    catch {
+        return [];
+    }
+    const list = Array.isArray(raw) ? raw : raw ? [raw] : [];
+    return list.flatMap((x) => {
+        const o = x;
+        return typeof o.pid === 'number' ? [{ pid: o.pid, keeper: o.keeper === true }] : [];
+    });
+}
+/**
+ * 拦着闲置睡眠(同 macOS 的 caffeinate -i):SetThreadExecutionState(ES_CONTINUOUS | ES_SYSTEM_REQUIRED) 之后等 serve 退出。
+ * 状态跟着这个线程走:进程被杀或 serve 没了就撤掉
+ */
+export function awakeScript(pid) {
+    return [
+        `$t = Add-Type -MemberDefinition '[DllImport("kernel32.dll")] public static extern uint SetThreadExecutionState(uint f);' -Name Awake -Namespace Cotutor -PassThru`,
+        '[void]$t::SetThreadExecutionState([uint32]2147483649)',
+        `Wait-Process -Id ${pid}`,
+    ].join('\n');
+}
+/**
+ * powercfg /query SCHEME_CURRENT SUB_SLEEP STANDBYIDLE:接着电源几秒没人碰就睡(0 = 不睡);读不出 → null。
+ * 输出的字随系统语言变,只认顺序:最后两个十六进制是接电源、用电池(前面三个是最小、最大、步长)
+ */
+export function winAcSleepSeconds(powercfg) {
+    const hex = [...powercfg.matchAll(/0x([0-9a-fA-F]{8})/g)].map((m) => Number.parseInt(m[1], 16));
+    return hex.length >= 2 ? hex[hex.length - 2] : null;
+}

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

@@ -0,0 +1,138 @@
+export type ServicePlatform = 'darwin' | 'linux' | 'win32';
+/** 跑命令、读写文件之外要的:系统、家目录、uid;run 测试换假的 */
+export interface ServiceHost {
+    platform: NodeJS.Platform;
+    home: string;
+    uid: number;
+    env: NodeJS.ProcessEnv;
+    run(cmd: string, args: string[]): Promise<{
+        code: number;
+        stdout: string;
+        stderr: string;
+    }>;
+}
+export declare const realHost: () => ServiceHost;
+/** 这个系统做没做 */
+export declare function servicePlatform(platform: NodeJS.Platform): ServicePlatform;
+type HostPaths = Pick<ServiceHost, 'platform' | 'home' | 'env'>;
+/** 服务名:workspace 目录名的小写字母数字连字符;撞了别的 workspace 加路径的短 hash */
+export declare function serviceName(root: string, taken?: boolean): string;
+/** 服务文件放哪 */
+export declare function serviceDir(host: HostPaths): string;
+/** 日志放哪(一个服务一个目录) */
+export declare function serviceLogDir(host: HostPaths, name: string): string;
+/** serve 起来之前的输出(node 自己报的、模块没加载上)去哪:给人看的一句 */
+export declare function earlyLogHint(platform: ServicePlatform, s: {
+    label: string;
+    logDir: string | null;
+}): string;
+/** 看护进程的日志(Windows):serve 退了几次、起来之前的输出 */
+export declare const KEEPER_LOG = "keeper.log";
+/**
+ * 看护进程(Windows;cotutor service run):起 serve,非 0 隔 10 秒再起,0 不起(端口被占着);同 launchd 的 KeepAlive、systemd 的 Restart=on-failure。
+ * 给 serve 带上 COTUTOR_SERVICE(mode 算后台服务、端口被占以 0 退);返回退出码
+ */
+export declare function runKeeper(o: {
+    root: string;
+    logDir: string;
+    label: string;
+    node?: string;
+    bin?: string;
+    restartMs?: number;
+}): Promise<number>;
+export declare const wscriptPath: (host: ServiceHost) => string;
+export interface ServiceSpec {
+    name: string;
+    /** launchd 的 Label / systemd 的单元名(不带 .service) */
+    label: string;
+    /** 跑什么:node、bin、serve 与它的旗标 */
+    args: string[];
+    root: string;
+    logDir: string;
+    path: string;
+}
+export declare const xml: (s: string) => string;
+/** macOS 的 LaunchAgent */
+export declare function launchdPlist(s: ServiceSpec): string;
+/** Linux 的 systemd 用户服务 */
+export declare function systemdUnit(s: ServiceSpec): string;
+/** 从服务文件里读回跑的参数(找它是哪个 workspace 的) */
+export declare function serviceArgs(text: string): string[];
+export interface InstalledService {
+    name: string;
+    label: string;
+    file: string;
+    args: string[];
+    root: string;
+    logDir: string | null;
+}
+/** 这台电脑上 cotutor 装的服务(各是哪个 workspace 的) */
+export declare function listServices(host: ServiceHost): Promise<InstalledService[]>;
+/** 这个 workspace 的服务;没装 → null(Windows 上路径不分大小写) */
+export declare function findService(host: ServiceHost, root: string): Promise<InstalledService | null>;
+/** cotutor 的 bin(npm 装的是 dist/app/cli → 包根;仓里直跑是 src/app/cli → 仓根,一样往上三层) */
+export declare const binPath: () => string;
+/** 装:写服务文件、交给 launchd / systemd 起来;已经装过就照现在的 node、bin、PATH 重写一遍再起 */
+export declare function installService(host: ServiceHost, root: string, opts?: {
+    node?: string;
+    bin?: string;
+}): Promise<{
+    spec: ServiceSpec;
+    file: string;
+    replaced: boolean;
+}>;
+/** 卸:停下、删服务文件;日志留着 */
+export declare function uninstallService(host: ServiceHost, root: string): Promise<InstalledService | null>;
+/** 起 / 停 / 重起。macOS 的停是从 launchd 卸下、Windows 的停是杀进程(服务文件都还在,下次登录又会起;要一直不起用 uninstall) */
+export declare function controlService(host: ServiceHost, root: string, what: 'start' | 'stop' | 'restart'): Promise<InstalledService>;
+/** launchctl print 那一大段里要的几行(一层缩进的 state / pid / last exit code) */
+export declare function parseLaunchctlPrint(text: string): {
+    running: boolean;
+    pid: number | null;
+    lastExit: string | null;
+};
+/** systemctl show -p ActiveState,MainPID,ExecMainStatus 的输出 */
+export declare function parseSystemctlShow(text: string): {
+    running: boolean;
+    pid: number | null;
+    lastExit: string | null;
+};
+/** /api/health 回的(只取要的) */
+export interface Health {
+    version: string | null;
+    started: string;
+    pid?: number;
+    mode?: string;
+    vault?: string;
+    /** 现在开着几通电话(托盘:退出前要不要问一声) */
+    calls?: number;
+    /** 百炼配了没有(托盘:没配算有事要处理) */
+    bailian?: boolean;
+    configError?: string | null;
+    /** 问到的是 https 还是 http(这边加的,不是服务回的) */
+    scheme?: 'https' | 'http';
+}
+/** 本机问一下 serve 起来没有(自签证书不验);先 https 再 http */
+export declare function probeHealth(port: number, timeoutMs?: number): Promise<Health | null>;
+export interface ServiceStatus {
+    installed: InstalledService | null;
+    running: boolean;
+    pid: number | null;
+    lastExit: string | null;
+    health: Health | null;
+    logFile: string | null;
+    /** Windows:下次登录还会不会自己起来(Run 项被删了、任务管理器里关掉了都算不会);别的系统 null */
+    autostart: boolean | null;
+}
+/** 装没装、在不在跑、问得到不(端口来自 cotutor.json 或 --port) */
+export declare function serviceStatus(host: ServiceHost, root: string, port: number): Promise<ServiceStatus>;
+/** 起来以后等它答应(装完、重起完);等不到 → null */
+export declare function waitHealthy(port: number, ms?: number, since?: string): Promise<Health | null>;
+/** 日志的最后 n 行(今天的没有就找最近一天的) */
+export declare function tailLog(logDir: string, n?: number): Promise<{
+    file: string;
+    lines: string[];
+} | null>;
+/** pmset -g custom 里「AC Power:」那一段的 sleep(接着电源几分钟没人碰就睡,0 = 不睡);没有那一段 → null */
+export declare function acSleepMinutes(pmset: string): number | null;
+export {};