cotutor 0.4.2 → 0.4.4

package/dist/app/http/parent-setup.js

@@ -0,0 +1,96 @@
+/**
+ * 家长端「还差几步」、备份、诊断信息。第一次打开家长端,家长要知道接下来做什么,不用开终端跑 doctor。
+ *
+ *   GET  /api/parent/setup          {steps: [{id, done, required, title, detail, commands?, grades?}]}
+ *   POST /api/parent/setup/grade    {grade: 1-6}:档案没写学期时,按年级算出 school_start 写进档案
+ *   GET  /api/parent/report         {text}:诊断信息(cli/report.ts,已抹掉名字和 key,给人先看再发)
+ *   GET  /api/parent/backups        {dir, list: [...], commands}(给家长抄的命令,Windows 上带 .cmd)
+ *   POST /api/parent/backups        现在备份一份
+ *
+ * 步骤用 doctor 的结果,不另查一遍;只挑家长要动手的那几项,说家长听得懂的话。别的(老师文件、技能)doctor --fix 能修,不打扰家长。
+ */
+import { readFile, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { schoolStartFor, setSchoolStart } from "../../memory/vault-notes.js";
+import { scanVault } from "../../memory/vault.js";
+import { readDevices } from "../../runtime/journal/kid-log.js";
+import { cliLine } from "../../shared/upgrade.js";
+import { redactHome } from "../workspace.js";
+import { BUILD } from "../build.js";
+import { backupsOf, listBackups, makeBackup } from "../cli/backup.js";
+import { doctorWorkspace } from "../cli/doctor.js";
+import { buildReport } from "../cli/report.js";
+export async function setupSteps(ctx) {
+    const doc = await doctorWorkspace(ctx.ws.root, { probeEnv: true, firewall: false, now: ctx.now() });
+    const by = (name) => doc.checks.find((c) => c.name === name);
+    const devices = Object.keys(await readDevices(ctx.ws)).length;
+    const https = Boolean(ctx.listen?.().https);
+    const certOnDisk = by('https')?.ok === true;
+    const profile = by('vault.profile');
+    const steps = [
+        { id: 'bailian', done: ctx.bailian.status().ready, required: true, title: '填百炼的 key', detail: '老师开口和写讲稿都靠它。在这一页下面「百炼」那块填,保存前会先试连。' },
+        {
+            id: 'https', done: https, required: true, title: '给平板签证书', detail: '平板上按住说话要 HTTPS。证书要在这台电脑上签一次,根证书还要装到平板上。',
+            link: { href: 'https://github.com/TarsLab/cotutor/blob/main/docs/iPad与iPhone.md', text: '一步步的说明' },
+            commands: (certOnDisk ? ['cotutor service restart'] : ['cotutor cert', 'cotutor service restart']).map((c) => cliLine(c)),
+        },
+        { id: 'tablet', done: devices > 0, required: true, title: '让孩子的平板连上', detail: '用平板的相机扫这一页上「扫码打开」的那张码。' },
+    ];
+    if (profile)
+        steps.push({ id: 'semester', done: profile.ok, required: true, title: '告诉老师孩子几年级', detail: profile.ok ? profile.detail : '老师要知道现在是几年级哪个学期,才讲得对。', grades: !profile.ok });
+    const access = by('server.access');
+    if (access)
+        steps.push({ id: 'pin', done: access.ok, required: false, title: '给家长端设个密码', detail: '现在连上家里网络的设备都能打开家长端。家长在旁边可以不设。', commands: [cliLine('cotutor pin')] });
+    const sleep = by('mac.sleep') ?? by('windows.sleep');
+    if (sleep)
+        steps.push({ id: 'sleep', done: sleep.ok, required: false, title: '别让这台电脑睡着', detail: sleep.ok ? sleep.detail : sleep.fix ?? sleep.detail });
+    return steps;
+}
+export async function parentSetupRoute(method, p, ctx, body) {
+    if (p === '/api/parent/setup') {
+        if (method !== 'GET')
+            return { status: 405, json: { error: 'method_not_allowed' } };
+        return { status: 200, json: { steps: await setupSteps(ctx) } };
+    }
+    if (p === '/api/parent/setup/grade') {
+        if (method !== 'POST')
+            return { status: 405, json: { error: 'method_not_allowed' } };
+        const grade = typeof body === 'object' && body !== null ? body.grade : undefined;
+        if (typeof grade !== 'number' || !Number.isInteger(grade) || grade < 1 || grade > 6)
+            return { status: 400, json: { error: 'bad_request', message: '年级要 1 到 6' } };
+        const found = (await scanVault(ctx.ws)).notes.find((n) => n.props.cotutor === 'profile');
+        if (!found)
+            return { status: 409, json: { error: 'no_profile', message: '还没有档案:在终端里跑 cotutor init 补一篇' } };
+        if (found.props.school_start?.trim() || found.props.semester?.trim())
+            return { status: 409, json: { error: 'already_set', message: '档案里已经写了学期,要改就直接改档案' } };
+        const file = join(ctx.ws.paths.vault, found.path);
+        await writeFile(file, setSchoolStart(await readFile(file, 'utf8'), schoolStartFor(grade, ctx.now())));
+        return { status: 200, json: { ok: true } };
+    }
+    if (p === '/api/parent/report') {
+        if (method !== 'GET')
+            return { status: 405, json: { error: 'method_not_allowed' } };
+        const t = ctx.bailian.trouble();
+        const text = await buildReport(ctx.ws, {
+            now: ctx.now(),
+            health: { version: BUILD.version, started: BUILD.started, mode: process.env.COTUTOR_SERVICE ? 'service' : 'foreground', scheme: ctx.listen?.().https ? 'https' : 'http', bailianTrouble: t, configError: ctx.configError },
+        });
+        return { status: 200, json: { text } };
+    }
+    if (p === '/api/parent/backups') {
+        const target = { root: ctx.ws.root, vault: ctx.ws.paths.vault };
+        if (method === 'POST') {
+            try {
+                const b = await makeBackup(target, { why: 'manual', version: BUILD.version, now: ctx.now() });
+                return { status: 200, json: { ok: true, backup: b } };
+            }
+            catch (err) {
+                return { status: 500, json: { error: 'backup_failed', message: err instanceof Error ? err.message : String(err) } };
+            }
+        }
+        if (method !== 'GET')
+            return { status: 405, json: { error: 'method_not_allowed' } };
+        return { status: 200, json: { dir: redactHome(backupsOf(ctx.ws.root)), list: await listBackups(ctx.ws.root), commands: { list: cliLine('cotutor backup list'), restore: cliLine('cotutor backup restore <名字> --yes') } } };
+    }
+    return null;
+}

package/dist/app/http/stage.js

@@ -1,6 +1,6 @@
 /**
- * 舞台包的静态文件:dist/stage/(esbuild 打的 stage.js / stage.css / index.html)+ /stage/fonts/(excalidraw 的字体:dist/stage/fonts/ 在就给它,
- * 不在从 node_modules 现取;部署包把字体拷进 dist/stage/fonts/、去掉 excalidraw 依赖,见 docs/wip/deploy/)。
+ * 舞台包的静态文件:dist/stage/(esbuild 打的 stage.js / stage.css / index.html)+ /stage/fonts/(excalidraw 的字体)。
+ * 字体由 build:stage 拷进 dist/stage/fonts/,npm 装的包里没有 excalidraw(它只在打包时用);开发时没打包就从 node_modules 现取。
  * serve 与 mock 共用;没打包(开发时没跑 pnpm run build:stage)→ null,页面开重卡舞台时什么都不出现,doctor 点名。
  */
 import { existsSync } from 'node:fs';

package/dist/app/mock/mock.js

@@ -74,6 +74,7 @@ import { kidThreads } from "../../runtime/kid-view.js";
 import { ICON_SIZES, appIconPng, webManifest } from "../../ui/shared/icon.js";
 import { faviconResponse } from "../../ui/shared/favicon.js";
 import { kidPage } from "../../ui/kid/kid-page.js";
+import { KID_SW_JS } from "../../ui/kid/offline-sw.js";
 import { parentPage } from "../../ui/parent/parent-page.js";
 import { arrangeHome, homeOwners, kidButtons, kidTiles, parseHome } from "../../runtime/home/home.js";
 import { packageTheme } from "../cli/themes.js";
@@ -644,6 +645,8 @@ export function createMock(opts = {}) {
             return { status: 200, html: VOICE_GALLERY_PAGE };
         if (p === '/manifest.webmanifest')
             return { status: 200, json: webManifest(title), contentType: 'application/manifest+json; charset=utf-8' };
+        if (p === '/sw.js')
+            return { status: 200, body: Buffer.from(KID_SW_JS), contentType: 'text/javascript; charset=utf-8', cacheControl: 'no-cache' };
         // 家长端「记录」:自己的一页(parent-page.ts);清单接口照真服务(答案不剥,第一节带一条给家长的尾巴与记忆)。mock 没有工作台 /dev
         if (p === '/parent')
             return { status: 200, html: parentPage(title) };

package/dist/memory/vault-notes.d.ts

@@ -20,6 +20,10 @@ export interface VaultNote {
 }
 /** 只认平铺的 `key: value`;值去掉成对引号。没有 frontmatter → {} */
 export declare function frontmatter(md: string): Record<string, string>;
+/** 现在读 grade 年级的孩子,读一年级是哪年 9 月(学年从 9 月算,同下面的 semesterAt;7、8 月算刚读完的那个年级) */
+export declare function schoolStartFor(grade: number, now: Date): string;
+/** 把 school_start 写进档案的 frontmatter:有空着的那行就填,没有就加在第一行 --- 后面;别的一个字不动 */
+export declare function setSchoolStart(md: string, value: string): string;
 /**
  * 某天是几年级的哪个学期 / 假期:9–1 月上学期、2 月寒假、3–6 月下学期、7–8 月暑假(刚读完的那个年级的暑假)。
  * 学年从 9 月算;`school_start` 是读一年级那年的 9 月(写别的月份也按它所在学年算)。年级不在 1–12 → null。

package/dist/memory/vault-notes.js

@@ -30,6 +30,17 @@ export function frontmatter(md) {
     return {};
 }
 const CN_DIGITS = ['', '一', '二', '三', '四', '五', '六', '七', '八', '九', '十', '十一', '十二'];
+/** 现在读 grade 年级的孩子,读一年级是哪年 9 月(学年从 9 月算,同下面的 semesterAt;7、8 月算刚读完的那个年级) */
+export function schoolStartFor(grade, now) {
+    const year = now.getMonth() + 1 >= 9 ? now.getFullYear() : now.getFullYear() - 1;
+    return `${year - (grade - 1)}-09`;
+}
+/** 把 school_start 写进档案的 frontmatter:有空着的那行就填,没有就加在第一行 --- 后面;别的一个字不动 */
+export function setSchoolStart(md, value) {
+    if (/^school_start:.*$/m.test(md))
+        return md.replace(/^school_start:.*$/m, `school_start: ${value}`);
+    return md.replace(/^---\r?\n/, (m) => `${m}school_start: ${value}\n`);
+}
 /**
  * 某天是几年级的哪个学期 / 假期:9–1 月上学期、2 月寒假、3–6 月下学期、7–8 月暑假(刚读完的那个年级的暑假)。
  * 学年从 9 月算;`school_start` 是读一年级那年的 9 月(写别的月份也按它所在学年算)。年级不在 1–12 → null。

package/dist/shared/upgrade.d.ts

@@ -3,6 +3,8 @@
 export declare const UPGRADE_STEPS: readonly ["cotutor update"];
 /** 给家长看的那份。Windows 上带 .cmd:PowerShell 缺省禁止跑脚本,不带后缀找到的是被拦的 .ps1,一跑就报错;.cmd 在 PowerShell 和 cmd.exe 里都能跑(2026-11-07 真机) */
 export declare function upgradeSteps(platform?: NodeJS.Platform): string[];
+/** 给家长抄的一条命令:Windows 上第一个词带 .cmd,原因同上 */
+export declare function cliLine(cmd: string, platform?: NodeJS.Platform): string;
 /** 正式版的版本号。预发布不算;从网上拿来的还要显示给家长,其余一律不认 */
 export declare function isPlainVersion(v: unknown): v is string;
 /** a 比 b 新;任一边不是正式版的版本号 → false,宁可不提醒 */

package/dist/shared/upgrade.js

@@ -3,7 +3,11 @@
 export const UPGRADE_STEPS = ['cotutor update'];
 /** 给家长看的那份。Windows 上带 .cmd:PowerShell 缺省禁止跑脚本,不带后缀找到的是被拦的 .ps1,一跑就报错;.cmd 在 PowerShell 和 cmd.exe 里都能跑(2026-11-07 真机) */
 export function upgradeSteps(platform = process.platform) {
-    return UPGRADE_STEPS.map((s) => (platform === 'win32' ? s.replace(' ', '.cmd ') : s));
+    return UPGRADE_STEPS.map((s) => cliLine(s, platform));
+}
+/** 给家长抄的一条命令:Windows 上第一个词带 .cmd,原因同上 */
+export function cliLine(cmd, platform = process.platform) {
+    return platform === 'win32' ? cmd.replace(/^(cotutor|npm)(?= |$)/, '$1.cmd') : cmd;
 }
 const PLAIN = /^(\d+)\.(\d+)\.(\d+)$/;
 /** 正式版的版本号。预发布不算;从网上拿来的还要显示给家长,其余一律不认 */