cotutor 0.2.0 → 0.4.0

package/dist/app/cli/service.js

@@ -0,0 +1,429 @@
+/**
+ * cotutor service:把一个 workspace 的 serve 装成这台电脑的后台服务——登录后自己起来、崩了自己拉起、日志按天落文件(serve-log.ts)。
+ *   macOS:用户级 LaunchAgent ~/Library/LaunchAgents/com.tarslab.cotutor.<名>.plist(launchctl bootstrap gui/<uid>);日志 ~/Library/Logs/cotutor/<名>/
+ *   Linux:systemd 用户服务 ~/.config/systemd/user/cotutor-<名>.service(systemctl --user);日志 ~/.local/state/cotutor/logs/<名>/;不登录也要跑要 loginctl enable-linger
+ *   Windows:用户的 Run 注册表项 + wscript 跑的隐藏启动器 %LOCALAPPDATA%\cotutor\service\cotutor-<名>.js + 看护进程 cotutor service run(runKeeper);为什么这样见 service-windows.ts;日志 %LOCALAPPDATA%\cotutor\logs\<名>\
+ * 一个 workspace 一个服务;找服务按文件里写的 --workspace 找,不按名字推(两个同名目录的 workspace 不会认错)。
+ * 装的那一刻把 node、bin、PATH 写死:launchd 的 PATH 里没有 Homebrew 和 nvm;换了 node 版本、包挪了地方,再 install 一次(幂等)。
+ * 退出码 0 不拉起(端口被别人占着时 serve 以 0 退,不一直重试);崩了(非 0、被杀)隔 10 秒拉起。
+ */
+import { execFile, spawn } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { appendFileSync, closeSync, existsSync, mkdirSync, openSync, realpathSync, renameSync, statSync } from 'node:fs';
+import { mkdir, readFile, readdir, rm, writeFile } from 'node:fs/promises';
+import { request as httpRequest } from 'node:http';
+import { request as httpsRequest } from 'node:https';
+import { homedir } from 'node:os';
+import { basename, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { UsageError } from "../../shared/errors.js";
+import { logFileFor } from "./serve-log.js";
+import { RUN_KEY, STARTUP_APPROVED_KEY, decodeServiceFile, encodeLauncher, findProcsScript, launcherArgs, parseProcs, psArgs, runValue, startupDisabled, windowsLauncher } from "./service-windows.js";
+/** 命令的输出:先按 UTF-8;中文 Windows 上 reg、taskkill 这些回的是 GBK */
+function decodeOutput(buf) {
+    try {
+        return new TextDecoder('utf-8', { fatal: true }).decode(buf);
+    }
+    catch {
+        return new TextDecoder('gbk').decode(buf);
+    }
+}
+export const realHost = () => ({
+    platform: process.platform,
+    home: homedir(),
+    uid: process.getuid?.() ?? 0,
+    env: process.env,
+    run: (cmd, args) => new Promise((resolve) => {
+        execFile(cmd, args, { timeout: 30_000, encoding: 'buffer', windowsHide: true }, (err, stdout, stderr) => {
+            const code = err ? (typeof err.code === 'number' ? err.code : 1) : 0;
+            const errText = decodeOutput(stderr ?? Buffer.alloc(0));
+            resolve({ code, stdout: decodeOutput(stdout ?? Buffer.alloc(0)), stderr: errText || (err ? err.message : '') });
+        });
+    }),
+});
+const LABEL_PREFIX = 'com.tarslab.cotutor.';
+const UNIT_PREFIX = 'cotutor-';
+/** 这个系统做没做 */
+export function servicePlatform(platform) {
+    if (platform === 'darwin' || platform === 'linux' || platform === 'win32')
+        return platform;
+    throw new UsageError(`${platform} 上没做后台服务,用 cotutor serve 在前台跑`);
+}
+const winLocal = (host) => host.env.LOCALAPPDATA || join(host.home, 'AppData', 'Local');
+/** 服务名:workspace 目录名的小写字母数字连字符;撞了别的 workspace 加路径的短 hash */
+export function serviceName(root, taken = false) {
+    const base = basename(root).toLowerCase().replace(/[^a-z0-9-]+/g, '-').replace(/^-+|-+$/g, '') || 'workspace';
+    return taken ? `${base}-${createHash('sha256').update(root).digest('hex').slice(0, 6)}` : base;
+}
+/** 服务文件放哪 */
+export function serviceDir(host) {
+    const p = servicePlatform(host.platform);
+    if (p === 'darwin')
+        return join(host.home, 'Library', 'LaunchAgents');
+    if (p === 'win32')
+        return join(winLocal(host), 'cotutor', 'service');
+    return join(host.env.XDG_CONFIG_HOME || join(host.home, '.config'), 'systemd', 'user');
+}
+/** 日志放哪(一个服务一个目录) */
+export function serviceLogDir(host, name) {
+    const p = servicePlatform(host.platform);
+    if (p === 'darwin')
+        return join(host.home, 'Library', 'Logs', 'cotutor', name);
+    if (p === 'win32')
+        return join(winLocal(host), 'cotutor', 'logs', name);
+    return join(host.env.XDG_STATE_HOME || join(host.home, '.local', 'state'), 'cotutor', 'logs', name);
+}
+const fileOf = (host, name) => {
+    const p = servicePlatform(host.platform);
+    return join(serviceDir(host), p === 'darwin' ? `${LABEL_PREFIX}${name}.plist` : p === 'win32' ? `${UNIT_PREFIX}${name}.js` : `${UNIT_PREFIX}${name}.service`);
+};
+const labelOf = (platform, name) => (platform === 'darwin' ? `${LABEL_PREFIX}${name}` : `${UNIT_PREFIX}${name}`);
+/** serve 起来之前的输出(node 自己报的、模块没加载上)去哪:给人看的一句 */
+export function earlyLogHint(platform, s) {
+    if (platform === 'linux')
+        return `journalctl --user -u ${s.label}.service`;
+    return join(s.logDir ?? '', platform === 'win32' ? KEEPER_LOG : 'launchd.log');
+}
+/** 看护进程的日志(Windows):serve 退了几次、起来之前的输出 */
+export const KEEPER_LOG = 'keeper.log';
+const KEEPER_LOG_MAX = 5 * 1024 * 1024;
+const KEEPER_RESTART_MS = 10_000;
+/**
+ * 看护进程(Windows;cotutor service run):起 serve,非 0 隔 10 秒再起,0 不起(端口被占着);同 launchd 的 KeepAlive、systemd 的 Restart=on-failure。
+ * 给 serve 带上 COTUTOR_SERVICE(mode 算后台服务、端口被占以 0 退);返回退出码
+ */
+export async function runKeeper(o) {
+    mkdirSync(o.logDir, { recursive: true });
+    const logFile = join(o.logDir, KEEPER_LOG);
+    const note = (text) => { try {
+        appendFileSync(logFile, `${new Date().toISOString()} ${text}\n`);
+    }
+    catch { /* 写不了日志不能把看护带倒 */ } };
+    for (;;) {
+        try {
+            if (statSync(logFile).size > KEEPER_LOG_MAX)
+                renameSync(logFile, `${logFile}.1`);
+        }
+        catch { /* 还没有 */ }
+        const fd = openSync(logFile, 'a');
+        const child = spawn(o.node ?? process.execPath, [o.bin ?? binPath(), 'serve', '--workspace', o.root, '--log-dir', o.logDir], { stdio: ['ignore', fd, fd], windowsHide: true, env: { ...process.env, COTUTOR_SERVICE: o.label } });
+        const code = await new Promise((resolve) => {
+            child.once('error', (err) => { note(`serve 起不来:${err.message}`); resolve(null); });
+            child.once('exit', (c) => resolve(c));
+        });
+        closeSync(fd);
+        if (code === 0) {
+            note('serve 以 0 退(端口被占着?),不再起;cotutor service start 再起');
+            return 0;
+        }
+        note(`serve 退了(${code ?? '没起来'}),${Math.round((o.restartMs ?? KEEPER_RESTART_MS) / 1000)} 秒后再起`);
+        await new Promise((r) => setTimeout(r, o.restartMs ?? KEEPER_RESTART_MS));
+    }
+}
+export const wscriptPath = (host) => join(host.env.SystemRoot || 'C:\\Windows', 'System32', 'wscript.exe');
+/** 这个 workspace 的看护进程与 serve 现在的进程 */
+async function windowsProcs(host, root) {
+    return parseProcs((await host.run('powershell.exe', psArgs(findProcsScript(root)))).stdout);
+}
+/** 停:看护进程连着子进程一起杀;看护没了留下的 serve 也杀 */
+async function stopWindows(host, root) {
+    const procs = await windowsProcs(host, root);
+    for (const p of [...procs].sort((a, b) => Number(b.keeper) - Number(a.keeper)))
+        await host.run('taskkill.exe', ['/PID', String(p.pid), '/T', '/F']);
+}
+/** 起:wscript 跑启动器,藏着窗口起看护进程,马上回来 */
+async function startWindows(host, file) {
+    const r = await host.run(wscriptPath(host), ['//B', '//Nologo', file]);
+    if (r.code !== 0)
+        throw new UsageError(`wscript 没成(系统可能关了 Windows Script Host):${(r.stderr || r.stdout).trim()}`);
+}
+export const xml = (s) => s.replaceAll('&', '&amp;').replaceAll('<', '&lt;').replaceAll('>', '&gt;').replaceAll('"', '&quot;');
+const unxml = (s) => s.replaceAll('&lt;', '<').replaceAll('&gt;', '>').replaceAll('&quot;', '"').replaceAll('&apos;', "'").replaceAll('&amp;', '&');
+/** macOS 的 LaunchAgent */
+export function launchdPlist(s) {
+    const str = (v) => `<string>${xml(v)}</string>`;
+    return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<!-- cotutor service install 写的;改了会被下次 install 盖掉。卸掉:cotutor service uninstall --workspace ${xml(s.root)} -->
+<plist version="1.0">
+<dict>
+  <key>Label</key>${str(s.label)}
+  <key>ProgramArguments</key>
+  <array>
+${s.args.map((a) => `    ${str(a)}`).join('\n')}
+  </array>
+  <key>WorkingDirectory</key>${str(s.root)}
+  <key>EnvironmentVariables</key>
+  <dict>
+    <key>PATH</key>${str(s.path)}
+    <key>COTUTOR_SERVICE</key>${str(s.label)}
+  </dict>
+  <key>RunAtLoad</key><true/>
+  <key>KeepAlive</key>
+  <dict>
+    <key>SuccessfulExit</key><false/>
+  </dict>
+  <key>ThrottleInterval</key><integer>10</integer>
+  <key>ProcessType</key><string>Interactive</string>
+  <key>StandardOutPath</key>${str(join(s.logDir, 'launchd.log'))}
+  <key>StandardErrorPath</key>${str(join(s.logDir, 'launchd.log'))}
+</dict>
+</plist>
+`;
+}
+/** systemd 的一个参数:双引号括起来,反斜杠与引号转义,% 写两个 */
+const sd = (v) => `"${v.replaceAll('\\', '\\\\').replaceAll('"', '\\"').replaceAll('%', '%%')}"`;
+/** Linux 的 systemd 用户服务 */
+export function systemdUnit(s) {
+    return `# cotutor service install 写的;改了会被下次 install 盖掉。卸掉:cotutor service uninstall --workspace ${s.root}
+[Unit]
+Description=cotutor (${s.name})
+After=network-online.target
+
+[Service]
+ExecStart=${s.args.map(sd).join(' ')}
+WorkingDirectory=${sd(s.root)}
+Environment=${sd(`PATH=${s.path}`)}
+Environment=${sd(`COTUTOR_SERVICE=${s.label}`)}
+Restart=on-failure
+RestartSec=10
+
+[Install]
+WantedBy=default.target
+`;
+}
+/** 从服务文件里读回跑的参数(找它是哪个 workspace 的) */
+export function serviceArgs(text) {
+    const js = launcherArgs(text);
+    if (js)
+        return js;
+    const plist = /<key>ProgramArguments<\/key>\s*<array>([\s\S]*?)<\/array>/.exec(text);
+    if (plist)
+        return [...plist[1].matchAll(/<string>([\s\S]*?)<\/string>/g)].map((m) => unxml(m[1]));
+    const line = /^ExecStart=(.*)$/m.exec(text)?.[1];
+    if (!line)
+        return [];
+    const out = [];
+    for (const m of line.matchAll(/"((?:[^"\\]|\\.)*)"|(\S+)/g))
+        out.push(m[1] !== undefined ? m[1].replace(/\\(.)/g, '$1').replaceAll('%%', '%') : m[2]);
+    return out;
+}
+const workspaceOf = (args) => { const i = args.indexOf('--workspace'); return i >= 0 && args[i + 1] ? args[i + 1] : null; };
+const real = (p) => { try {
+    return realpathSync(p);
+}
+catch {
+    return p;
+} };
+/** 这台电脑上 cotutor 装的服务(各是哪个 workspace 的) */
+export async function listServices(host) {
+    const dir = serviceDir(host);
+    const platform = servicePlatform(host.platform);
+    const pattern = platform === 'darwin' ? /^com\.tarslab\.cotutor\.(.+)\.plist$/ : platform === 'win32' ? /^cotutor-(.+)\.js$/ : /^cotutor-(.+)\.service$/;
+    const out = [];
+    for (const f of (await readdir(dir).catch(() => [])).sort()) {
+        const m = pattern.exec(f);
+        if (!m)
+            continue;
+        const args = serviceArgs(decodeServiceFile(await readFile(join(dir, f)).catch(() => Buffer.alloc(0))));
+        const root = workspaceOf(args);
+        if (!root)
+            continue;
+        const li = args.indexOf('--log-dir');
+        out.push({ name: m[1], label: labelOf(platform, m[1]), file: join(dir, f), args, root, logDir: li >= 0 ? args[li + 1] ?? null : null });
+    }
+    return out;
+}
+/** 这个 workspace 的服务;没装 → null(Windows 上路径不分大小写) */
+export async function findService(host, root) {
+    const norm = (p) => (host.platform === 'win32' ? real(p).toLowerCase() : real(p));
+    const want = norm(root);
+    return (await listServices(host)).find((s) => norm(s.root) === want) ?? null;
+}
+/** cotutor 的 bin(npm 装的是 dist/app/cli → 包根;仓里直跑是 src/app/cli → 仓根,一样往上三层) */
+export const binPath = () => fileURLToPath(new URL('../../../bin/cotutor.js', import.meta.url));
+/** 装:写服务文件、交给 launchd / systemd 起来;已经装过就照现在的 node、bin、PATH 重写一遍再起 */
+export async function installService(host, root, opts = {}) {
+    const platform = servicePlatform(host.platform);
+    const had = await findService(host, root);
+    let name = had?.name ?? serviceName(root);
+    if (!had && existsSync(fileOf(host, name)))
+        name = serviceName(root, true);
+    const label = labelOf(platform, name);
+    const logDir = serviceLogDir(host, name);
+    // Windows 上跑的是看护进程,它再起 serve(那边没有 launchd / systemd 替你拉起)
+    const run = platform === 'win32' ? ['service', 'run'] : ['serve'];
+    const spec = { name, label, root, logDir, path: host.env.PATH ?? '/usr/bin:/bin', args: [opts.node ?? process.execPath, opts.bin ?? binPath(), ...run, '--workspace', root, '--log-dir', logDir] };
+    const file = fileOf(host, name);
+    await mkdir(serviceDir(host), { recursive: true });
+    await mkdir(logDir, { recursive: true });
+    if (platform === 'win32') {
+        if (had)
+            await stopWindows(host, root);
+        await writeFile(file, encodeLauncher(windowsLauncher(spec.args, root)));
+        const reg = await host.run('reg.exe', ['add', RUN_KEY, '/v', label, '/t', 'REG_SZ', '/d', runValue(wscriptPath(host), file), '/f']);
+        if (reg.code !== 0)
+            throw new UsageError(`写登录项没成:${(reg.stderr || reg.stdout).trim()}`);
+        // 再装一次 = 要它:以前在任务管理器里关掉的记录也去掉(没有这一笔时报错,不管)
+        await host.run('reg.exe', ['delete', STARTUP_APPROVED_KEY, '/v', label, '/f']);
+        await startWindows(host, file);
+    }
+    else if (platform === 'darwin') {
+        // 先卸下旧的(没装过会报错,不管),再装上;bootstrap 会按 RunAtLoad 马上起
+        await host.run('launchctl', ['bootout', `gui/${host.uid}/${label}`]);
+        await writeFile(file, launchdPlist(spec));
+        const r = await host.run('launchctl', ['bootstrap', `gui/${host.uid}`, file]);
+        if (r.code !== 0)
+            throw new UsageError(`launchctl bootstrap 没成:${(r.stderr || r.stdout).trim()}`);
+    }
+    else {
+        await writeFile(file, systemdUnit(spec));
+        await host.run('systemctl', ['--user', 'daemon-reload']);
+        const r = await host.run('systemctl', ['--user', 'enable', '--now', `${label}.service`]);
+        if (r.code !== 0)
+            throw new UsageError(`systemctl --user enable 没成:${(r.stderr || r.stdout).trim()}`);
+        if (had)
+            await host.run('systemctl', ['--user', 'restart', `${label}.service`]);
+    }
+    return { spec, file, replaced: Boolean(had) };
+}
+/** 卸:停下、删服务文件;日志留着 */
+export async function uninstallService(host, root) {
+    const s = await findService(host, root);
+    if (!s)
+        return null;
+    const platform = servicePlatform(host.platform);
+    if (platform === 'win32') {
+        await stopWindows(host, s.root);
+        await host.run('reg.exe', ['delete', RUN_KEY, '/v', s.label, '/f']);
+        await host.run('reg.exe', ['delete', STARTUP_APPROVED_KEY, '/v', s.label, '/f']);
+    }
+    else if (platform === 'darwin')
+        await host.run('launchctl', ['bootout', `gui/${host.uid}/${s.label}`]);
+    else
+        await host.run('systemctl', ['--user', 'disable', '--now', `${s.label}.service`]);
+    await rm(s.file, { force: true });
+    if (host.platform === 'linux')
+        await host.run('systemctl', ['--user', 'daemon-reload']);
+    return s;
+}
+const need = async (host, root) => {
+    const s = await findService(host, root);
+    if (!s)
+        throw new UsageError('这个 workspace 没装后台服务:cotutor service install');
+    return s;
+};
+/** 起 / 停 / 重起。macOS 的停是从 launchd 卸下、Windows 的停是杀进程(服务文件都还在,下次登录又会起;要一直不起用 uninstall) */
+export async function controlService(host, root, what) {
+    const s = await need(host, root);
+    const platform = servicePlatform(host.platform);
+    if (platform === 'win32') {
+        if (what !== 'start')
+            await stopWindows(host, s.root);
+        if (what === 'stop')
+            return s;
+        // 已经在跑就不再起一个(再起一个也会因为端口被占以 0 退,只是多转一圈)
+        if (!(await windowsProcs(host, s.root)).some((p) => p.keeper))
+            await startWindows(host, s.file);
+        return s;
+    }
+    if (platform === 'darwin') {
+        const target = `gui/${host.uid}/${s.label}`;
+        const loaded = (await host.run('launchctl', ['print', target])).code === 0;
+        if (what === 'stop') {
+            if (loaded)
+                await host.run('launchctl', ['bootout', target]);
+            return s;
+        }
+        const r = loaded ? await host.run('launchctl', what === 'restart' ? ['kickstart', '-k', target] : ['kickstart', target]) : await host.run('launchctl', ['bootstrap', `gui/${host.uid}`, s.file]);
+        if (r.code !== 0)
+            throw new UsageError(`launchctl 没成:${(r.stderr || r.stdout).trim()}`);
+        return s;
+    }
+    const r = await host.run('systemctl', ['--user', what, `${s.label}.service`]);
+    if (r.code !== 0)
+        throw new UsageError(`systemctl --user ${what} 没成:${(r.stderr || r.stdout).trim()}`);
+    return s;
+}
+/** launchctl print 那一大段里要的几行(一层缩进的 state / pid / last exit code) */
+export function parseLaunchctlPrint(text) {
+    const field = (k) => new RegExp(`^\\t${k} = (.*)$`, 'm').exec(text)?.[1]?.trim() ?? null;
+    const pid = Number(field('pid'));
+    return { running: field('state') === 'running', pid: Number.isInteger(pid) && pid > 0 ? pid : null, lastExit: field('last exit code') };
+}
+/** systemctl show -p ActiveState,MainPID,ExecMainStatus 的输出 */
+export function parseSystemctlShow(text) {
+    const kv = Object.fromEntries(text.split('\n').map((l) => l.split('=')).filter((p) => p.length >= 2).map(([k, ...v]) => [k.trim(), v.join('=').trim()]));
+    const pid = Number(kv.MainPID);
+    return { running: kv.ActiveState === 'active', pid: pid > 0 ? pid : null, lastExit: kv.ExecMainStatus ?? null };
+}
+/** 本机问一下 serve 起来没有(自签证书不验);先 https 再 http */
+export async function probeHealth(port, timeoutMs = 1500) {
+    const get = (secure) => new Promise((resolve) => {
+        const req = (secure ? httpsRequest : httpRequest)({ host: '127.0.0.1', port, path: '/api/health', method: 'GET', timeout: timeoutMs, ...(secure ? { rejectUnauthorized: false } : {}) }, (res) => {
+            let body = '';
+            res.setEncoding('utf8');
+            res.on('data', (c) => { body += c; });
+            res.on('end', () => { try {
+                const j = JSON.parse(body);
+                resolve(j.ok ? { ...j, scheme: secure ? 'https' : 'http' } : null);
+            }
+            catch {
+                resolve(null);
+            } });
+        });
+        req.on('timeout', () => req.destroy());
+        req.on('error', () => resolve(null));
+        req.end();
+    });
+    return (await get(true)) ?? (await get(false));
+}
+/** 装没装、在不在跑、问得到不(端口来自 cotutor.json 或 --port) */
+export async function serviceStatus(host, root, port) {
+    const s = await findService(host, root);
+    let st = { running: false, pid: null, lastExit: null };
+    let autostart = null;
+    if (s && host.platform === 'win32') {
+        const procs = await windowsProcs(host, s.root);
+        st = { running: procs.some((p) => p.keeper), pid: (procs.find((p) => !p.keeper) ?? procs[0])?.pid ?? null, lastExit: null };
+        autostart = (await host.run('reg.exe', ['query', RUN_KEY, '/v', s.label])).code === 0 && !startupDisabled((await host.run('reg.exe', ['query', STARTUP_APPROVED_KEY, '/v', s.label])).stdout);
+    }
+    else if (s) {
+        const r = host.platform === 'darwin'
+            ? await host.run('launchctl', ['print', `gui/${host.uid}/${s.label}`])
+            : await host.run('systemctl', ['--user', 'show', '-p', 'ActiveState,MainPID,ExecMainStatus', `${s.label}.service`]);
+        if (r.code === 0)
+            st = host.platform === 'darwin' ? parseLaunchctlPrint(r.stdout) : parseSystemctlShow(r.stdout);
+    }
+    const health = await probeHealth(port);
+    return { installed: s, ...st, health, logFile: s?.logDir ? logFileFor(s.logDir, new Date()) : null, autostart };
+}
+/** 起来以后等它答应(装完、重起完);等不到 → null */
+export async function waitHealthy(port, ms = 15_000, since) {
+    const until = Date.now() + ms;
+    while (Date.now() < until) {
+        const h = await probeHealth(port, 1000);
+        if (h && (!since || h.started > since))
+            return h;
+        await new Promise((r) => setTimeout(r, 300));
+    }
+    return null;
+}
+/** 日志的最后 n 行(今天的没有就找最近一天的) */
+export async function tailLog(logDir, n = 50) {
+    const files = (await readdir(logDir).catch(() => [])).filter((f) => /^\d{4}-\d{2}-\d{2}\.log$/.test(f)).sort();
+    const last = files.at(-1);
+    if (!last)
+        return null;
+    const file = join(logDir, last);
+    const lines = (await readFile(file, 'utf8').catch(() => '')).split('\n');
+    if (lines.at(-1) === '')
+        lines.pop();
+    return { file, lines: lines.slice(-n) };
+}
+/** pmset -g custom 里「AC Power:」那一段的 sleep(接着电源几分钟没人碰就睡,0 = 不睡);没有那一段 → null */
+export function acSleepMinutes(pmset) {
+    const ac = /^AC Power:\s*$([\s\S]*?)(?=^\S|(?![\s\S]))/m.exec(pmset)?.[1];
+    const v = ac ? /^\s+sleep\s+(\d+)/m.exec(ac)?.[1] : undefined;
+    return v === undefined ? null : Number(v);
+}

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

@@ -0,0 +1,30 @@
+export declare const SHIPPED_FILE = ".cotutor/shipped.json";
+export interface ShippedManifest {
+    /** 已安装的出厂教学包;旧版缺省按二年级迁移,与孩子当前年级分开。 */
+    teachingPack?: {
+        grade: number;
+    };
+    /** 出厂 skill(做课包的四个 chalk-* + 本包的机器件)的 hash,与 tutors 同一套机制(src/app/cli/skills.ts) */
+    skills?: Record<string, {
+        hash: string;
+        version: string;
+    }>;
+    /** 出厂主题(themes/<name>/)的目录 hash,同一套机制(src/app/cli/themes.ts) */
+    themes?: Record<string, {
+        hash: string;
+        version: string;
+    }>;
+    /** 出厂 activity(agents/<老师>/activities/<名>.md,键是「老师/名」),同一套机制(src/app/cli/activities.ts) */
+    activities?: Record<string, {
+        hash: string;
+        version: string;
+    }>;
+    version: string;
+    tutors: Record<string, {
+        hash: string;
+        version: string;
+    }>;
+}
+export declare const sha256: (text: string) => string;
+export declare function readManifest(root: string): Promise<ShippedManifest>;
+export declare function writeManifest(root: string, m: ShippedManifest): Promise<void>;

package/dist/app/cli/shipped.js

@@ -0,0 +1,47 @@
+/** 所有出厂件共用的来源记录;修改时保留其他种类的 hash。 */
+import { createHash } from 'node:crypto';
+import { readFile, mkdir, writeFile, rename } from 'node:fs/promises';
+import { join, dirname } from 'node:path';
+import { UsageError } from "../workspace.js";
+export const SHIPPED_FILE = '.cotutor/shipped.json';
+export const sha256 = (text) => `sha256:${createHash('sha256').update(text).digest('hex')}`;
+export async function readManifest(root) {
+    let text;
+    try {
+        text = await readFile(join(root, SHIPPED_FILE), 'utf8');
+    }
+    catch (err) {
+        if (err.code === 'ENOENT')
+            return { version: '0', tutors: {} };
+        throw err;
+    }
+    try {
+        const raw = JSON.parse(text);
+        if (!raw || typeof raw !== 'object' || Array.isArray(raw))
+            throw new Error('顶层要是对象');
+        if (raw.teachingPack !== undefined && (!raw.teachingPack || !Number.isInteger(raw.teachingPack.grade) || raw.teachingPack.grade < 1 || raw.teachingPack.grade > 6))
+            throw new Error('teachingPack.grade 要是 1–6 的整数');
+        for (const key of ['tutors', 'activities', 'skills', 'themes']) {
+            const records = raw[key];
+            if (records === undefined)
+                continue;
+            if (!records || typeof records !== 'object' || Array.isArray(records))
+                throw new Error(`${key} 要是对象`);
+            for (const rec of Object.values(records)) {
+                if (!rec || typeof rec.hash !== 'string' || typeof rec.version !== 'string')
+                    throw new Error(`${key} 的记录要有 hash 和 version`);
+            }
+        }
+        return { ...raw, version: raw.version ?? '0', tutors: raw.tutors ?? {} };
+    }
+    catch (err) {
+        throw new UsageError(`${join(root, SHIPPED_FILE)} 出厂记录用不了:${err.message}。请恢复或修复记录,不会重置 hash 或猜测年级。`);
+    }
+}
+export async function writeManifest(root, m) {
+    const file = join(root, SHIPPED_FILE);
+    await mkdir(dirname(file), { recursive: true });
+    const tmp = `${file}.tmp`;
+    await writeFile(tmp, `${JSON.stringify({ ...m, _note: '出厂时老师文件的 hash,cotutor upgrade 据此分辨「没改过」与「改过」;机器写,不用手改' }, null, 2)}\n`);
+    await rename(tmp, file);
+}

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

@@ -0,0 +1,38 @@
+export declare const DIRS: readonly ["agents", "ledger", "conversations", "bundles"];
+export declare const LEDGER_FILES: readonly ["ledger/artifacts.jsonl"];
+/** 默认年级的出厂老师目录;workspace 的操作用 workspaceGradePack 选来源 */
+export declare const PACKAGE_AGENTS_DIR: string;
+/** 本包版本(出厂件的 hash 记录带它,升级时知道基于哪版) */
+export declare const PACKAGE_VERSION: string;
+export interface ShippedAgent {
+    name: string;
+    file: string;
+    description: string;
+}
+export declare function shippedAgents(dir?: string): Promise<ShippedAgent[]>;
+export declare const GITIGNORE = "# \u8F6C\u5F55\u65E5\u5FD7\u4F53\u79EF\u5927\u3001\u53EF\u4ECE\u5BF9\u8BDD\u7D22\u5F15\u91CD\u5EFA\u5173\u952E\u4FE1\u606F;\u8981\u7559\u5168\u6863\u5C31\u5220\u6389\u4E0B\u9762\u8FD9\u884C\nconversations/**/*.log\n# \u914D\u97F3\u53EF\u91CD\u65B0\u5408\u6210\nconversations/**/*.mp3\n# \u56DE\u653E(cotutor replay)\u662F\u8C03\u63D0\u793A\u8BCD\u4E0E vault \u65F6\u7684\u5BF9\u7167,\u4E0D\u662F\u5B69\u5B50\u7684\u5BF9\u8BDD\nevals/\n# \u505A\u597D\u7684\u8BFE(\u8BFE\u5305\u3001\u89C6\u9891\u8BFE)\u4E0E\u8BFE\u5305\u622A\u56FE:\u4F53\u79EF\u5927,\u6E90\u5728\u5BB6\u957F\u505A\u8BFE\u7684\u5730\u65B9\nbundles/\nlectures/\nsnaps/\n# \u53E3\u8BED\u8BFE(\u5B69\u5B50\u7684\u539F\u58F0\u3001\u7167\u7247)\ntalk/\n# \u4F5C\u4E1A\u7167\u7247(\u5B69\u5B50\u5728\u8001\u5E08\u9875\u4E0A\u62CD\u7684;paths.captures):\u4F53\u79EF\u5927\u3001\u53EA\u662F\u8FD9\u4E00\u8F6E\u7684\u7D20\u6750,\u8BA4\u51FA\u7684\u6587\u5B57\u5728\u65E5\u8BB0\u91CC\ncaptures/\n# \u5BB6\u957F\u5728 workspace \u91CC\u7528 Claude Code \u65F6\u5B83\u7684\u4E2A\u4EBA\u8BBE\u7F6E\n.claude/settings.local.json\n# .cotutor/ \u662F\u673A\u5668\u6587\u4EF6(\u677F\u4E66\u5199\u6CD5\u7F13\u5B58\u3001\u914D\u97F3\u7F13\u5B58\u3001\u4E8C\u7EF4\u7801\u3001\u65E5\u5FD7),\u53EA\u7559\u51FA\u5382 hash \u4E0E schema\n.cotutor/*\n!.cotutor/shipped.json\n!.cotutor/cotutor.schema.json\nnode_modules/\n.DS_Store\n";
+/** 档案模板(paths.profile,缺了才写):cotutor: profile 的那篇,原文整篇进每个话题的第一条 */
+export declare function profileTemplate(name: string): string;
+/** 参考目录的 README(缺了才写) */
+export declare const REFERENCE_README = "# \u53C2\u8003\n\n\u8FD9\u91CC\u653E\u653F\u7B56\u4E0E\u4F60\u81EA\u5DF1\u7684\u7B14\u8BB0:\u8BB2\u67D0\u7C7B\u9898\u7684\u504F\u597D\u3001\u8584\u5F31\u70B9\u3001\u5FCC\u8BB3\u3001\u6309\u9898\u578B\u6574\u7406\u7684\u4E1C\u897F\u2014\u2014\u968F\u4FBF\u5EFA,\u673A\u5668\u53EA\u8BFB\u4E0D\u5199\u3002\n\u8BA9\u8001\u5E08\u770B\u5230\u7684\u529E\u6CD5:\u5728\u6863\u6848\u6216\u8FD9\u4F4D\u8001\u5E08\u7684\u5165\u53E3\u6587\u4EF6(`cotutor: subject` \u7684\u90A3\u7BC7)\u91CC\u94FE\u8FC7\u53BB(`[[\u627E\u89C4\u5F8B\u586B\u6570]]`);\u8001\u5E08\u62FF\u5230\u8DEF\u5F84,\u8981\u7528\u65F6\u81EA\u5DF1\u8BFB\u3002\n";
+export interface TutorTemplateInput {
+    name: string;
+    display: string;
+    subject?: string;
+    description?: string;
+}
+/**
+ * 家长自己加老师时的文件模板:和出厂老师一样只有人设与这一科的做法;
+ * 公共的守则(上下文包、三种回复、记忆段、不变的规矩)在机器技能 cotutor-tutor,应用每个话题第一条放进上下文包。
+ */
+export declare function tutorTemplate(t: TutorTemplateInput): string;
+export interface ConfigTemplateInput {
+    slug: string;
+    name?: string;
+    port?: number;
+    tutors: ShippedAgent[];
+}
+/** cotutor.json 模板:只在文件不存在时写入;政策文件永不自动重建或覆盖(家长的决定不由机器代做)。 */
+export declare function configTemplate(input: ConfigTemplateInput): string;
+/** 把 JSON Schema 写进 workspace(机器文件,每次 init / upgrade 都刷新);板书语法表出厂成技能 cotutor-board,见 skills.ts `writeBoardSkill` */
+export declare function writeSchemaFile(root: string): Promise<string>;