cotutor 0.1.0 → 0.3.0

package/dist/app/cli/chalk/snap.js

@@ -0,0 +1,103 @@
+/**
+ * snap:阶梯层 4 —— 起临时页面服务(./serve.ts)与本机 Chrome(./browser.ts),逐步打开舞台的 ?chalk=snap&step=<n> 截 keyframe。
+ * 走真浏览器 + 孩子端同一个渲染(src/ui/stage/chalk/render.ts 画烤好的画面):截到的和孩子看到的零偏差。
+ * 产物:<out>/step-<n>.png(n=0 空板起,0 号图配题面)+ index.json(图↔讲稿对照,给检验 skill 吃)。
+ * index.json 里每张图还带该步新增元素清单(id/type/color/text/bbox)与画板 viewBox:
+ * 检验方不读源码也能按 id 报问题、按坐标核对计数与越界。
+ * `--step n` 只重截一步时,index.json 与已有内容合并(只换那一步),不覆盖整份对照表。
+ */
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { basename, join } from 'node:path';
+import { bboxOf } from "../../../chalk/check.js";
+import { isAction, resolveActions } from "../../../chalk/actions.js";
+import { withBrowser } from "./browser.js";
+import { startPageServer } from "./serve.js";
+const VIEWBOX_EXPR = `document.querySelector('#chalk-snap svg')?.getAttribute('viewBox') ?? null`;
+function describe(el, erases) {
+    if (isAction(el))
+        return { id: el.id, type: el.type, erases: erases ?? [] };
+    const b = bboxOf(el);
+    const out = {
+        id: el.id,
+        type: el.type,
+        bbox: { x: round(b.minX), y: round(b.minY), w: round(b.maxX - b.minX), h: round(b.maxY - b.minY) },
+    };
+    if (typeof el.strokeColor === 'string')
+        out.strokeColor = el.strokeColor;
+    if (typeof el.backgroundColor === 'string' && el.backgroundColor !== 'transparent') {
+        out.backgroundColor = el.backgroundColor;
+        if (typeof el.fillStyle === 'string')
+            out.fillStyle = el.fillStyle;
+    }
+    if (typeof el.strokeStyle === 'string' && el.strokeStyle !== 'solid')
+        out.strokeStyle = el.strokeStyle;
+    if (el.type === 'text' && typeof el.text === 'string')
+        out.text = el.text;
+    return out;
+}
+const round = (n) => Math.round(n * 10) / 10;
+function parseViewBox(s) {
+    if (!s)
+        return null;
+    const nums = s.trim().split(/[\s,]+/).map(Number);
+    if (nums.length !== 4 || nums.some((n) => !Number.isFinite(n)))
+        return null;
+    return { viewBox: [nums[0], nums[1], nums[2], nums[3]] };
+}
+/** 读已有 index.json(同一场景才合并;读不到或格式不对就当没有) */
+async function readExistingIndex(outDir, sceneId) {
+    try {
+        const raw = JSON.parse(await readFile(join(outDir, 'index.json'), 'utf8'));
+        if (raw.schema !== 'drawtell-snaps' || raw.scene !== sceneId || !Array.isArray(raw.shots))
+            return null;
+        return raw;
+    }
+    catch {
+        return null;
+    }
+}
+export async function snapScene({ scene, bundlesDir, outDir, step, cursor = true }) {
+    const byId = new Map(scene.skeletons.map((e) => [e.id, e]));
+    const acts = resolveActions(scene.skeletons, scene.background);
+    const addedOf = (n) => n === 0 ? [] : scene.steps[n - 1].elementIds.map((id) => byId.get(id)).filter((e) => !!e).map((e) => describe(e, acts.targets.get(e.id)));
+    const server = await startPageServer(bundlesDir);
+    try {
+        return await withBrowser(async (page) => {
+            const stepNums = step != null ? [step] : Array.from({ length: scene.steps.length + 1 }, (_, i) => i);
+            await mkdir(outDir, { recursive: true });
+            const shots = [];
+            let board = null;
+            for (const n of stepNums) {
+                await page.goto(`${server.origin}/stage/?chalk=snap&bundle=${encodeURIComponent(`/api/bundles/${scene.id}/`)}&step=${n}${cursor ? '' : '&cursor=0'}`);
+                await page.waitFor(`document.body.dataset.chalkDone === '1'`, 60_000);
+                const pageErr = await page.evaluate('window.__chalkError ?? null');
+                if (pageErr)
+                    throw new Error(`截图那页出错(step ${n}):${pageErr}`);
+                const vb = parseViewBox(await page.evaluate(VIEWBOX_EXPR));
+                if (!board)
+                    board = vb;
+                const file = join(outDir, `step-${n}.png`);
+                await writeFile(file, await page.screenshot('#chalk-snap'));
+                shots.push({ step: n, file, line: n === 0 ? `(题面)${scene.problem}` : scene.steps[n - 1].line, added: addedOf(n), cursor, ...(vb ? { viewBox: vb.viewBox } : {}) });
+            }
+            // 单步重截:与已有对照表合并,只替换这一步(第一批真题里三组生成方都踩过"覆盖成单条")
+            let merged = shots.map((s) => ({ ...s, file: basename(s.file) }));
+            if (step != null) {
+                const existing = await readExistingIndex(outDir, scene.id);
+                if (existing) {
+                    const others = existing.shots.filter((s) => s.step !== step);
+                    merged = [...others, ...merged].sort((a, b) => a.step - b.step);
+                    if (!board)
+                        board = existing.board ?? null;
+                }
+            }
+            // schema 名照旧(drawtell-snaps):检验技能与已有的截图目录认它
+            const index = { schema: 'drawtell-snaps', version: 2, scene: scene.id, title: scene.title, problem: scene.problem, board, shots: merged };
+            await writeFile(join(outDir, 'index.json'), `${JSON.stringify(index, null, 2)}\n`);
+            return shots;
+        });
+    }
+    finally {
+        await server.close();
+    }
+}

package/dist/app/cli/chalk/typecheck.d.ts

@@ -0,0 +1,7 @@
+import type { Finding } from '../../../chalk/check.ts';
+export interface TypecheckResult {
+    /** false = 类型层没跑(typescript 缺席等),findings 里有一条 warning 说明原因 */
+    ran: boolean;
+    findings: Finding[];
+}
+export declare function typecheckScene(file: string): Promise<TypecheckResult>;

package/dist/app/cli/chalk/typecheck.js

@@ -0,0 +1,51 @@
+/**
+ * 阶梯层 1:类型。`cotutor chalk check` 内嵌 tsc 过一遍场景文件——工作区不需要 tsconfig、不需要自己装 typescript、
+ * 不需要知道类型在哪:场景里的 `import type … from 'cotutor/chalk'` 在这里被映射到包内的类型文件
+ * (仓库内跑是 src/chalk/types.ts,npm 安装后是 dist/chalk/types.d.ts);并进来之前写的 `from 'drawtell'` 照认。
+ * 这是"CLI 中心、工作区只剩源"原则在类型层的落法:以前要求工作区放一个 tsconfig 垫片,现在不用了。
+ * typescript 是 dependency;万一缺席降级为一条 warning,不拦后面几层。
+ */
+import { existsSync } from 'node:fs';
+import { dirname, relative, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+const here = dirname(fileURLToPath(import.meta.url));
+const TYPES = ['../../../chalk/types.ts', '../../../chalk/types.d.ts'].map((p) => resolve(here, p)).find(existsSync);
+export async function typecheckScene(file) {
+    let ts;
+    try {
+        ts = (await import('typescript')).default;
+    }
+    catch {
+        return { ran: false, findings: [{ level: 'warning', rule: 'types-unavailable', message: '类型层未跑:找不到 typescript 包(它是 cotutor 的依赖;重新 pnpm install 即可)。后续各层照常。' }] };
+    }
+    if (!TYPES) {
+        return { ran: false, findings: [{ level: 'warning', rule: 'types-unavailable', message: '类型层未跑:找不到场景的类型文件(chalk/types)。后续各层照常。' }] };
+    }
+    const abs = resolve(file);
+    const options = {
+        noEmit: true,
+        strict: true,
+        skipLibCheck: true,
+        types: [],
+        // DOM 是给仓库内种子场景用的:它们从 ../src/player 引类型,会把播放器(用到 SVG/DOM 类型)一起拉进程序
+        lib: ['lib.esnext.d.ts', 'lib.dom.d.ts', 'lib.dom.iterable.d.ts'],
+        target: ts.ScriptTarget.ESNext,
+        module: ts.ModuleKind.ESNext,
+        moduleResolution: ts.ModuleResolutionKind.Bundler,
+        allowImportingTsExtensions: true,
+        jsx: ts.JsxEmit.ReactJSX,
+        baseUrl: dirname(abs),
+        paths: { 'cotutor/chalk': [TYPES], drawtell: [TYPES] },
+    };
+    const program = ts.createProgram([abs], options);
+    const diags = ts.getPreEmitDiagnostics(program).filter((d) => d.category === ts.DiagnosticCategory.Error);
+    const findings = diags.map((d) => {
+        let where = '';
+        if (d.file && d.start != null) {
+            const { line, character } = d.file.getLineAndCharacterOfPosition(d.start);
+            where = `${relative(process.cwd(), d.file.fileName)}:${line + 1}:${character + 1} `;
+        }
+        return { level: 'error', rule: 'types', message: `${where}TS${d.code}: ${ts.flattenDiagnosticMessageText(d.messageText, '\n')}` };
+    });
+    return { ran: true, findings };
+}

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

@@ -0,0 +1,23 @@
+import { type ResolveOptions, type RootSource } from '../workspace.ts';
+export interface DoctorCheck {
+    name: string;
+    ok: boolean;
+    required: boolean;
+    detail: string;
+    fix?: string;
+}
+export interface DoctorReport {
+    ok: boolean;
+    root: string | null;
+    source: RootSource | null;
+    checks: DoctorCheck[];
+}
+/** 运行时的 CLI 名(run[0] 的 basename) */
+export declare function runtimeCli(run: readonly string[]): string;
+/** 已知的环境坑,从 CLI 的输出里认出来给修复命令(错误信息即修复指南) */
+export declare function explainLlmFailure(text: string, runtime: readonly string[]): string;
+export declare function doctorWorkspace(override?: string, opts?: ResolveOptions & {
+    probeEnv?: boolean;
+    live?: boolean; /** 测试钉时间用:首页「几天前发布的」按它算 */
+    now?: Date;
+}): Promise<DoctorReport>;