@qnroa/qtype 0.0.1

package/docs/zh/authoring.md

@@ -0,0 +1,131 @@
+# 撰写 material 文件
+
+English: [authoring.md](../en/authoring.md)
+
+`material/*.md` 的快速入门。权威规范见
+[`templates/zh/QTYPE.md`](../../templates/zh/QTYPE.md)
+（`qtype init --lang zh` 时拷到新 repo）。有疑问先查那份。
+
+## 文件位置
+
+```
+my-deck/
+├── QTYPE.md              # 规范（init 时自动拷贝；留着）
+├── index.md              # 面向人的目录（可选）
+├── material/
+│   ├── example.md
+│   ├── javascript-basics.md
+│   └── english-vocab.md
+└── .qtype/
+    └── config.json       # 单 repo 配置
+```
+
+一个 `.md` 文件 = 一副卡组。
+
+## 卡片形状
+
+每张卡有一个问题和一个答案，用 `## Q:` / `## A:` 标题分隔。同一文件里
+的多张卡用 `\n\n---\n\n`（独占一行的 `---`，前后各留空行）分隔。
+
+```markdown
+---
+tags: [js, basics]
+type: normal
+---
+
+## Q:
+
+React 三大核心概念是什么？
+
+## A:
+
+组件、props 和 state。
+
+---
+
+## Q:
+
+`useState` 返回什么？
+
+## A:
+
+一个 `[值, setter]` 的元组。
+```
+
+parser 先按 `---` 分割，再逐卡提取 Q、A、metadata。缺 Q 或 A 的卡片被
+静默丢弃（方便写占位）。
+
+## Frontmatter 字段
+
+文件顶部的 YAML frontmatter 对文件内每张卡都生效。如需单卡覆盖，把
+YAML fence 放到该卡上方（见规范）。
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `tags` | `string[]` | 自由形式；用于列表过滤 |
+| `type` | `normal \| word \| sentence` | 默认 `normal` |
+| `hint` | `none \| ghost` | 下方是否显示褪色目标 |
+| `difficulty` | `1..5` | 可选，信息用 |
+| `phonetic` | `string` | `type: word` 用 —— IPA / 拼音 |
+| `gloss` | `string` | `type: word` 用 —— 释义 |
+| `translation` | `string` | `type: sentence` 用 —— 目标语等价句 |
+
+示例 —— 一张 `word` 卡：
+
+```markdown
+---
+type: word
+phonetic: /ˈklō-zhər/
+gloss: 捕获词法作用域的函数
+---
+
+## Q:
+
+closure
+
+## A:
+
+closure
+```
+
+## 被打字的是什么？
+
+**答案**是用户要打的内容。Q 只做提示（不打）。代码块、行内代码、多行
+答案都支持 —— 打字引擎按归一化后的答案逐 codepoint 迭代。
+
+引擎处理不了的字符（比如某些代理对 emoji）会出现在 `qtype check`
+输出里。发布前修掉或删掉。
+
+## 跑 `qtype check`
+
+发布前始终跑：
+
+```bash
+qtype check
+```
+
+它报告：
+- `material/` 目录不存在（致命）
+- 含无法打字字符的卡片（致命，附逐卡列表）
+
+退出码 0 = 可以安全发布。
+
+## 发布
+
+```bash
+qtype publish build
+qtype publish serve            # http://localhost:4000
+```
+
+密码保护的卡组：
+
+```bash
+qtype publish password set     # 写入 repo 配置
+qtype publish build            # 出栈时加密 material
+```
+
+## 完整规范在哪
+
+以上是 80% 的用法。少见场景（单卡 frontmatter 覆盖、准确的空白处理、
+分隔规则边界情形、跨文件引用）见
+[`templates/zh/QTYPE.md`](../../templates/zh/QTYPE.md)。

package/docs/zh/cli-reference.md

@@ -0,0 +1,162 @@
+# qtype CLI 简介
+
+English: [cli-reference.md](../en/cli-reference.md)
+
+每个顶层命令的简单介绍。跑 `qtype <cmd> --help` 看完整选项。
+
+## 全局选项
+
+| 选项 | 说明 |
+|---|---|
+| `-h, --help` | 显示帮助 |
+| `-v, --version` | 显示版本 |
+| `--lang <zh\|en>` | 本次调用的 UI 语言 |
+
+语言优先级：`--lang` > `$QTYPE_LANG` > `~/.config/qtype/config.json` 里的
+`cli.lang` > 系统 locale。
+
+---
+
+## `qtype init [dir]`
+
+在已有目录里搭起 material 仓库脚手架。`qtype repo sync` 的别名，形态一致。
+
+```bash
+qtype init                    # 当前目录
+qtype init my-deck --lang en  # 在 ./my-deck 下用英文模板
+```
+
+创建：`QTYPE.md`（撰写规范）、`AGENTS.md` / `CLAUDE.md` / `GEMINI.md`
+（指向 `QTYPE.md` 的软链）、`README.md`、`TODO.md`、`index.md`、
+`log.md`、含 example 的 `material/`、`.qtype/` 骨架。
+
+幂等 —— 跳过已有的用户内容，只有 `--force` 会覆盖 qtype 管理的规范文件。
+
+---
+
+## `qtype repo new <name>`
+
+新建一个 material 仓库目录。
+
+```bash
+qtype repo new my-deck --lang zh
+cd my-deck
+```
+
+## `qtype repo sync [dir]`
+
+在已有 repo 里补齐约定。与 `qtype init` 相同。
+
+---
+
+## `qtype check [dir]`
+
+校验 `material/*.md` 里的每张卡。报告含打字引擎无法处理字符的卡片
+（返回非零码）。只读；建议在 CI 里放在 `publish build` 前面。
+
+```bash
+qtype check
+```
+
+---
+
+## `qtype publish build [dir]`
+
+拼装静态站到 `dist/`。执行：
+
+1. 解析每个 `material/*.md`
+2. 预渲染 Mermaid 图（除非 `publish.mermaid=off`）
+3. 加密 material（如果 `publish.password.enabled=true`）
+4. 输出每份 material 的 HTML + `_data/material.json`
+5. 把预构建的 view bundle 拷到 `dist/_app/`
+
+```bash
+qtype publish build
+```
+
+## `qtype publish serve [dir]`
+
+本地 HTTP 预览 `dist/`。默认端口 4000。
+
+```bash
+qtype publish serve
+qtype publish serve --port 8080
+```
+
+## `qtype publish init`
+
+写 `.gitignore` + GitHub Pages workflow，push 到 `main` 就触发构建 + 部署。
+
+## `qtype publish password set / clear / status`
+
+密码保护生命周期。`set` 会提示输入密码，用 Argon2id 派生 AES 密钥，
+把结果 salt + hash 写到 `.qtype/config.json`。`clear` 关闭保护。
+
+```bash
+qtype publish password set
+qtype publish password status
+```
+
+---
+
+## `qtype pack [-o file]`
+
+把当前 material 仓库打成 `.tar.gz`。忽略 `dist/`、`node_modules/`、
+`.git/` 以及任何已存在的 tarball。
+
+```bash
+qtype pack -o my-deck.tar.gz
+```
+
+---
+
+## `qtype content lint | validate | search`
+
+- `lint` —— material 文件的样式级 pass
+- `validate` —— schema 级 pass；`qtype check` 的补充
+- `search <query>` —— 卡片全量子串搜索
+
+```bash
+qtype content search "closure"
+```
+
+---
+
+## `qtype config get / set / unset / list`
+
+git 风格的双层配置（user 层在 `~/.config/qtype/config.json`，repo 层
+在 `<repo>/.qtype/config.json`）。
+
+读优先级：repo > user > schema default。写入默认：repo-scope 键写到
+repo，user-only 键写到 user，双层键优先写 repo。
+
+```bash
+qtype config set cli.lang zh --global
+qtype config set typing.theme mocha
+qtype config get typing.theme --show-origin
+qtype config list
+qtype config unset typing.targetWpm
+```
+
+已知的键包括：
+
+- `cli.lang`、`cli.color`（user-only）
+- `repo.name`、`publish.password.*`（repo-only）
+- `repo.lang`、`typing.theme`、`typing.targetWpm`、`typing.tabBehavior`、
+  `typing.hint`、`typing.showKeyboard`、`typing.showHands`、
+  `publish.mermaid`（双 scope）
+
+严格模式：未知键会被拒绝。
+
+---
+
+## `qtype plugin`
+
+命令骨架。运行时执行尚未实现 —— 见 [TODO.zh.md](../../TODO.zh.md)。
+
+---
+
+## 退出码
+
+- `0` —— 成功
+- `1` —— 校验 / lint / 构建失败，或任何抛出的错误

package/package.json

@@ -0,0 +1,85 @@
+{
+  "name": "@qnroa/qtype",
+  "version": "0.0.1",
+  "description": "Turn Markdown notes into typing practice — CLI + review + static-site publisher",
+  "keywords": [
+    "typing",
+    "typing-practice",
+    "typing-test",
+    "markdown",
+    "cli",
+    "static-site-generator",
+    "spaced-repetition",
+    "chinese-typing",
+    "pinyin",
+    "qrism"
+  ],
+  "license": "Apache-2.0",
+  "author": "Qnroa",
+  "homepage": "https://www.npmjs.com/package/@qnroa/qtype",
+  "engines": {
+    "node": ">=20"
+  },
+  "type": "module",
+  "bin": {
+    "qtype": "./dist/cli/index.js"
+  },
+  "files": [
+    "dist",
+    "templates",
+    "docs",
+    "CHANGELOG.md",
+    "CHANGELOG.zh.md",
+    "README.md",
+    "README.zh.md",
+    "LICENSE",
+    "!dist/**/*.js.map",
+    "!dist/**/*.d.ts.map",
+    "!docs/**/release.md",
+    "!docs/**/cli-internals.md",
+    "!docs/**/architecture.md",
+    "!docs/**/core-architecture.md",
+    "!docs/**/cli-architecture.md",
+    "!docs/**/view-architecture.md"
+  ],
+  "exports": {
+    "./core": "./dist/core/index.js",
+    "./cli": "./dist/cli/index.js"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.cli.json && chmod +x dist/cli/index.js",
+    "build:view": "vite build",
+    "build:all": "npm run build && npm run build:view",
+    "dev:view": "vite",
+    "test": "vitest --run",
+    "test:watch": "vitest",
+    "lint": "tsc --noEmit -p tsconfig.cli.json && tsc --noEmit -p tsconfig.view.json",
+    "clean": "rm -rf dist",
+    "prepublishOnly": "npm run clean && npm run build:all && npm test"
+  },
+  "dependencies": {
+    "@noble/hashes": "^2.2.0",
+    "commander": "^15.0.0",
+    "mermaid": "^11.15.0",
+    "pinyin-pro": "^3.29.1",
+    "puppeteer": "^25.4.0"
+  },
+  "devDependencies": {
+    "@radix-ui/react-dialog": "^1.1.23",
+    "@tanstack/react-router": "^1.170.29",
+    "@tanstack/router-plugin": "^1.168.32",
+    "@types/node": "^26.2.0",
+    "@types/react": "^18.3.11",
+    "@types/react-dom": "^18.3.0",
+    "@vitejs/plugin-react": "^4.3.2",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
+    "react-resizable-panels": "^4.12.2",
+    "typescript": "^5.6.2",
+    "vite": "^5.4.8",
+    "vitest": "^2.1.2"
+  }
+}