@mintfolio/core 0.1.5

package/bin/lib/posts.mjs

@@ -0,0 +1,114 @@
+import { mkdir, readFile, readdir, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { isMap, isScalar, parseDocument } from 'yaml';
+import { checkedPath, exists, saveFile } from './files.mjs';
+
+/** @param {Date} [date] Local calendar date for article frontmatter. @returns {string} YYYY-MM-DD. */
+export function today(date = new Date()) {
+  return `${date.getFullYear()}-${String(date.getMonth() + 1).padStart(2, '0')}-${String(date.getDate()).padStart(2, '0')}`;
+}
+
+/** @param {string} title Unicode title. @returns {string} Human-readable slug; no path is inferred from the title. */
+export function slugFromTitle(title) { return title.normalize('NFKC').toLowerCase().replace(/[^\p{L}\p{N}_-]+/gu, '-').replace(/^-+|-+$/g, ''); }
+
+/** @param {string} slug Relative article ID, optionally ending in .md. @returns {string} Checked relative Markdown path. */
+export function postPath(slug) {
+  const id = slug.replace(/\.md$/i, '');
+  const pieces = id.split('/');
+  if (!id || pieces.some(piece => !/^[\p{L}\p{N}][\p{L}\p{N}_-]*$/u.test(piece) || /^(con|prn|aux|nul|com[1-9]|lpt[1-9])$/i.test(piece))) throw new Error('文章 ID 仅支持文字、数字、下划线、连字符和目录分隔符 /；请用 --slug 指定有效路径。');
+  return pieces.join(path.sep) + '.md';
+}
+
+function checkedDate(value) {
+  if (!/^\d{4}-\d{2}-\d{2}$/.test(value) || !Number.isFinite(Date.parse(value)) || new Date(value).toISOString().slice(0, 10) !== value) throw new Error('日期必须是有效的 YYYY-MM-DD。');
+  return value;
+}
+
+/**
+ * Create a Markdown article exclusively; existing articles are never overwritten.
+ * @param {string} root Site root.
+ * @param {string} title Required article title.
+ * @param {{slug?:string,description?:string,category?:string,tags?:string,date?:string,publish?:boolean}} options Frontmatter inputs; new articles default to drafts.
+ * @returns {Promise<string>} Absolute created filename.
+ */
+export async function createPost(root, title, options = {}) {
+  if (!title.trim()) throw new Error('文章标题不能为空。');
+  const filename = path.join(root, 'content/blog', postPath(options.slug || slugFromTitle(title)));
+  await checkedPath(root, filename);
+  const fields = {
+    title,
+    pubDate: checkedDate(options.date || today()),
+    description: options.description || '',
+    category: options.category || '',
+    tags: (options.tags || '').split(',').map(tag => tag.trim()).filter(Boolean),
+    draft: !options.publish,
+  };
+  const frontmatter = Object.entries(fields).map(([key, value]) => `${key}: ${JSON.stringify(value)}`).join('\n');
+  await mkdir(path.dirname(filename), { recursive: true });
+  await checkedPath(root, filename);
+  try { await writeFile(filename, `---\n${frontmatter}\n---\n\n## ${title.replace(/[\r\n]+/g, ' ')}\n\n开始写作吧。\n`, { flag: 'wx' }); }
+  catch (error) { if (error.code === 'EEXIST') throw new Error(`文章已存在，未覆盖：${filename}`); throw error; }
+  return filename;
+}
+
+/** @param {string} source Markdown source. @param {string} filename Diagnostic path. @returns {{document:object,start:number,end:number}} YAML document and exact source offsets. */
+function frontmatter(source, filename) {
+  const opening = /^(?:\uFEFF)?---[^\S\r\n]*\r?\n/.exec(source);
+  if (!opening) throw new Error(`${filename} 缺少 YAML frontmatter。`);
+  const remaining = source.slice(opening[0].length);
+  const closing = /^---[^\S\r\n]*(?:\r?\n|$)/m.exec(remaining);
+  if (!closing) throw new Error(`${filename} 的 YAML frontmatter 未结束。`);
+  const start = opening[0].length;
+  const end = start + closing.index;
+  const document = parseDocument(source.slice(start, end), { uniqueKeys: true });
+  if (document.errors.length || !isMap(document.contents)) throw new Error(`${filename} 的 YAML frontmatter 无效：${document.errors[0]?.message || '需要键值对象'}`);
+  return { document, start, end };
+}
+
+/**
+ * Toggle draft status while retaining Markdown and all unrelated YAML bytes.
+ * @param {string} root Site root. @param {string} slug Article ID.
+ * @param {boolean} draft true saves as draft, false makes it eligible for the next build.
+ * @returns {Promise<{filename:string,backup:string|null}>} Updated article and exact backup.
+ */
+export async function setDraft(root, slug, draft) {
+  const filename = await checkedPath(root, path.join(root, 'content/blog', postPath(slug)));
+  const original = await readFile(filename, 'utf8');
+  const { document, start, end } = frontmatter(original, filename);
+  const node = document.get('draft', true);
+  let source;
+  if (node !== undefined) {
+    if (!isScalar(node) || typeof node.value !== 'boolean') throw new Error('draft 必须是布尔值，请先修正文章 frontmatter。');
+    source = original.slice(0, start + node.range[0]) + String(draft) + original.slice(start + node.range[1]);
+  } else {
+    const eol = original.includes('\r\n') ? '\r\n' : '\n';
+    source = original.slice(0, end) + `draft: ${draft}${eol}` + original.slice(end);
+  }
+  return { filename, backup: await saveFile(root, filename, original, source) };
+}
+
+/**
+ * List public metadata only; passwords and article bodies are never printed.
+ * @param {string} root Site root.
+ * @returns {Promise<Array<{slug:string,title:string,date:string,draft:boolean}>>} Date-sorted article metadata.
+ */
+export async function listPosts(root) {
+  const base = path.join(root, 'content/blog');
+  if (!await exists(base)) return [];
+  await checkedPath(root, base);
+  const posts = [];
+  async function visit(directory) {
+    for (const entry of await readdir(directory, { withFileTypes: true })) {
+      const filename = path.join(directory, entry.name);
+      if (entry.isDirectory()) await visit(filename);
+      else if (entry.isFile() && entry.name.endsWith('.md')) {
+        const { document } = frontmatter(await readFile(filename, 'utf8'), filename);
+        const title = document.get('title');
+        if (typeof title !== 'string') throw new Error(`${filename} 的 title 必须是字符串。`);
+        posts.push({ slug: path.relative(base, filename).replace(/\\/g, '/').replace(/\.md$/, ''), title, date: String(document.get('pubDate') || '').slice(0, 10), draft: document.get('draft') === true });
+      }
+    }
+  }
+  await visit(base);
+  return posts.sort((a, b) => b.date.localeCompare(a.date) || a.slug.localeCompare(b.slug));
+}

package/bin/lib/process.mjs

@@ -0,0 +1,67 @@
+import { spawn } from 'node:child_process';
+import { realpath } from 'node:fs/promises';
+import path from 'node:path';
+import { createRequire } from 'node:module';
+import { exists } from './files.mjs';
+
+/**
+ * Execute arguments without a shell, including Windows paths and Unicode titles.
+ * @param {string} executable Executable path.
+ * @param {string[]} args Literal argument vector; never interpolated shell code.
+ * @param {string} cwd Working directory.
+ * @returns {Promise<void>} Reject on launch errors, signals or nonzero status.
+ */
+export async function run(executable, args, cwd) {
+  await new Promise((resolve, reject) => {
+    const child = spawn(executable, args, { cwd, stdio: 'inherit', shell: false, windowsHide: true });
+    const forward = () => child.kill('SIGINT');
+    process.once('SIGINT', forward);
+    child.once('error', error => { process.removeListener('SIGINT', forward); reject(error); });
+    child.once('exit', (code, signal) => {
+      process.removeListener('SIGINT', forward);
+      if (code === 0) resolve();
+      else reject(Object.assign(new Error(`${path.basename(executable)} 退出，状态 ${code ?? signal}。`), { exitCode: code ?? 1 }));
+    });
+  });
+}
+
+/** @returns {Promise<string>} npm's JavaScript entry, for npx, global and direct CLI execution. */
+export async function npmEntry() {
+  const candidates = [];
+  if (process.env.npm_execpath?.endsWith('npm-cli.js')) candidates.push(process.env.npm_execpath);
+  // PATH is the user's chosen npm (which may be newer than Node's bundled copy).
+  const directories = [...(process.env.PATH || '').split(path.delimiter).filter(Boolean), path.dirname(process.execPath)];
+  for (const directory of directories) {
+    candidates.push(path.join(directory, 'node_modules/npm/bin/npm-cli.js'), path.join(directory, '../lib/node_modules/npm/bin/npm-cli.js'));
+    try {
+      const binary = await realpath(path.join(directory, 'npm'));
+      if (binary.endsWith('npm-cli.js')) candidates.push(binary);
+    } catch {}
+  }
+  for (const candidate of candidates) if (await exists(candidate)) return candidate;
+  throw new Error('找不到 npm。请安装 Node.js/npm，或通过 npx mintfolio 运行。');
+}
+
+/** @param {string[]} args npm arguments. @param {string} root Host directory. */
+export async function npm(args, root) { await run(process.execPath, [await npmEntry(), ...args], root); }
+
+/** @param {string} root Host root. @returns {string} Astro installed with this site's Core, including nested layouts. */
+export function astroEntry(root) {
+  const host = createRequire(path.join(root, 'package.json'));
+  const core = createRequire(host.resolve('@mintfolio/core/package.json'));
+  return path.join(path.dirname(core.resolve('astro/package.json')), 'bin/astro.mjs');
+}
+
+/**
+ * Open the exact file with an installed GUI editor. An explicit --editor is an
+ * executable name/path, not a shell expression. The CLI never invokes a shell.
+ * @param {string} filename Checked site file. @param {string|undefined} editor Explicit editor executable.
+ * @param {string} root Site root.
+ */
+export async function editFile(filename, editor, root) {
+  const configured = editor || process.env.VISUAL || process.env.EDITOR;
+  if (configured) return run(configured, [filename], root);
+  if (process.platform === 'win32') return run('notepad.exe', [filename], root);
+  if (process.platform === 'darwin') return run('open', ['-t', filename], root);
+  return run('xdg-open', [filename], root);
+}

package/bin/lib/site.mjs

@@ -0,0 +1,65 @@
+import { mkdir, readdir, readFile, realpath, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { createRequire } from 'node:module';
+import semver from 'semver';
+import { initialize } from './init.mjs';
+import { activeTheme, installTheme } from './themes.mjs';
+import { npm } from './process.mjs';
+import { exists } from './files.mjs';
+import { getConfig } from './config.mjs';
+
+/** @returns {Promise<string>} Version of the executing CLI package. */
+export async function cliVersion() { return JSON.parse(await readFile(new URL('../../package.json', import.meta.url), 'utf8')).version; }
+
+/** @param {string} root Site root. Reject theme-file editing against engines that cannot read those files. */
+export async function requireThemeConfigRuntime(root) {
+  const host = createRequire(path.join(root, 'package.json'));
+  const core = JSON.parse(await readFile(host.resolve('@mintfolio/core/package.json'), 'utf8'));
+  if (!semver.gte(core.version, '0.1.1')) throw new Error(`当前站点 Core ${core.version} 不支持独立主题配置，请先运行 mintfolio upgrade。`);
+}
+
+/**
+ * Create a new site in an empty target and install Core through npm. A supplied
+ * registry config applies only to @mintfolio; no global npm settings are changed.
+ * @param {string} directory Explicit target directory.
+ * @param {{theme?:string,registry?:string}} options Optional initial theme and scoped registry.
+ * @returns {Promise<string>} Absolute created site directory.
+ */
+export async function createSite(directory, options = {}) {
+  const target = path.resolve(directory);
+  if (await exists(target) && (await readdir(target)).length) throw new Error('新站点目录必须为空；已有站点请使用 mintfolio init。');
+  let registry;
+  if (options.registry) {
+    const url = new URL(options.registry);
+    if (!['http:', 'https:'].includes(url.protocol) || url.username || url.password || url.search || url.hash) throw new Error('--registry 需要不带账号或查询参数的 HTTP(S) 仓库地址。');
+    registry = url.href;
+  }
+  await mkdir(target, { recursive: true });
+  const root = await realpath(target);
+  const name = path.basename(root).toLowerCase().replace(/[^a-z0-9-]/g, '-') || 'mintfolio-site';
+  await writeFile(path.join(root, 'package.json'), JSON.stringify({ name, private: true, version: '1.0.0', type: 'module' }, null, 2) + '\n', { flag: 'wx' });
+  if (registry) await writeFile(path.join(root, '.npmrc'), `registry=https://registry.npmjs.org/\n@mintfolio:registry=${registry}\n`, { flag: 'wx' });
+  await npm(['install', `@mintfolio/core@^${await cliVersion()}`, '--no-audit'], root);
+  await initialize(root);
+  if (options.theme && options.theme !== 'minimal') await installTheme(root, options.theme, true);
+  console.log(`站点已创建：${root}\n进入目录后执行 mintfolio dev。`);
+  return root;
+}
+
+/**
+ * Diagnose the actual installed host and selected theme without changing files.
+ * @param {string} root Site root.
+ * @returns {Promise<object>} Runtime paths, versions and configuration status.
+ */
+export async function doctor(root) {
+  if (!semver.gte(process.versions.node, '22.12.0')) throw new Error('需要 Node.js >= 22.12.0。');
+  const host = createRequire(path.join(root, 'package.json'));
+  const corePath = host.resolve('@mintfolio/core/package.json');
+  const core = JSON.parse(await readFile(corePath, 'utf8'));
+  const coreRequire = createRequire(corePath);
+  const astro = JSON.parse(await readFile(coreRequire.resolve('astro/package.json'), 'utf8'));
+  const active = await activeTheme(root, process.env.MINTFOLIO_THEME || undefined);
+  const site = await getConfig(root, 'site');
+  if (!site.site) throw new Error('site.config.ts 缺少 site 信息。');
+  return { root, node: process.versions.node, cli: await cliVersion(), core: core.version, astro: astro.version, theme: active.selector, themeVersion: active.definition.manifest.version, config: active.themeConfigFile, themeConfigExists: await exists(active.themeConfigFile), status: 'ok' };
+}

package/bin/lib/themes.mjs

@@ -0,0 +1,119 @@
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import semver from 'semver';
+import { createThemeConfig, normalizeThemeName } from '../theme-config.mjs';
+import { loadTheme } from '../../src/engine/loader.mjs';
+import { mergeThemeSettings } from '../../src/engine/theme-config.mjs';
+import { resolveSettings } from '../../src/engine/schema.mjs';
+import { configSource, setSourceValue, sourceNode, sourceValue } from './config-source.mjs';
+import { checkedPath, exists, saveFile } from './files.mjs';
+import { npm } from './process.mjs';
+
+let revision = 0;
+
+/** @param {string} root Site root. @returns {Promise<object>} Persistent theme selection, independent of a temporary environment override. */
+export async function readSelection(root) {
+  const filename = await checkedPath(root, path.join(root, 'theme.config.mjs'));
+  const url = pathToFileURL(filename);
+  url.searchParams.set('cli', `${Date.now()}-${++revision}`);
+  const selection = (await import(url.href)).default;
+  if (!selection || typeof selection !== 'object' || Array.isArray(selection)) throw new Error('theme.config.mjs 必须导出配置对象。');
+  return selection;
+}
+
+/** @param {string} root @param {string} [selector] Explicit package, local theme or Minimal. @returns {Promise<object>} Validated selected theme and persistent selection. */
+export async function activeTheme(root, selector) {
+  const selection = await readSelection(root);
+  const theme = normalizeThemeName(selector || selection.theme || 'minimal');
+  const same = theme === normalizeThemeName(selection.theme || 'minimal');
+  const active = await loadTheme({ root, theme, settings: same ? selection.settings : {}, overrides: same ? selection.overrides : {} });
+  return { ...active, selection, selector: theme, same };
+}
+
+/** @param {string} spec npm package with optional version/range/tag; default and happyhues are aliases. @returns {{name:string,spec:string}} Validated package identity and install spec. */
+export function packageSpec(spec) {
+  const separator = spec.lastIndexOf('@');
+  const split = separator > spec.indexOf('/') && separator > 0;
+  const name = normalizeThemeName(split ? spec.slice(0, separator) : spec);
+  const version = split ? spec.slice(separator + 1) : '';
+  if (typeof name !== 'string' || !/^(?:@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*$/.test(name) || name === 'minimal' || (split && !version) || (version && !semver.validRange(version) && !/^[a-z][a-z0-9._-]*$/i.test(version))) throw new Error('请提供 npm 主题包名，可附加 @版本；例如 default 或 @mintfolio/theme-default@0.1.1。');
+  return { name, spec: name + (version ? `@${version}` : '') };
+}
+
+/** @param {string} root @returns {Promise<Array<{name:string,version:string,selected:boolean}>>} Built-in Minimal and directly installed themes. */
+export async function listThemes(root) {
+  const selection = await readSelection(root);
+  const selected = normalizeThemeName(selection.theme || 'minimal');
+  const pkg = JSON.parse(await readFile(path.join(root, 'package.json'), 'utf8'));
+  const themes = [{ name: 'minimal', version: 'built-in', selected: selected === 'minimal' }];
+  const dependencies = { ...pkg.dependencies, ...pkg.devDependencies, ...pkg.optionalDependencies };
+  for (const name of Object.keys(dependencies)) {
+    const filename = path.join(root, 'node_modules', name, 'package.json');
+    if (!await exists(filename)) continue;
+    const installed = JSON.parse(await readFile(filename, 'utf8'));
+    if (installed.exports?.['./theme'] && name !== '@mintfolio/core') themes.push({ name, version: installed.version, selected: selected === name });
+  }
+  if (!themes.some(theme => theme.name === selected)) themes.push({ name: selected, version: 'local', selected: true });
+  return themes;
+}
+
+/** @param {string} root @param {string} spec npm theme spec. @param {boolean} use Select after a successful install. */
+export async function installTheme(root, spec, use = false) {
+  const pkg = packageSpec(spec);
+  await npm(['install', pkg.spec, '--no-audit'], root);
+  const result = await createThemeConfig(root, pkg.name);
+  console.log(`${result.created ? '已生成' : '已保留'} ${result.filename}`);
+  if (use) await useTheme(root, pkg.name);
+  else console.log(`启用主题：mintfolio theme use ${pkg.name}`);
+}
+
+/** Apply an object as individual source edits so unrelated comments remain intact. */
+function mergeSource(source, value, prefix = []) {
+  for (const [key, child] of Object.entries(value)) {
+    const keys = [...prefix, key];
+    if (child && typeof child === 'object' && !Array.isArray(child) && Object.keys(child).length) source = mergeSource(source, child, keys);
+    else source = setSourceValue(source, keys.join('.'), child);
+  }
+  return source;
+}
+
+/**
+ * Select an installed theme. Legacy inline settings are retained in the previous
+ * theme's own file before clearing the inline override; both changes get backups.
+ * @param {string} root Site root. @param {string} selector Installed theme/package or local directory.
+ * @returns {Promise<void>} New selection is validated before persistent changes.
+ */
+export async function useTheme(root, selector) {
+  const theme = normalizeThemeName(selector);
+  const selection = await readSelection(root);
+  const previous = normalizeThemeName(selection.theme || 'minimal');
+  if (theme === previous) { await activeTheme(root, theme); console.log(`当前已使用 ${theme}`); return; }
+  // Page overrides are intentional host choices; keep them and validate them with the new theme.
+  await loadTheme({ root, theme, overrides: selection.overrides });
+  const filename = path.join(root, 'theme.config.mjs');
+  const original = await readFile(filename, 'utf8');
+  let source = setSourceValue(original, 'theme', theme, filename);
+  const inline = selection.settings;
+  let migration;
+  if (inline && Object.keys(inline).length) {
+    const current = await activeTheme(root);
+    const doc = configSource(original, filename);
+    const literal = sourceValue(doc, sourceNode(doc, ['settings']));
+    if (JSON.stringify(literal) !== JSON.stringify(inline)) throw new Error('旧的内联 settings 包含动态表达式，请先移到对应主题配置文件再切换。');
+    const result = await createThemeConfig(root, previous);
+    const before = await readFile(result.filename, 'utf8');
+    const after = mergeSource(before, inline);
+    resolveSettings(current.definition, mergeThemeSettings(sourceValue(configSource(after)), {}));
+    migration = { filename: result.filename, before, after };
+    source = setSourceValue(source, 'settings', {}, filename);
+  }
+  await createThemeConfig(root, theme);
+  // Check the selection again before the first mutation to avoid stale writes.
+  if (await readFile(filename, 'utf8') !== original) throw new Error('主题选择已被其他程序修改，请重试。');
+  if (migration) await saveFile(root, migration.filename, migration.before, migration.after);
+  const backup = await saveFile(root, filename, original, source);
+  console.log(`已启用 ${theme}`);
+  if (migration) console.log(`旧主题设置已保留在 ${migration.filename}`);
+  if (backup) console.log(`备份：${backup}`);
+}

package/bin/mintfolio.mjs

@@ -0,0 +1,244 @@
+#!/usr/bin/env node
+import { parseArgs } from 'node:util';
+import { mkdir, realpath } from 'node:fs/promises';
+import path from 'node:path';
+import { createRequire } from 'node:module';
+import { initialize } from './lib/init.mjs';
+import { cliVersion, createSite, doctor, requireThemeConfigRuntime } from './lib/site.mjs';
+import { createPost, listPosts, setDraft } from './lib/posts.mjs';
+import { activeTheme, installTheme, listThemes, packageSpec, readSelection, useTheme } from './lib/themes.mjs';
+import { configFilename, configSchema, getConfig, setConfig } from './lib/config.mjs';
+import { display, exists, findSite } from './lib/files.mjs';
+import { astroEntry, editFile, npm, run } from './lib/process.mjs';
+import { createThemeConfig, reportThemeConfigs, syncThemeConfigs } from './theme-config.mjs';
+
+const help = {
+  main: `Mintfolio — 站点、文章、主题和配置管理
+
+用法：mintfolio [--cwd <目录>] <命令>
+
+  create <目录> [--theme default]  创建站点并安装依赖
+  init                            补齐当前站点的初始化文件
+  upgrade [--version <版本>]       更新当前站点的 Core
+  dev / build / preview / sync     开发、构建、预览或同步内容
+  post new|list|publish|draft       创建和管理文章
+  theme list|current|install|use   安装和切换主题
+  theme init|sync|check            生成和校验主题配置
+  config get|set|path|edit|schema   查看、修改或打开配置
+  doctor                          检查站点环境与已安装版本
+  check                           校验主题并同步 Astro 内容
+  --version                       显示 CLI 版本
+
+使用 mintfolio <命令> --help 查看用法。
+在站点子目录也可运行；--cwd / -C 指定其他站点。
+旧的 theme:add/theme:init/theme:sync/theme:check 命令继续有效。`,
+  create: `用法：mintfolio create <空目录> [--theme <主题>] [--registry <URL>]
+
+安装 Core，生成站点文件；--theme 可同时安装并启用主题。
+--registry 只配置新站点的 @mintfolio 仓库，例如本地仓库地址。`,
+  init: '用法：mintfolio init\n在已安装 Core 的当前目录补齐初始化文件，保留已有内容和 npm scripts。',
+  upgrade: '用法：mintfolio upgrade [--version <版本或标签>]\n从当前站点配置的 npm 仓库更新 Core，默认 latest。更新后请重新启动开发服务。',
+  post: `用法：mintfolio post <操作>
+
+  new <标题> [--slug <ID>] [--description <摘要>] [--category <分类>]
+             [--tags <逗号分隔标签>] [--date YYYY-MM-DD] [--publish]
+  list [--draft | --published] [--json]
+  publish <ID>     将 draft 设为 false，下一次构建可见
+  draft <ID>       将 draft 设为 true
+
+新文章默认是草稿，存放在 content/blog；ID 支持 notes/hello 等目录。
+标题含空格时请加引号。不会覆盖同名文件。publish 不执行部署。
+示例：mintfolio post new "我的第一篇文章" --slug first-post --tags 随笔,生活`,
+  theme: `用法：mintfolio theme <操作>
+
+  list [--json]                   列出内置和已安装主题
+  current                         显示当前配置中选定的主题
+  install <包名[@版本]> [--use]    安装主题并生成配置，可同时启用
+  use <主题>                      选择 minimal、已安装包或本地主题目录
+  init [主题]                     生成完整配置，保留已有文件
+  sync                            补齐已安装主题的配置
+  check [主题]                    校验清单、配置和页面路径
+
+verdant 是 @mintfolio/theme-default 的别名；default / happyhues 继续兼容。
+示例：mintfolio theme install default --use`,
+  config: `用法：mintfolio config <操作> <site|theme>
+
+  get <范围> [字段]               查看配置；theme 返回合并默认值后的设置
+  set <范围> <字段> <值> [--json]  修改单项，保存前校验并备份
+  path <范围>                     显示配置路径
+  edit <范围> [--editor <程序>]    用编辑器打开配置
+  schema <范围>                   查看可用字段和限制
+
+theme 范围可加 --theme <主题> 编辑未启用主题。
+字段用点号访问，例如 sidebar.quote.enabled；数组下标也用点号。
+字符串直接填写；布尔值用 true/false，数组和对象用 JSON。
+site 值按源文件读取；动态表达式显示为 $expression，不执行导入。
+修改会保留周围注释，并在 .mintfolio/backups 中备份原文件。
+
+示例：mintfolio config set site site.title "我的博客"
+      mintfolio config set theme initialPalette 3
+      mintfolio config set theme sidebar.quote.enabled true`,
+  doctor: '用法：mintfolio doctor [--json]\n检查 Node、当前站点 Core/Astro、主题与配置，不修改文件。',
+  check: '用法：mintfolio check\n检查站点和主题，然后运行 Astro sync 校验内容并生成类型；不代替生产构建。',
+};
+
+/** @param {string[]} args @param {object} [options] @returns {{values:object,positionals:string[]}} Strict argument parsing shared by commands. */
+function options(args, options = {}) { return parseArgs({ args, options: { ...options, help: { type: 'boolean', short: 'h' } }, allowPositionals: true, strict: true }); }
+
+/** @param {string[]} positionals @param {number} min @param {number} max @param {string} group */
+function count(positionals, min, max, group) {
+  if (positionals.length < min || positionals.length > max) throw new Error(`参数数量不正确。\n${help[group]}`);
+}
+
+function printHelp(group = 'main') {
+  if (!help[group]) throw new Error(`未知命令：${group}`);
+  console.log(help[group]);
+}
+
+/** @param {string[]} argv Raw process arguments. @returns {Promise<void>} Dispatch one command and propagate failures. */
+async function main(argv) {
+  let cwd = process.cwd();
+  if (['--cwd', '-C'].includes(argv[0])) {
+    if (!argv[1]) throw new Error('--cwd 需要目录。');
+    cwd = path.resolve(argv[1]);
+    argv = argv.slice(2);
+  }
+  let [command = 'help', ...args] = argv;
+  if (['--version', '-v', 'version'].includes(command)) { console.log(await cliVersion()); return; }
+  if (['help', '--help', '-h'].includes(command)) { printHelp(args[0] || 'main'); return; }
+  const aliases = { 'theme:add': 'install', 'theme:init': 'init', 'theme:sync': 'sync', 'theme:check': 'check' };
+  if (Object.hasOwn(aliases, command)) { args.unshift(aliases[command]); command = 'theme'; }
+  if (command === 'new') { command = 'post'; args.unshift('new'); }
+
+  if (command === 'create') {
+    const parsed = options(args, { theme: { type: 'string' }, registry: { type: 'string' } });
+    if (parsed.values.help) return printHelp(command);
+    count(parsed.positionals, 1, 1, command);
+    await createSite(path.resolve(cwd, parsed.positionals[0]), parsed.values);
+    return;
+  }
+  if (command === 'init') {
+    const parsed = options(args);
+    if (parsed.values.help) return printHelp(command);
+    count(parsed.positionals, 0, 0, command);
+    await mkdir(cwd, { recursive: true });
+    const root = await realpath(cwd);
+    try { createRequire(path.join(root, 'package.json')).resolve('@mintfolio/core/package.json'); }
+    catch { throw new Error('当前目录尚未安装 Core。请先 npm install @mintfolio/core，或使用 mintfolio create <目录>。'); }
+    await initialize(root);
+    return;
+  }
+  if (command === 'upgrade') {
+    const parsed = options(args, { version: { type: 'string' } });
+    if (parsed.values.help) return printHelp(command);
+    count(parsed.positionals, 0, 0, command);
+    const root = await findSite(cwd);
+    const target = packageSpec(`@mintfolio/core@${parsed.values.version || 'latest'}`);
+    await npm(['install', target.spec, '--no-audit'], root);
+    console.log('Core 已更新，请重新启动开发服务。');
+    return;
+  }
+  if (['dev', 'build', 'preview', 'sync'].includes(command)) {
+    const root = await findSite(cwd);
+    if (!args.includes('--help') && !args.includes('-h') && command !== 'preview') reportThemeConfigs(await syncThemeConfigs(root));
+    await run(process.execPath, [astroEntry(root), command, ...args], root);
+    return;
+  }
+  if (command === 'post') {
+    const [action, ...rest] = args;
+    if (!action || action === '--help' || action === '-h') return printHelp(command);
+    const definitions = action === 'new' ? { slug: { type: 'string' }, description: { type: 'string' }, category: { type: 'string' }, tags: { type: 'string' }, date: { type: 'string' }, publish: { type: 'boolean' } }
+      : action === 'list' ? { draft: { type: 'boolean' }, published: { type: 'boolean' }, json: { type: 'boolean' } } : {};
+    const parsed = options(rest, definitions);
+    if (parsed.values.help) return printHelp(command);
+    if (!['new', 'list', 'publish', 'draft'].includes(action)) throw new Error(`未知文章操作：${action}`);
+    count(parsed.positionals, action === 'list' ? 0 : 1, action === 'list' ? 0 : 1, command);
+    const root = await findSite(cwd);
+    if (action === 'new') console.log(`已创建${parsed.values.publish ? '文章' : '草稿'}：${await createPost(root, parsed.positionals[0], parsed.values)}`);
+    else if (action === 'list') {
+      if (parsed.values.draft && parsed.values.published) throw new Error('--draft 和 --published 不能同时使用。');
+      const posts = (await listPosts(root)).filter(post => parsed.values.draft ? post.draft : parsed.values.published ? !post.draft : true);
+      if (parsed.values.json) console.log(JSON.stringify(posts, null, 2));
+      else if (!posts.length) console.log('没有匹配的文章。');
+      else for (const post of posts) console.log(`${post.draft ? '草稿' : '已发布'}  ${post.date}  ${post.slug}  ${post.title}`);
+    } else {
+      const result = await setDraft(root, parsed.positionals[0], action === 'draft');
+      console.log(`${action === 'draft' ? '已设为草稿' : '已标记发布，下次构建生效'}：${result.filename}`);
+      if (result.backup) console.log(`备份：${result.backup}`);
+    }
+    return;
+  }
+  if (command === 'theme') {
+    const [action, ...rest] = args;
+    if (!action || action === '--help' || action === '-h') return printHelp(command);
+    const parsed = options(rest, action === 'install' ? { use: { type: 'boolean' } } : action === 'list' ? { json: { type: 'boolean' } } : {});
+    if (parsed.values.help) return printHelp(command);
+    if (!['list', 'current', 'install', 'use', 'init', 'sync', 'check'].includes(action)) throw new Error(`未知主题操作：${action}`);
+    const required = ['install', 'use'].includes(action);
+    count(parsed.positionals, required ? 1 : 0, ['install', 'use', 'init', 'check'].includes(action) ? 1 : 0, command);
+    const root = await findSite(cwd);
+    if (action === 'list') {
+      const themes = await listThemes(root);
+      if (parsed.values.json) console.log(JSON.stringify(themes, null, 2));
+      else for (const theme of themes) console.log(`${theme.selected ? '*' : ' '} ${theme.name}  ${theme.version}`);
+    } else if (action === 'current') console.log((await activeTheme(root)).selector);
+    else if (action === 'install') await installTheme(root, parsed.positionals[0], parsed.values.use);
+    else if (action === 'use') { await requireThemeConfigRuntime(root); await useTheme(root, parsed.positionals[0]); }
+    else if (action === 'sync') reportThemeConfigs(await syncThemeConfigs(root));
+    else if (action === 'init') {
+      const selection = await readSelection(root);
+      const result = await createThemeConfig(root, parsed.positionals[0] || selection.theme || 'minimal');
+      console.log(`${result.created ? '已生成' : '已保留'} ${result.filename}`);
+    } else {
+      const active = await activeTheme(root, parsed.positionals[0] || process.env.MINTFOLIO_THEME);
+      console.log(`主题 ${active.definition.manifest.id} 的清单、配置与页面路径校验通过。`);
+    }
+    return;
+  }
+  if (command === 'config') {
+    const [action, ...rest] = args;
+    if (!action || action === '--help' || action === '-h') return printHelp(command);
+    const definitions = { theme: { type: 'string' }, ...(action === 'set' ? { json: { type: 'boolean' } } : {}), ...(action === 'edit' ? { editor: { type: 'string' } } : {}) };
+    const parsed = options(rest, definitions);
+    if (parsed.values.help) return printHelp(command);
+    if (!['get', 'set', 'path', 'edit', 'schema'].includes(action)) throw new Error(`未知配置操作：${action}`);
+    count(parsed.positionals, action === 'set' ? 3 : 1, action === 'set' ? 3 : action === 'get' ? 2 : 1, command);
+    const [scope, key, raw] = parsed.positionals;
+    if (!['site', 'theme'].includes(scope)) throw new Error('配置范围为 site 或 theme。');
+    if (scope === 'site' && parsed.values.theme) throw new Error('--theme 只用于 theme 配置。');
+    const root = await findSite(cwd);
+    if (scope === 'theme') await requireThemeConfigRuntime(root);
+    if (action === 'get') console.log(display(await getConfig(root, scope, key, parsed.values.theme)));
+    else if (action === 'schema') console.log(display(await configSchema(root, scope, parsed.values.theme)));
+    else if (action === 'set') {
+      const result = await setConfig(root, scope, key, raw, parsed.values);
+      console.log(`${key} = ${display(result.value)}\n文件：${result.filename}`);
+      if (result.backup) console.log(`备份：${result.backup}`);
+    } else {
+      const filename = await configFilename(root, scope, parsed.values.theme);
+      if (action === 'path') console.log(filename);
+      else {
+        if (!await exists(filename) && scope === 'theme') await createThemeConfig(root, parsed.values.theme || (await readSelection(root)).theme || 'minimal');
+        await editFile(filename, parsed.values.editor, root);
+      }
+    }
+    return;
+  }
+  if (command === 'doctor' || command === 'check') {
+    const parsed = options(args, command === 'doctor' ? { json: { type: 'boolean' } } : {});
+    if (parsed.values.help) return printHelp(command);
+    count(parsed.positionals, 0, 0, command);
+    const root = await findSite(cwd);
+    const result = await doctor(root);
+    console.log(parsed.values.json ? JSON.stringify(result, null, 2) : `环境检查通过\n站点：${result.root}\nNode ${result.node} · Core ${result.core} · Astro ${result.astro}\n主题：${result.theme} ${result.themeVersion}\n配置：${result.config}`);
+    if (command === 'check') await run(process.execPath, [astroEntry(root), 'sync'], root);
+    return;
+  }
+  throw new Error(`未知命令：${command}\n运行 mintfolio --help 查看可用命令。`);
+}
+
+try { await main(process.argv.slice(2)); }
+catch (error) {
+  process.stderr.write(`[mintfolio] ${error instanceof Error ? error.message : String(error)}\n`);
+  process.exitCode = error.exitCode || 1;
+}