mosage 0.2.0 → 0.8.0

package/README.md

@@ -1,28 +1,29 @@
 # mosage
 
-**English** · [繁體中文](README.zh-TW.md)
-
-Scaffold an [MoSage](https://github.com/nickchen1998/MoSage) workspace — documents as React, one component per printed page.
+讓 AI coding agent 幫你做出要印出來、要交出去的文件：報告、企劃書、白皮書、手冊。
+Agent 把內容寫成頁面，MoSage 負責紙張尺寸、分頁、目錄與頁碼，並匯出 PDF、可編輯的 Word 或 HTML。
 
 ```bash
 npx mosage init my-docs
 cd my-docs
-pnpm dev
+npm run dev        # http://localhost:5273
 ```
 
-The scaffolded workspace ships with the `create-doc` and `doc-authoring` agent skills preconfigured (`.agents/skills`, linked into `.claude/skills`), a sample document, and the `mosage` dev/build/preview scripts.
+接著在同一個資料夾開啟 Claude Code 或 Codex，描述你要的文件即可。
 
-It also writes a `pnpm-workspace.yaml` allowing esbuild's postinstall to run. pnpm blocks build scripts by default and Vite cannot start without that one; the file is inert under npm, yarn, and bun.
+## 這個套件包含
 
-## Flags
+- **CLI**：`mosage init`（建立專案）、`dev`、`check`（版面檢查）、`export`（PDF／Word／HTML／PNG）、`import`（Markdown 轉文件）、`build`、`preview`、`sync:skills`
+- **檢視器**：真實尺寸的頁面、縮圖與大綱、單頁／雙頁／格狀檢視、Inspect（直接改字或留言給 AI）、Design 面板
+- **文件元件**：`flow()` 自動分頁、`TableOfContents`、`Footnote`、`Figure`／`Ref` 編號與交互參照、`DataTable`（讀 CSV）、頁碼 hooks
+- **AI skills**：`create-doc`、`doc-authoring`、`current-doc`、`apply-comments`、`create-theme`
 
+`mosage check` 與 `mosage export` 會用無頭 Chromium 渲染，第一次使用前請安裝 Playwright：
+
+```bash
+npm i -D playwright && npx playwright install chromium
 ```
-mosage init [dir]
-  -f, --force        overwrite a non-empty target directory
-  -n, --name <name>  package name (defaults to the folder name)
-  --use-pnpm         (or --use-npm / --use-yarn / --use-bun)
-  --no-install       skip dependency installation
-  --no-git           skip git init and the initial commit
-```
 
-MIT
+完整說明與範例：<https://github.com/nickchen1998/MoSage>
+
+MoSage 以 [open-doc](https://github.com/simonliu-ai-product/open-doc)（Simon Liu，MIT）為基礎開發。授權：MIT。

package/bin.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import './dist/cli/bin.js';

package/dist/build-C7NW_3Pk.js

@@ -0,0 +1,14 @@
+import { t as createViteConfig } from "./config-DPm1BBAb.js";
+import path from "node:path";
+import { build as build$1, mergeConfig } from "vite";
+//#region src/cli/build.ts
+async function build(opts = {}) {
+	const base = await createViteConfig({
+		userCwd: process.cwd(),
+		mode: "build"
+	});
+	const config = mergeConfig(base, { build: { ...opts.outDir !== void 0 ? { outDir: path.resolve(process.cwd(), opts.outDir) } : {} } });
+	await build$1(config);
+}
+//#endregion
+export { build };

package/dist/check-CP4873Wx.js

@@ -0,0 +1,41 @@
+import { i as listDocIds } from "./config-DPm1BBAb.js";
+import { n as checkLayout, r as closeRenderSession, t as cliContext } from "./context-BqsdSrAQ.js";
+import chalk from "chalk";
+//#region src/cli/check.ts
+function line(finding) {
+	const where = finding.page > 0 ? `p.${finding.page}` : "doc";
+	const mark = finding.severity === "error" ? chalk.red("✗") : chalk.yellow("!");
+	const detail = [finding.element, finding.loc && chalk.dim(`@ ${finding.loc}`)].filter(Boolean).join("  ");
+	return `  ${mark} ${chalk.dim(where.padEnd(5))} ${finding.message}${detail ? `\n      ${chalk.dim(detail)}` : ""}`;
+}
+/**
+* Renders every sheet at true page size and reports the layout faults an agent
+* writing React cannot see: content clipped by the page edge, an empty sheet, a
+* heading stranded at the foot of a page, type too small to print.
+*
+* Exits non-zero when anything is an error, so it works as a CI gate.
+*/
+async function checkDocs(docIds, opts = {}) {
+	const ctx = await cliContext();
+	const targets = docIds.length > 0 ? docIds : await listDocIds(ctx);
+	if (targets.length === 0) throw new Error("No documents found under docs/.");
+	let errors = 0;
+	const reports = [];
+	try {
+		for (const docId of targets) {
+			const report = await checkLayout(ctx, docId);
+			reports.push(report);
+			errors += report.errors;
+			if (opts.json) continue;
+			const summary = report.errors === 0 && report.warnings === 0 ? chalk.green("clean") : [report.errors > 0 ? chalk.red(`${report.errors} error(s)`) : "", report.warnings > 0 ? chalk.yellow(`${report.warnings} warning(s)`) : ""].filter(Boolean).join(", ");
+			process.stdout.write(`${chalk.bold(docId)} ${chalk.dim(`${report.pageCount} pages`)} — ${summary}\n`);
+			for (const finding of report.findings) process.stdout.write(`${line(finding)}\n`);
+		}
+	} finally {
+		await closeRenderSession();
+	}
+	if (opts.json) process.stdout.write(`${JSON.stringify(reports, null, 2)}\n`);
+	if (errors > 0) process.exitCode = 1;
+}
+//#endregion
+export { checkDocs };

package/dist/cli/bin.d.ts

@@ -0,0 +1 @@
+export {}

package/dist/cli/bin.js

@@ -0,0 +1,228 @@
+#!/usr/bin/env node
+import { a as PAGE_SIZE_NAMES, r as ORIENTATIONS } from "../sdk-DjpX6mCv.js";
+import chalk from "chalk";
+import path from "node:path";
+import * as readline from "node:readline/promises";
+import { fileURLToPath } from "node:url";
+import { Command, Option } from "commander";
+import { existsSync, readFileSync } from "node:fs";
+import fs, { readFile } from "node:fs/promises";
+//#region \0rolldown/runtime.js
+var __defProp = Object.defineProperty;
+var __exportAll = (all, no_symbols) => {
+	let target = {};
+	for (var name in all) __defProp(target, name, {
+		get: all[name],
+		enumerable: true
+	});
+	if (!no_symbols) __defProp(target, Symbol.toStringTag, { value: "Module" });
+	return target;
+};
+//#endregion
+//#region src/ops/formats.ts
+/** Kept apart from `layout.ts`, so the CLI can list the choices without loading the renderer. */
+const EXPORT_FORMATS = [
+	"pdf",
+	"html",
+	"docx",
+	"png"
+];
+//#endregion
+//#region src/cli/package-version.ts
+const PACKAGE_NAME = "mosage";
+/**
+* This package's root folder (the one holding its own `package.json`, the
+* `template/` and `skills/`). Walks up instead of assuming a fixed depth: the
+* bundler decides which chunk a module lands in, so `../../` is right from
+* `dist/cli/` and wrong from `dist/`.
+*/
+function packageRoot() {
+	let dir = path.dirname(fileURLToPath(import.meta.url));
+	for (let up = 0; up < 6; up += 1) {
+		const file = path.join(dir, "package.json");
+		if (existsSync(file)) try {
+			if (JSON.parse(readFileSync(file, "utf8")).name === PACKAGE_NAME) return dir;
+		} catch {}
+		const parent = path.dirname(dir);
+		if (parent === dir) break;
+		dir = parent;
+	}
+	return null;
+}
+/** Getting the root wrong is silent — it reports `0.0.0` rather than failing. */
+async function readCoreVersion() {
+	const root = packageRoot();
+	if (!root) return "0.0.0";
+	try {
+		return JSON.parse(await readFile(path.join(root, "package.json"), "utf8")).version ?? "0.0.0";
+	} catch {
+		return "0.0.0";
+	}
+}
+//#endregion
+//#region src/cli/sync.ts
+var sync_exports = /* @__PURE__ */ __exportAll({
+	detectSkillsDrift: () => detectSkillsDrift,
+	syncSkills: () => syncSkills
+});
+const SKILL_TARGET_DIRS = [".agents/skills", ".claude/skills"];
+async function listFiles(dir) {
+	const out = [];
+	const walk = async (current) => {
+		const entries = await fs.readdir(current, { withFileTypes: true });
+		for (const entry of entries) {
+			const abs = path.join(current, entry.name);
+			if (entry.isDirectory()) await walk(abs);
+			else out.push(path.relative(dir, abs));
+		}
+	};
+	await walk(dir);
+	return out.sort();
+}
+async function sameTree(src, dst) {
+	if (!existsSync(dst)) return false;
+	const [srcFiles, dstFiles] = await Promise.all([listFiles(src), listFiles(dst)]);
+	if (srcFiles.length !== dstFiles.length) return false;
+	if (srcFiles.some((f, i) => f !== dstFiles[i])) return false;
+	for (const rel of srcFiles) {
+		const [a, b] = await Promise.all([fs.readFile(path.join(src, rel), "utf8"), fs.readFile(path.join(dst, rel), "utf8")]);
+		if (a !== b) return false;
+	}
+	return true;
+}
+async function skillNames(builtinDir) {
+	if (!existsSync(builtinDir)) return [];
+	return (await fs.readdir(builtinDir, { withFileTypes: true })).filter((e) => e.isDirectory()).map((e) => e.name).sort();
+}
+async function detectSkillsDrift(builtinDir, userCwd = process.cwd()) {
+	const names = await skillNames(builtinDir);
+	const primaryTarget = path.join(userCwd, SKILL_TARGET_DIRS[0]);
+	const drift = [];
+	for (const name of names) {
+		const src = path.join(builtinDir, name);
+		const dst = path.join(primaryTarget, name);
+		if (!existsSync(dst)) drift.push({
+			name,
+			status: "added"
+		});
+		else if (!await sameTree(src, dst)) drift.push({
+			name,
+			status: "updated"
+		});
+		else drift.push({
+			name,
+			status: "unchanged"
+		});
+	}
+	return drift;
+}
+async function syncSkills(builtinDir, opts = {}, userCwd = process.cwd()) {
+	const stale = (await detectSkillsDrift(builtinDir, userCwd)).filter((d) => d.status !== "unchanged");
+	if (stale.length === 0) {
+		if (!opts.quiet) process.stdout.write(`${chalk.green("✔")} Skills already up to date.\n`);
+		return;
+	}
+	for (const { name, status } of stale) {
+		if (opts.dryRun) {
+			process.stdout.write(`${chalk.yellow("~")} ${name} ${chalk.dim(`(${status})`)}\n`);
+			continue;
+		}
+		for (const targetDir of SKILL_TARGET_DIRS) {
+			const dst = path.join(userCwd, targetDir, name);
+			await fs.rm(dst, {
+				recursive: true,
+				force: true
+			});
+			await fs.mkdir(path.dirname(dst), { recursive: true });
+			await fs.cp(path.join(builtinDir, name), dst, { recursive: true });
+		}
+		if (!opts.quiet) process.stdout.write(`${chalk.green("✔")} ${name} ${chalk.dim(`(${status})`)}\n`);
+	}
+	if (opts.dryRun) process.stdout.write(chalk.dim("\nDry run — nothing written.\n"));
+}
+//#endregion
+//#region src/cli/run.ts
+function parsePort(value) {
+	const n = Number(value);
+	if (!Number.isInteger(n) || n < 0 || n > 65535) throw new Error(`Invalid port: ${value}`);
+	return n;
+}
+function resolveBuiltinSkillsDir() {
+	const here = path.dirname(fileURLToPath(import.meta.url));
+	return path.resolve(here, "..", "..", "skills");
+}
+async function runSkillsDriftCheck(skillsDir) {
+	if (process.env.OPEN_DOC_SKIP_SKILLS_CHECK === "1") return;
+	let drift;
+	try {
+		drift = await detectSkillsDrift(skillsDir);
+	} catch {
+		return;
+	}
+	const stale = drift.filter((d) => d.status !== "unchanged");
+	if (stale.length === 0) return;
+	const names = stale.map((d) => d.name).join(", ");
+	if (!Boolean(process.stdin.isTTY && process.stdout.isTTY)) {
+		process.stderr.write(`${chalk.yellow("!")} Skills out of date (${names}). Run \`mosage sync:skills\` to update.\n`);
+		return;
+	}
+	const rl = readline.createInterface({
+		input: process.stdin,
+		output: process.stdout
+	});
+	try {
+		const answer = (await rl.question(`${chalk.yellow("!")} Skills out of date: ${chalk.bold(names)}. Sync now? ${chalk.dim("(Y/n) ")}`)).trim().toLowerCase();
+		if (answer === "" || answer === "y" || answer === "yes") await syncSkills(skillsDir);
+		else process.stdout.write(chalk.dim("Skipped. Run `mosage sync:skills` later to update.\n"));
+	} finally {
+		rl.close();
+	}
+}
+async function run(argv) {
+	const version = await readCoreVersion();
+	const program = new Command();
+	program.name("mosage").description("Author documents — we handle the Vite/React stack, pagination, and export.").version(version, "-v, --version", "print version").helpOption("-h, --help", "show help").showHelpAfterError(chalk.dim("(run `mosage --help` for usage)"));
+	program.command("init").description("Create a new MoSage workspace").argument("[dir]", "target directory", void 0).option("-f, --force", "overwrite non-empty target directory", false).option("-n, --name <name>", "override package name (defaults to folder name)").option("--use-npm", "use npm to install dependencies").option("--use-pnpm", "use pnpm to install dependencies").option("--use-yarn", "use yarn to install dependencies").option("--use-bun", "use bun to install dependencies").option("--no-install", "skip dependency installation").option("--no-git", "skip git init and initial commit").action(async (dir, flags) => {
+		const { runInit } = await import("../init-Bbtj2pxF.js");
+		await runInit(dir, flags);
+	});
+	program.command("dev").description("Start the dev server").addOption(new Option("-p, --port <port>", "port to listen on").argParser(parsePort)).addOption(new Option("--host [host]", "expose on the network (optional host)")).option("--open", "open the browser on start").option("--no-skills-check", "skip the built-in skills drift check").action(async (flags) => {
+		if (flags.skillsCheck !== false) await runSkillsDriftCheck(resolveBuiltinSkillsDir());
+		const { dev } = await import("../dev-Biz42qlu.js");
+		await dev(flags);
+	});
+	program.command("build").description("Build a static site").option("--out-dir <dir>", "output directory (defaults to `dist`)").action(async (flags) => {
+		const { build } = await import("../build-C7NW_3Pk.js");
+		await build(flags);
+	});
+	program.command("preview").description("Preview the production build").addOption(new Option("-p, --port <port>", "port to listen on").argParser(parsePort)).addOption(new Option("--host [host]", "expose on the network (optional host)")).option("--open", "open the browser on start").action(async (flags) => {
+		const { preview } = await import("../preview-CLm51aRt.js");
+		await preview(flags);
+	});
+	program.command("export [docIds...]").description("Render documents headlessly to PDF, HTML, DOCX, or PNG").addOption(new Option("-f, --format <format>", "output format").choices(EXPORT_FORMATS)).option("-o, --out-dir <dir>", "directory to write into (defaults to `out`)").option("--all", "export every document under docs/").action(async (docIds, flags) => {
+		const { exportDocs } = await import("../export-Bi6nuxjT.js");
+		await exportDocs(docIds, flags);
+	});
+	program.command("check [docIds...]").description("Report layout faults — clipped content, blank sheets, stranded headings").option("--json", "print the full report as JSON").action(async (docIds, flags) => {
+		const { checkDocs } = await import("../check-CP4873Wx.js");
+		await checkDocs(docIds, flags);
+	});
+	program.command("import <file>").description("Turn a Markdown file into a document under docs/").option("--id <id>", "document id (defaults to a slug of the title)").option("--title <title>", "override the title").option("--subtitle <subtitle>", "subtitle, also used as the cover eyebrow").option("--author <author>", "author line on the cover").option("--theme <theme>", "theme id to back-link from meta.theme").addOption(new Option("--page-size <size>", "page size").choices(PAGE_SIZE_NAMES)).addOption(new Option("--orientation <orientation>", "page orientation").choices(ORIENTATIONS)).option("--no-cover", "skip the title page").option("--contents", "add a self-filling contents page").action(async (file, flags) => {
+		const { importDoc } = await import("../import-D2jNB07F.js");
+		await importDoc(file, flags);
+	});
+	program.command("sync:skills").description("Sync built-in skills from mosage into this workspace").option("--dry-run", "show what would change without writing").action(async (flags) => {
+		const { syncSkills } = await Promise.resolve().then(() => sync_exports);
+		await syncSkills(resolveBuiltinSkillsDir(), flags);
+	});
+	await program.parseAsync(argv, { from: "user" });
+}
+//#endregion
+//#region src/cli/bin.ts
+run(process.argv.slice(2)).catch((err) => {
+	const message = err instanceof Error ? err.message : String(err);
+	process.stderr.write(`${chalk.red("error:")} ${message}\n`);
+	process.exit(1);
+});
+//#endregion
+export { EXPORT_FORMATS as i, packageRoot as n, readCoreVersion as r, syncSkills as t };