@qnroa/qtype 0.0.1

package/dist/cli/commands/publish/init/action.js

@@ -0,0 +1,74 @@
+/**
+ * `qtype publish init` action — scaffold .gitignore + optional GitHub Pages workflow.
+ *
+ * Files:
+ *   - .gitignore                       (always)
+ *   - .github/workflows/pages.yml      (when --ci github)
+ *
+ * Both refuse to overwrite unless --force. Users don't want their
+ * hand-edited workflow silently clobbered when they re-run this after
+ * upgrading qtype.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { error, success } from '../../../utils/output.js';
+import { t } from '../../../i18n/index.js';
+const GITIGNORE = `# qtype
+dist/
+node_modules/
+*.tar.gz
+.DS_Store
+`;
+const GITHUB_YML = `name: Deploy qtype site to Pages
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+concurrency:
+  group: pages
+  cancel-in-progress: true
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+      - run: npx -y @qnroa/qtype publish build --out dist
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: dist
+  deploy:
+    needs: build
+    environment:
+      name: github-pages
+      url: \${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v4
+`;
+function writeIfMissing(target, content, force, cwd) {
+    if (fs.existsSync(target) && !force) {
+        error(t('err.file.exists', { path: path.relative(cwd, target) }));
+        return false;
+    }
+    fs.mkdirSync(path.dirname(target), { recursive: true });
+    fs.writeFileSync(target, content, 'utf8');
+    const rel = path.relative(cwd, target);
+    success(t('publish.init.msg.wrote', { path: rel }));
+    return true;
+}
+export async function publishInitAction(opts = {}) {
+    const cwd = opts.path ? path.resolve(opts.path) : process.cwd();
+    writeIfMissing(path.join(cwd, '.gitignore'), GITIGNORE, opts.force ?? false, cwd);
+    if (opts.ci === 'github') {
+        writeIfMissing(path.join(cwd, '.github', 'workflows', 'pages.yml'), GITHUB_YML, opts.force ?? false, cwd);
+    }
+    success(t('publish.init.msg.done'));
+}

package/dist/cli/commands/publish/init/i18n.js

@@ -0,0 +1,22 @@
+export const messages = {
+    'zh-CN': {
+        'publish.init.summary': '写入 .gitignore 与 GitHub Pages 工作流',
+        'publish.init.description': '给当前资料仓库添加 .gitignore 与 .github/workflows/pages.yml，方便一键部署到 GitHub Pages',
+        'publish.init.arg.path': '仓库路径（默认当前目录）',
+        'publish.init.opt.ci': 'CI 平台（目前仅 github）',
+        'publish.init.example.basic': '只写 .gitignore',
+        'publish.init.example.github': '带 GitHub Pages 部署',
+        'publish.init.msg.wrote': '写入 {path}',
+        'publish.init.msg.done': '发布配置已就绪。git commit + push 后由 Actions 部署。',
+    },
+    'en-US': {
+        'publish.init.summary': 'Write .gitignore and a GitHub Pages workflow',
+        'publish.init.description': 'Add .gitignore and .github/workflows/pages.yml so this repo deploys to GitHub Pages',
+        'publish.init.arg.path': 'Repo path (default: current directory)',
+        'publish.init.opt.ci': 'CI platform (currently github only)',
+        'publish.init.example.basic': 'gitignore only',
+        'publish.init.example.github': 'With GitHub Pages deploy',
+        'publish.init.msg.wrote': 'Wrote {path}',
+        'publish.init.msg.done': 'Publish config ready. Commit + push and Actions will deploy.',
+    },
+};

package/dist/cli/commands/publish/init/index.js

@@ -0,0 +1,26 @@
+import { t } from '../../../i18n/index.js';
+import { messages } from './i18n.js';
+import { publishInitAction } from './action.js';
+export const publishInitCmd = {
+    name: 'init',
+    messages,
+    summary: () => t('publish.init.summary'),
+    describe: () => t('publish.init.description'),
+    args: [{ flag: '[path]', describe: () => t('publish.init.arg.path') }],
+    options: [
+        {
+            flags: '--ci <platform>',
+            describe: () => t('publish.init.opt.ci'),
+            choices: ['github'],
+        },
+        { flags: '--force', describe: () => t('opt.force') },
+    ],
+    examples: () => [
+        { command: 'qtype publish init', describe: () => t('publish.init.example.basic') },
+        { command: 'qtype publish init --ci github', describe: () => t('publish.init.example.github') },
+    ],
+    seeAlso: ['publish build', 'publish serve'],
+    action: async (pathArg, opts) => {
+        await publishInitAction({ path: pathArg, ci: opts.ci, force: opts.force });
+    },
+};

package/dist/cli/commands/publish/password/action.js

@@ -0,0 +1,158 @@
+/**
+ * Implementation of `qtype publish password set|clear|status`.
+ *
+ * Goes through `repoKv` (same store as `qtype config`), so it's identical
+ * to a direct `config set`:
+ *   - Same `.qtype/config.json`
+ *   - Shares JsonStorage's atomic writes + key sorting
+ *   - Avoids ordering-jitter git diffs when the two commands alternate
+ *
+ * Hashing: argon2id via @noble/hashes (pure JS, no native build).
+ * Stored format:
+ *   `argon2id$v=19$m=<memory>,t=<iter>,p=<para>$<saltB64>$<hashB64>`
+ * Modeled on the PHC string format so future tooling can read it.
+ */
+import { randomBytes } from 'node:crypto';
+import { argon2id } from '@noble/hashes/argon2.js';
+import { generateAesSalt } from '../../../../core/encrypt.js';
+import { repoKv as defaultRepoKv, createRepoKv } from '../../../bootstrap.js';
+import { error, success, info } from '../../../utils/output.js';
+import { promptPassword } from '../../../utils/prompt.js';
+import { t } from '../../../i18n/index.js';
+// Argon2id parameters — interactive-login profile per OWASP guidance:
+// 64 MiB memory, 3 iterations, 1 lane, 32-byte output.
+const ARGON2_MEMORY = 64 * 1024; // 64 MiB
+const ARGON2_TIME = 3;
+const ARGON2_PARALLEL = 1;
+const ARGON2_KEY_LEN = 32;
+const ARGON2_SALT_LEN = 16;
+function toB64(u8) {
+    return Buffer.from(u8).toString('base64');
+}
+function fromB64(s) {
+    return new Uint8Array(Buffer.from(s, 'base64'));
+}
+/** Hash a plaintext password with argon2id, return PHC-style storage string. */
+function hashPassword(plaintext) {
+    const salt = randomBytes(ARGON2_SALT_LEN);
+    const hash = argon2id(plaintext, salt, {
+        t: ARGON2_TIME,
+        m: ARGON2_MEMORY,
+        p: ARGON2_PARALLEL,
+        dkLen: ARGON2_KEY_LEN,
+    });
+    return [
+        'argon2id',
+        'v=19',
+        `m=${ARGON2_MEMORY},t=${ARGON2_TIME},p=${ARGON2_PARALLEL}`,
+        toB64(salt),
+        toB64(hash),
+    ].join('$');
+}
+/**
+ * Verify a plaintext against a stored PHC string. Exported (rather than
+ * just exercised in `set`) because `publish build` needs it to check the
+ * password before deriving the AES key.
+ */
+export function verifyPassword(plaintext, stored) {
+    try {
+        const parts = stored.split('$');
+        if (parts.length !== 5 || parts[0] !== 'argon2id')
+            return false;
+        // parts[1]=v=19, parts[2]=m=…,t=…,p=…
+        const params = Object.fromEntries(parts[2].split(',').map((kv) => {
+            const [k, v] = kv.split('=');
+            return [k, Number(v)];
+        }));
+        const salt = fromB64(parts[3]);
+        const expected = fromB64(parts[4]);
+        const got = argon2id(plaintext, salt, {
+            t: params.t,
+            m: params.m,
+            p: params.p,
+            dkLen: expected.length,
+        });
+        if (got.length !== expected.length)
+            return false;
+        let diff = 0;
+        for (let i = 0; i < got.length; i++)
+            diff |= got[i] ^ expected[i];
+        return diff === 0;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Resolve the KvStore to operate on:
+ *   - With a `path` argument → build a fresh one bound to that root
+ *   - Without → use the default cwd-derived singleton
+ */
+function resolveRepoKv(repoPath) {
+    return repoPath ? createRepoKv(repoPath) : defaultRepoKv;
+}
+async function ensureRepo(kv) {
+    if (await kv.available())
+        return true;
+    error(t('err.file.notFound', { path: '.qtype/config.json' }));
+    console.error(`  ${t('msg.err.hint')} ${t('hint.publish.initFirst')}`);
+    process.exitCode = 1;
+    return false;
+}
+export async function passwordSetAction(repoPath) {
+    const kv = resolveRepoKv(repoPath);
+    if (!(await ensureRepo(kv)))
+        return;
+    const pwd = await promptPassword(t('publish.password.msg.prompt'));
+    if (!pwd) {
+        error(t('publish.password.msg.empty'));
+        return;
+    }
+    // Argon2id with a fresh salt. ~300ms on a modern laptop at these params —
+    // right ballpark for an interactive login: slow enough to throttle
+    // brute-force, fast enough that the user doesn't notice.
+    const token = hashPassword(pwd);
+    await kv.set('publish.password.enabled', true);
+    await kv.set('publish.password.hash', token);
+    // A fresh AES salt is generated once here and reused by every subsequent
+    // `publish build`. Rotating it would invalidate previously-built sites
+    // that were unlocked with the old salt-derived key — since the same
+    // password + same salt always derives the same AES key, this stays
+    // stable across rebuilds without needing a stored key file.
+    await kv.set('publish.password.aesSalt', generateAesSalt());
+    // When scope / selected are unset, fall back to schema defaults.
+    if (!(await kv.has('publish.password.scope'))) {
+        await kv.set('publish.password.scope', 'all');
+    }
+    if (!(await kv.has('publish.password.selected'))) {
+        await kv.set('publish.password.selected', []);
+    }
+    success(t('publish.password.msg.setDone'));
+    console.log(`  ${t('publish.password.msg.setEffective')}`);
+}
+export async function passwordClearAction(repoPath) {
+    const kv = resolveRepoKv(repoPath);
+    if (!(await ensureRepo(kv)))
+        return;
+    await kv.set('publish.password.enabled', false);
+    await kv.set('publish.password.hash', '');
+    await kv.set('publish.password.aesSalt', '');
+    success(t('publish.password.msg.clearDone'));
+}
+export async function passwordStatusAction(repoPath) {
+    const kv = resolveRepoKv(repoPath);
+    if (!(await kv.available())) {
+        info(t('publish.password.msg.uninitialized'));
+        return;
+    }
+    const hasEnabled = await kv.has('publish.password.enabled');
+    if (!hasEnabled) {
+        info(t('publish.password.msg.unset'));
+        return;
+    }
+    const enabled = await kv.get('publish.password.enabled');
+    if (enabled === true)
+        success(t('publish.password.msg.enabled'));
+    else
+        info(t('publish.password.msg.disabled'));
+}

package/dist/cli/commands/publish/password/i18n.js

@@ -0,0 +1,44 @@
+export const messages = {
+    'zh-CN': {
+        'publish.password.summary': '密码保护',
+        'publish.password.description': '密码保护：set / clear / status',
+        'publish.password.set.summary': '设置或修改密码',
+        'publish.password.set.description': '设置访问密码',
+        'publish.password.clear.summary': '移除密码',
+        'publish.password.clear.description': '移除密码保护',
+        'publish.password.status.summary': '查看状态',
+        'publish.password.status.description': '显示当前密码保护状态',
+        'publish.password.arg.path': '仓库路径（默认当前目录）',
+        // runtime messages
+        'publish.password.msg.prompt': '输入新密码: ',
+        'publish.password.msg.empty': '密码为空，已取消',
+        'publish.password.msg.setDone': '密码已设置',
+        'publish.password.msg.setEffective': '下次 `qtype publish build` 后生效',
+        'publish.password.msg.clearDone': '密码已清除',
+        'publish.password.msg.uninitialized': '未初始化（.qtype/config.json 不存在）',
+        'publish.password.msg.unset': '未设置密码',
+        'publish.password.msg.enabled': '已启用密码保护',
+        'publish.password.msg.disabled': '未启用',
+    },
+    'en-US': {
+        'publish.password.summary': 'Password protection',
+        'publish.password.description': 'Password protection: set / clear / status',
+        'publish.password.set.summary': 'Set or change password',
+        'publish.password.set.description': 'Set access password',
+        'publish.password.clear.summary': 'Clear password',
+        'publish.password.clear.description': 'Remove password protection',
+        'publish.password.status.summary': 'Show status',
+        'publish.password.status.description': 'Show current password protection status',
+        'publish.password.arg.path': 'Repo path (default: current directory)',
+        // runtime messages
+        'publish.password.msg.prompt': 'New password: ',
+        'publish.password.msg.empty': 'Empty password; cancelled',
+        'publish.password.msg.setDone': 'Password set',
+        'publish.password.msg.setEffective': 'Takes effect on next `qtype publish build`',
+        'publish.password.msg.clearDone': 'Password cleared',
+        'publish.password.msg.uninitialized': 'Not initialized (.qtype/config.json not found)',
+        'publish.password.msg.unset': 'No password set',
+        'publish.password.msg.enabled': 'Password protection enabled',
+        'publish.password.msg.disabled': 'Disabled',
+    },
+};

package/dist/cli/commands/publish/password/index.js

@@ -0,0 +1,35 @@
+import { t } from '../../../i18n/index.js';
+import { messages } from './i18n.js';
+import { passwordSetAction, passwordClearAction, passwordStatusAction, } from './action.js';
+const pathArg = {
+    flag: '[path]',
+    describe: () => t('publish.password.arg.path'),
+};
+const setCmd = {
+    name: 'set',
+    summary: () => t('publish.password.set.summary'),
+    describe: () => t('publish.password.set.description'),
+    args: [pathArg],
+    action: passwordSetAction,
+};
+const clearCmd = {
+    name: 'clear',
+    summary: () => t('publish.password.clear.summary'),
+    describe: () => t('publish.password.clear.description'),
+    args: [pathArg],
+    action: passwordClearAction,
+};
+const statusCmd = {
+    name: 'status',
+    summary: () => t('publish.password.status.summary'),
+    describe: () => t('publish.password.status.description'),
+    args: [pathArg],
+    action: passwordStatusAction,
+};
+export const publishPasswordCmd = {
+    name: 'password',
+    messages,
+    summary: () => t('publish.password.summary'),
+    describe: () => t('publish.password.description'),
+    subcommands: [setCmd, clearCmd, statusCmd],
+};

package/dist/cli/commands/publish/serve/action.js

@@ -0,0 +1,117 @@
+/**
+ * `qtype publish serve` action — HTTP-serve a built dist/ directory.
+ *
+ * Static, read-only file server with:
+ *   - MIME lookup for the file types the built site emits
+ *   - SPA fallback: unknown extensionless routes fall back to index.html so
+ *     client-side routing works when a user opens a deep link directly
+ *   - Structured error handling for EADDRINUSE / EACCES so the operator
+ *     sees a one-line message instead of a stack trace
+ */
+import fs from 'node:fs';
+import http from 'node:http';
+import path from 'node:path';
+import { error, success } from '../../../utils/output.js';
+import { t } from '../../../i18n/index.js';
+const MIME = {
+    '.html': 'text/html; charset=utf-8',
+    '.css': 'text/css; charset=utf-8',
+    '.js': 'application/javascript; charset=utf-8',
+    '.json': 'application/json; charset=utf-8',
+    '.md': 'text/markdown; charset=utf-8',
+    '.svg': 'image/svg+xml',
+    '.png': 'image/png',
+    '.jpg': 'image/jpeg',
+    '.jpeg': 'image/jpeg',
+    '.gif': 'image/gif',
+    '.webp': 'image/webp',
+    '.ico': 'image/x-icon',
+    '.txt': 'text/plain; charset=utf-8',
+    '.woff': 'font/woff',
+    '.woff2': 'font/woff2',
+    '.map': 'application/json; charset=utf-8',
+};
+export async function publishServeAction(opts = {}) {
+    const port = opts.port ?? 4000;
+    const dir = opts.dir
+        ? path.resolve(opts.dir)
+        : path.resolve(process.cwd(), 'dist');
+    if (!fs.existsSync(dir)) {
+        error(t('err.dir.notExists', { path: dir }));
+        console.error(`  ${t('msg.err.hint')} ${t('hint.serve.buildFirst')}`);
+        process.exitCode = 1;
+        return;
+    }
+    const server = http.createServer((req, res) => {
+        const parsed = new URL(req.url || '/', 'http://localhost');
+        const decoded = decodeURIComponent(parsed.pathname);
+        const safe = path.posix.normalize(decoded).replace(/^(\.\.[/\\])+/, '');
+        let file = path.join(dir, safe);
+        try {
+            const stat = fs.statSync(file);
+            if (stat.isDirectory())
+                file = path.join(file, 'index.html');
+        }
+        catch {
+            // fall through to 404 / SPA fallback
+        }
+        fs.readFile(file, (err, data) => {
+            if (err) {
+                // SPA fallback for GET requests. Real static-resource paths
+                // (`/material/*`, `/assets/*`) must 404 honestly — the client
+                // relies on those failures to detect missing content. Everything
+                // else (typing routes like `/typing/foo.md`, unknown deep links)
+                // falls back to index.html so client-side routing can take over.
+                const rp = safe; // decoded, normalised URL pathname
+                const isReservedAsset = rp === '/index.html' ||
+                    rp.startsWith('/material/') ||
+                    rp.startsWith('/assets/');
+                if (!isReservedAsset && req.method === 'GET') {
+                    fs.readFile(path.join(dir, 'index.html'), (e2, d2) => {
+                        if (e2) {
+                            res.writeHead(404, { 'Content-Type': 'text/plain; charset=utf-8' });
+                            res.end('404 Not Found');
+                        }
+                        else {
+                            res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' });
+                            res.end(d2);
+                        }
+                    });
+                    return;
+                }
+                res.writeHead(404, { 'Content-Type': 'text/plain; charset=utf-8' });
+                res.end('404 Not Found');
+                return;
+            }
+            const ext = path.extname(file).toLowerCase();
+            res.writeHead(200, {
+                'Content-Type': MIME[ext] || 'application/octet-stream',
+                'Cache-Control': 'no-cache',
+            });
+            res.end(data);
+        });
+    });
+    server.on('error', (err) => {
+        if (err.code === 'EADDRINUSE') {
+            error(t('publish.serve.err.portInUse', { port }));
+            console.error(`  ${t('msg.err.hint')} ${t('publish.serve.hint.portInUse')}`);
+        }
+        else if (err.code === 'EACCES') {
+            error(t('publish.serve.err.portDenied', { port }));
+            console.error(`  ${t('msg.err.hint')} ${t('publish.serve.hint.portDenied')}`);
+        }
+        else {
+            error(t('publish.serve.err.listenFailed', {
+                port,
+                code: err.code ?? '',
+                message: err.message,
+            }));
+        }
+        process.exitCode = 1;
+    });
+    server.listen(port, () => {
+        success(t('publish.serve.msg.listening', { port }));
+        console.log(`  ${t('publish.serve.msg.dir', { dir })}`);
+        console.log(`  ${t('publish.serve.msg.stopHint')}`);
+    });
+}

package/dist/cli/commands/publish/serve/i18n.js

@@ -0,0 +1,32 @@
+export const messages = {
+    'zh-CN': {
+        'publish.serve.summary': '预览已构建的资料站',
+        'publish.serve.description': '本地 HTTP 服务器预览 publish build 的产物（静态只读），部署前 debug 用',
+        'publish.serve.arg.dir': '要服务的目录（默认 ./dist）',
+        'publish.serve.example.basic': '默认端口预览',
+        'publish.serve.example.port': '自定义端口',
+        'publish.serve.msg.listening': 'QTYPE 站点服务中 http://localhost:{port}/',
+        'publish.serve.msg.dir': '目录: {dir}',
+        'publish.serve.msg.stopHint': '按 Ctrl+C 停止',
+        'publish.serve.err.portInUse': '端口 {port} 已被占用',
+        'publish.serve.hint.portInUse': '换个端口试试：qtype publish serve -p <port>',
+        'publish.serve.err.portDenied': '端口 {port} 无权限（<1024 需 sudo）',
+        'publish.serve.hint.portDenied': '换 1024 以上的端口，如 -p 4000',
+        'publish.serve.err.listenFailed': '监听 {port} 失败 [{code}]: {message}',
+    },
+    'en-US': {
+        'publish.serve.summary': 'Preview the built site',
+        'publish.serve.description': 'Local HTTP server for publish-build output (read-only), for pre-deploy debug',
+        'publish.serve.arg.dir': 'Directory to serve (default: ./dist)',
+        'publish.serve.example.basic': 'Default port',
+        'publish.serve.example.port': 'Custom port',
+        'publish.serve.msg.listening': 'QTYPE site serving at http://localhost:{port}/',
+        'publish.serve.msg.dir': 'Directory: {dir}',
+        'publish.serve.msg.stopHint': 'Press Ctrl+C to stop',
+        'publish.serve.err.portInUse': 'Port {port} is already in use',
+        'publish.serve.hint.portInUse': 'Try another port: qtype publish serve -p <port>',
+        'publish.serve.err.portDenied': 'Permission denied for port {port} (<1024 requires sudo)',
+        'publish.serve.hint.portDenied': 'Use a port ≥ 1024, e.g. -p 4000',
+        'publish.serve.err.listenFailed': 'Failed to listen on {port} [{code}]: {message}',
+    },
+};

package/dist/cli/commands/publish/serve/index.js

@@ -0,0 +1,37 @@
+/**
+ * `qtype publish serve` command module.
+ */
+import { InvalidArgumentError } from 'commander';
+import { t } from '../../../i18n/index.js';
+import { messages } from './i18n.js';
+import { publishServeAction } from './action.js';
+function parsePort(value) {
+    const n = parseInt(value, 10);
+    if (Number.isNaN(n) || n <= 0 || n > 65535) {
+        throw new InvalidArgumentError(t('msg.port.invalid'));
+    }
+    return n;
+}
+export const publishServeCmd = {
+    name: 'serve',
+    messages,
+    summary: () => t('publish.serve.summary'),
+    describe: () => t('publish.serve.description'),
+    args: [{ flag: '[dir]', describe: () => t('publish.serve.arg.dir') }],
+    options: [
+        {
+            flags: '-p, --port <port>',
+            describe: () => t('opt.port'),
+            defaultValue: 4000,
+            parser: parsePort,
+        },
+    ],
+    examples: () => [
+        { command: 'qtype publish serve', describe: () => t('publish.serve.example.basic') },
+        { command: 'qtype publish serve -p 8080', describe: () => t('publish.serve.example.port') },
+    ],
+    seeAlso: ['publish build'],
+    action: async (dir, opts) => {
+        await publishServeAction({ port: opts.port, dir });
+    },
+};

package/dist/cli/commands/repo/index.js

@@ -0,0 +1,19 @@
+import { t } from '../../i18n/index.js';
+import { repoNewCmd } from './new/index.js';
+import { repoSyncCmd } from './sync/index.js';
+export const repoCmd = {
+    name: 'repo',
+    summary: () => t('repo.summary'),
+    describe: () => t('repo.description'),
+    messages: {
+        'zh-CN': {
+            'repo.summary': '仓库管理',
+            'repo.description': '管理 qtype 资料仓库：新建 / 补齐缺失文件',
+        },
+        'en-US': {
+            'repo.summary': 'Repository management',
+            'repo.description': 'Manage qtype material repositories: create new / sync missing files',
+        },
+    },
+    subcommands: [repoNewCmd, repoSyncCmd],
+};

package/dist/cli/commands/repo/new/action.js

@@ -0,0 +1,98 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { execSync } from 'node:child_process';
+import { getTemplatesDir, readTemplate } from '../templates.js';
+import { info, success, warn, fatal } from '../../../utils/output.js';
+import { t } from '../../../i18n/index.js';
+export async function repoNewAction(opts) {
+    // Validate the repo name. Path separators, '.' / '..' are all rejected
+    // — they would either silently create nested dirs the user didn't mean
+    // or refer to an existing directory rather than creating a new one.
+    if (opts.name.length === 0 ||
+        opts.name === '.' ||
+        opts.name === '..' ||
+        /[/\\]/.test(opts.name)) {
+        fatal(t('err.repo.invalidName', { name: opts.name }));
+    }
+    // Reduce BCP 47 / short-code inputs to the two-letter short form used
+    // by template and content directories.
+    const shortLang = opts.lang === 'zh' || opts.lang === 'zh-CN' ? 'zh' : 'en';
+    // Canonical BCP 47 form used in .qtype/config.json (repo.lang) so the
+    // web reader can pick it up directly without further normalisation.
+    const canonicalLang = shortLang === 'zh' ? 'zh-CN' : 'en-US';
+    // Retained under the old name so the rest of this file (which uses
+    // `lang` for directory lookups) keeps working unchanged.
+    const lang = shortLang;
+    const qtypeFileName = 'QTYPE.md';
+    const parentDir = opts.dir ?? process.cwd();
+    const repoDir = path.join(parentDir, opts.name);
+    const today = new Date().toISOString().slice(0, 10);
+    if (fs.existsSync(repoDir)) {
+        const entries = fs.readdirSync(repoDir);
+        if (entries.length > 0) {
+            fatal(t('err.dir.notEmpty', { path: repoDir }), t('hint.sync.dirExists'));
+        }
+    }
+    else {
+        fs.mkdirSync(repoDir, { recursive: true });
+    }
+    info(t('repo.new.msg.creating', { path: repoDir }));
+    const templatesDir = getTemplatesDir(lang);
+    const vars = {
+        name: opts.name,
+        description: opts.description || t('repo.new.tpl.defaultDescription'),
+        date: today,
+    };
+    // 1. Copy QTYPE.md from the language-specific template directory
+    fs.writeFileSync(path.join(repoDir, qtypeFileName), readTemplate(templatesDir, 'QTYPE.md', vars));
+    console.log(`  + ${qtypeFileName}`);
+    // 2. Create AGENTS/CLAUDE/GEMINI symlinks → QTYPE.md
+    for (const alias of ['AGENTS.md', 'CLAUDE.md', 'GEMINI.md']) {
+        try {
+            fs.symlinkSync(qtypeFileName, path.join(repoDir, alias));
+            console.log(`  + ${alias} → ${qtypeFileName}`);
+        }
+        catch {
+            fs.copyFileSync(path.join(repoDir, qtypeFileName), path.join(repoDir, alias));
+            console.log(`  + ${t('repo.new.msg.symlinkFallback', { alias })}`);
+        }
+    }
+    // 3. Copy the other localized template files
+    for (const fileName of ['README.md', 'TODO.md', 'index.md', 'log.md']) {
+        fs.writeFileSync(path.join(repoDir, fileName), readTemplate(templatesDir, fileName, vars));
+        console.log(`  + ${fileName}`);
+    }
+    // 4. Seed material/example.md and empty .gitkeep so the directory exists
+    //    but stays trivially prunable if the user wipes the seed.
+    fs.mkdirSync(path.join(repoDir, 'material'), { recursive: true });
+    fs.writeFileSync(path.join(repoDir, 'material', 'example.md'), readTemplate(templatesDir, path.join('material', 'example.md'), vars));
+    console.log(`  + material/example.md`);
+    fs.writeFileSync(path.join(repoDir, 'material', '.gitkeep'), '');
+    console.log(`  + material/.gitkeep`);
+    // 5. Write .qtype/config.json with the repo language.
+    const qtypeDir = path.join(repoDir, '.qtype');
+    fs.mkdirSync(qtypeDir, { recursive: true });
+    fs.writeFileSync(path.join(qtypeDir, 'config.json'), JSON.stringify({ repo: { lang: canonicalLang } }, null, 2) + '\n');
+    console.log(`  + .qtype/config.json`);
+    // 6. git init (optional; requires explicit --git)
+    if (opts.git === true) {
+        try {
+            execSync('git init -b main', { cwd: repoDir, stdio: 'ignore' });
+            console.log(`  + ${t('repo.new.msg.gitInited')}`);
+        }
+        catch (err) {
+            warn(t('repo.new.msg.gitInitFailed', { reason: err.message }));
+        }
+    }
+    console.log('');
+    success(t('repo.new.msg.done', { path: repoDir }));
+    console.log(`\n${t('repo.new.msg.nextSteps')}`);
+    console.log(`  ${t('repo.new.msg.next.cd', { name: opts.name })}`);
+    console.log(`  ${t('repo.new.msg.next.edit')}`);
+    if (opts.git === true) {
+        console.log(`  ${t('repo.new.msg.next.commit')}`);
+    }
+    else {
+        console.log(`  ${t('repo.new.msg.next.gitHint')}`);
+    }
+}