@mintfolio/core 0.1.5

package/README.md

@@ -0,0 +1,104 @@
+<p align="center"><img src="docs/assets/mintfolio-icon.png" width="112" height="112" alt="Mintfolio" /></p>
+
+# Mintfolio
+
+把个人主页和博客放在一起，用 Markdown 写文章，用主题决定它们的样子。
+
+Mintfolio 基于 Astro。站点目录保存你的资料、文章和图片；引擎负责文章路由、搜索数据、RSS、Sitemap 和密码文章。换一个主题，内容仍然留在原处。
+
+[使用教程](https://github.com/cnflwzh/mintfolio/wiki/Getting-Started) · [命令参考](docs/cli.md) · [开发主题](https://github.com/cnflwzh/mintfolio/wiki/Theme-Development) · [更新记录](CHANGELOG.md) · [反馈问题](https://github.com/cnflwzh/mintfolio/issues)
+
+![Verdant 主题的个人主页](docs/assets/home-desktop.webp)
+
+*上图使用 Verdant 主题和示例资料。只安装引擎时，默认使用文字为主的 Minimal。*
+
+## 能做什么
+
+- 用 Markdown 管理文章，支持分类、标签、标题与摘要搜索。
+- 在主页展示个人资料、技能、项目和社交链接。
+- 为单篇文章设置密码，在浏览器中解锁正文。
+- 通过命令行新建草稿、安装主题、修改配置并构建网站。
+- 输出静态文件，部署到普通 Web 服务器或静态托管平台。
+
+Core 自带 Minimal；[Verdant](https://github.com/cnflwzh/mintfolio-theme-verdant) 提供文章卡片、八套配色、明暗模式、目录和阅读工具。第三方主题可以从两个 Astro 页面开始，再逐步补齐自己的布局。
+
+## 开始使用
+
+需要 **Node.js >= 22.12.0**。项目仍在持续开发中。
+
+~~~sh
+npm install -g @mintfolio/core
+mintfolio create my-blog
+cd my-blog
+mintfolio dev
+~~~
+
+打开终端显示的地址。编辑 site.config.ts 填写资料，文章放在 content/blog。
+
+想使用上图的 Verdant：
+
+~~~sh
+mintfolio theme install verdant --use
+~~~
+
+## 写第一篇文章
+
+~~~sh
+mintfolio post new "我的第一篇文章" --slug first-post
+~~~
+
+打开 content/blog/first-post.md 写正文。新文章默认是草稿，准备好后再发布并构建：
+
+~~~sh
+mintfolio post publish first-post
+mintfolio build
+mintfolio preview
+~~~
+
+post publish 修改本地草稿状态；build 生成 dist；部署时上传 dist 中的内容。[写作教程](https://github.com/cnflwzh/mintfolio/wiki/Writing) 介绍日期、封面、嵌套目录和密码文章。
+
+## 常用操作
+
+| 想做什么 | 命令或文件 |
+| --- | --- |
+| 修改网站标题 | mintfolio config set site site.title "我的博客" |
+| 编辑个人资料 | site.config.ts |
+| 调整主题设置 | mintfolio config edit theme |
+| 查看主题配置项 | mintfolio config schema theme |
+| 检查环境 | mintfolio doctor |
+| 查看命令帮助 | mintfolio --help |
+
+[配置教程](https://github.com/cnflwzh/mintfolio/wiki/Configuration) 说明内容与显示设置的区别、备案号、图片和配置优先级。
+
+## 界面
+
+![文章阅读](docs/assets/article-reading.webp)
+
+<p><img src="docs/assets/home-mobile.webp" width="280" alt="手机上的 Verdant 首页" /> <img src="docs/assets/encrypted-mobile.webp" width="280" alt="手机上的密码文章" /></p>
+
+## 开发状态
+
+当前重点是完善写作流程、主题接口和跨平台安装。0.x 阶段仍可能调整接口；升级前请保留源文件与锁文件，并阅读版本说明。
+
+目前需要知道的几件事：
+
+- 草稿在开发和生产构建中都不会公开显示。
+- 搜索匹配标题和公开摘要，不搜索全文；标签、分类与搜索共用博客归档页。
+- Minimal 目前不显示备案号；Verdant 的首页和普通页面支持 icp 字段。
+- 密码文章的正文和目录会被加密，标题、图片等信息仍公开。
+- CLI 负责本地操作与构建，部署由你选择的托管平台完成。
+
+## 仓库
+
+| 仓库 | 内容 |
+| --- | --- |
+| [mintfolio](https://github.com/cnflwzh/mintfolio) | 项目入口、CLI、博客引擎与 Minimal |
+| [mintfolio-theme-verdant](https://github.com/cnflwzh/mintfolio-theme-verdant) | Verdant 主题 |
+| [mintfolio-theme-api](https://github.com/cnflwzh/mintfolio-theme-api) | 主题的公共类型与契约 |
+| [mintfolio-theme-starter](https://github.com/cnflwzh/mintfolio-theme-starter) | 可直接修改的主题起点 |
+
+想贡献代码，从 [CONTRIBUTING.md](CONTRIBUTING.md) 开始。发现安全问题，请按 [SECURITY.md](SECURITY.md) 私下报告。
+
+## 许可证
+
+[GPL-3.0-only](LICENSE)。第三方依赖和资源保留各自许可证，见 [第三方声明](THIRD_PARTY_NOTICES.md)。

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,5 @@
+# 第三方依赖
+
+本仓库代码按 GPL-3.0-only 发布。npm 依赖保留各自许可证，请参阅对应包内的 LICENSE。
+
+vendor 保存真实 Mintfolio 安装快照，用于公共 npm 发布前的独立构建。更新时应保留包内许可证。

package/bin/lib/config-source.mjs

@@ -0,0 +1,147 @@
+import { parse } from '@babel/parser';
+import { keyPath } from './files.mjs';
+
+const wrappers = new Set(['TSAsExpression', 'TSSatisfiesExpression', 'TypeCastExpression', 'ParenthesizedExpression']);
+const unsupported = () => new Error('该字段使用动态表达式、展开或不明确的定义，请用 mintfolio config edit 打开配置文件修改。');
+
+function unwrap(node) {
+  while (node && wrappers.has(node.type)) node = node.expression;
+  return node;
+}
+
+/**
+ * Locate an exported config object without evaluating host code or its imports.
+ * Supports literals, top-level const aliases, TS satisfies/as, and defineSiteConfig.
+ * @param {string} source Original ESM/TypeScript source.
+ * @param {string} filename Used in syntax diagnostics.
+ * @returns {{source:string,root:object}} Parsed source with an editable object root.
+ */
+export function configSource(source, filename = 'config.mjs') {
+  const ast = parse(source, { sourceType: 'module', sourceFilename: filename, plugins: ['typescript'] });
+  const constants = new Map();
+  const siteHelpers = new Set();
+  for (const statement of ast.program.body) {
+    if (statement.type === 'VariableDeclaration' && statement.kind === 'const') {
+      for (const declaration of statement.declarations) if (declaration.id.type === 'Identifier') constants.set(declaration.id.name, declaration.init);
+    }
+    if (statement.type === 'ImportDeclaration' && statement.source.value === '@mintfolio/core/config') {
+      for (const specifier of statement.specifiers) if (specifier.type === 'ImportSpecifier' && specifier.imported.name === 'defineSiteConfig') siteHelpers.add(specifier.local.name);
+    }
+  }
+  const declaration = ast.program.body.find(statement => statement.type === 'ExportDefaultDeclaration');
+  if (!declaration) throw new Error(`${filename} 必须有 export default。`);
+  let root = unwrap(declaration.declaration);
+  const visited = new Set();
+  while (root?.type === 'Identifier') {
+    if (visited.has(root.name)) throw unsupported();
+    visited.add(root.name);
+    root = unwrap(constants.get(root.name));
+  }
+  if (root?.type === 'CallExpression' && root.callee.type === 'Identifier' && siteHelpers.has(root.callee.name) && root.arguments.length === 1) root = unwrap(root.arguments[0]);
+  if (root?.type !== 'ObjectExpression') throw unsupported();
+  return { source, root };
+}
+
+function propertyName(property) {
+  if (property.type !== 'ObjectProperty' || property.computed || property.method) throw unsupported();
+  if (property.key.type === 'Identifier') return property.key.name;
+  if (property.key.type === 'StringLiteral' || property.key.type === 'NumericLiteral') return String(property.key.value);
+  throw unsupported();
+}
+
+function properties(node) {
+  const entries = new Map();
+  for (const property of node.properties) {
+    const name = propertyName(property);
+    if (entries.has(name)) throw unsupported();
+    entries.set(name, property);
+  }
+  return entries;
+}
+
+/** @param {{source:string,root:object}} document @param {string[]} keys @returns {object|undefined} Source node for a direct field. */
+export function sourceNode(document, keys) {
+  let node = document.root;
+  for (const key of keys) {
+    node = unwrap(node);
+    if (node?.type === 'ObjectExpression') node = properties(node).get(key)?.value;
+    else if (node?.type === 'ArrayExpression' && /^(0|[1-9]\d*)$/.test(key)) node = node.elements[Number(key)];
+    else if (node === undefined) return undefined;
+    else throw unsupported();
+  }
+  return unwrap(node);
+}
+
+/**
+ * Read literal data. Expressions are represented explicitly, never executed.
+ * @param {{source:string,root:object}} document Parsed config.
+ * @param {object|undefined} [node] Node to inspect, or the default export.
+ * @returns {unknown} JSON-compatible value; dynamic leaves have a $expression key.
+ */
+export function sourceValue(document, node = document.root) {
+  node = unwrap(node);
+  if (!node) return undefined;
+  if (['StringLiteral', 'NumericLiteral', 'BooleanLiteral'].includes(node.type)) return node.value;
+  if (node.type === 'NullLiteral') return null;
+  if (node.type === 'UnaryExpression' && node.operator === '-' && node.argument.type === 'NumericLiteral') return -node.argument.value;
+  if (node.type === 'TemplateLiteral' && node.expressions.length === 0) return node.quasis[0].value.cooked;
+  if (node.type === 'ArrayExpression') return node.elements.map(element => element ? sourceValue(document, element) : null);
+  if (node.type === 'ObjectExpression') return Object.fromEntries([...properties(node)].map(([name, property]) => [name, sourceValue(document, property.value)]));
+  return { $expression: document.source.slice(node.start, node.end) };
+}
+
+function indentation(source, index) {
+  return source.slice(source.lastIndexOf('\n', index - 1) + 1, index).match(/^[\t ]*/)[0];
+}
+
+/**
+ * Change just one field's source range, preserving imports and surrounding comments.
+ * Unknown intermediate objects are created; ambiguous/dynamic containers fail.
+ * @param {string} source Original ESM/TS content.
+ * @param {string} key Dotted field path; numeric segments address existing array items.
+ * @param {unknown} value JSON-serializable replacement.
+ * @param {string} [filename] Diagnostic filename.
+ * @returns {string} Updated source, still with the original surrounding formatting.
+ */
+export function setSourceValue(source, key, value, filename) {
+  const document = configSource(source, filename);
+  const keys = keyPath(key);
+  const eol = source.includes('\r\n') ? '\r\n' : '\n';
+  const format = (input, indent) => JSON.stringify(input, null, 2).replace(/\n/g, eol + indent);
+  let container = document.root;
+  for (let index = 0; index < keys.length; index++) {
+    container = unwrap(container);
+    const name = keys[index];
+    let node;
+    let property;
+    if (container?.type === 'ObjectExpression') {
+      property = properties(container).get(name);
+      node = property?.value;
+    } else if (container?.type === 'ArrayExpression' && /^(0|[1-9]\d*)$/.test(name) && Number(name) < container.elements.length) node = container.elements[Number(name)];
+    else throw unsupported();
+    if (node && index < keys.length - 1) { container = node; continue; }
+    let replacement = value;
+    for (const tail of keys.slice(index + 1).reverse()) {
+      if (/^\d+$/.test(tail)) throw new Error('不能通过下标创建数组，请用 JSON 设置完整数组。');
+      replacement = { [tail]: replacement };
+    }
+    if (node) {
+      if (property?.shorthand) return source.slice(0, property.start) + `${name}: ${format(replacement, indentation(source, property.start))}` + source.slice(property.end);
+      return source.slice(0, node.start) + format(replacement, indentation(source, node.start)) + source.slice(node.end);
+    }
+    const last = container.properties.at(-1);
+    const baseIndent = indentation(source, container.start);
+    const indent = last ? indentation(source, last.start) || baseIndent + '  ' : baseIndent + '  ';
+    const entry = `${JSON.stringify(name)}: ${format(replacement, indent)},`;
+    const insertion = `${eol}${indent}${entry}${eol}${baseIndent}`;
+    const edits = [{ start: container.end - 1, end: container.end - 1, text: insertion }];
+    // Babel excludes a property's trailing comma from its range. Ignore comments
+    // while checking that comma, then place any missing comma before the comment.
+    if (last && !/^\s*,/.test(source.slice(last.end, container.end - 1).replace(/\/\*[\s\S]*?\*\/|\/\/[^\r\n]*/g, ''))) edits.push({ start: last.end, end: last.end, text: ',' });
+    let result = source;
+    for (const edit of edits.sort((a, b) => b.start - a.start)) result = result.slice(0, edit.start) + edit.text + result.slice(edit.end);
+    configSource(result, filename);
+    return result;
+  }
+  throw unsupported();
+}

package/bin/lib/config.mjs

@@ -0,0 +1,144 @@
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { z } from 'astro/zod';
+import { activeTheme, readSelection } from './themes.mjs';
+import { createThemeConfig } from '../theme-config.mjs';
+import { loadTheme } from '../../src/engine/loader.mjs';
+import { resolveSettings } from '../../src/engine/schema.mjs';
+import { configSource, setSourceValue, sourceNode, sourceValue } from './config-source.mjs';
+import { checkedPath, getIn, keyPath, saveFile, setIn } from './files.mjs';
+
+const string = z.string();
+const image = z.union([string, z.object({ src: string, width: z.number(), height: z.number(), format: string.optional() })]);
+/** CLI input validation mirrors the public SiteConfigInput, without evaluating site imports. */
+const siteSchema = z.object({
+  site: z.object({
+    title: string.refine(value => value.trim().length > 0, '标题不能为空'),
+    url: string.url().refine(value => ['http:', 'https:'].includes(new URL(value).protocol), '域名须使用 HTTP 或 HTTPS'),
+    description: string.optional(), language: string.optional(),
+  }).strict(),
+  profile: z.object({ name: string.optional(), avatar: image.optional(), bio: string.optional(), location: string.optional(), signature: string.optional() }).strict(),
+  social: z.array(z.object({ platform: string, url: string, icon: string }).strict()),
+  skills: z.array(z.object({ category: string, items: z.array(z.object({ name: string, level: z.number().min(0).max(100) }).strict()) }).strict()),
+  projects: z.array(z.object({ title: string, description: string, link: string.optional(), repo: string.optional(), tags: z.array(string), image: string.optional() }).strict()),
+  contact: z.object({ email: string.optional(), social: z.array(string).optional() }).strict(),
+  icp: string,
+}).strict();
+
+function siteField(keys) {
+  let field = siteSchema;
+  for (const key of keys) {
+    while (field instanceof z.ZodOptional) field = field.unwrap();
+    if (field instanceof z.ZodObject) field = field.shape[key];
+    else if (field instanceof z.ZodArray && /^(0|[1-9]\d*)$/.test(key)) field = field.element;
+    else field = undefined;
+    if (!field) throw new Error(`未知站点配置项：${keys.join('.')}`);
+  }
+  return field;
+}
+
+/**
+ * Parse values against the target field. String fields keep numeric-looking text;
+ * booleans/numbers/arrays/objects use JSON. --json forces explicit JSON parsing.
+ * @param {string} raw Literal argument. @param {(value:unknown)=>unknown} validate Target validator.
+ * @param {boolean} json Force JSON, including JSON strings.
+ * @returns {unknown} Validated replacement value.
+ */
+export function inputValue(raw, validate, json = false) {
+  if (!json) {
+    try { return validate(raw); } catch {}
+  }
+  let parsed;
+  try { parsed = JSON.parse(raw); }
+  catch { throw new Error('值的类型不正确：布尔值使用 true/false，数字直接填写，数组和对象使用 JSON。'); }
+  return validate(parsed);
+}
+
+/** @param {string} root @param {'site'|'theme'} scope @param {string} [selector] Theme selector for inactive settings. @returns {Promise<string>} Checked editable config path. */
+export async function configFilename(root, scope, selector) {
+  if (scope === 'site') {
+    const selection = await readSelection(root);
+    return checkedPath(root, path.resolve(root, selection.siteConfig || 'site.config.ts'));
+  }
+  if (scope === 'theme') {
+    // Opening an editor must still work when the editable settings are invalid.
+    const theme = selector || (await readSelection(root)).theme || 'minimal';
+    return (await loadTheme({ root, theme, readUserConfig: false })).themeConfigFile;
+  }
+  throw new Error('配置范围为 site 或 theme。');
+}
+
+/** @param {string} root @param {'site'|'theme'} scope @param {string} [key] Optional dotted field. @param {string} [selector] @returns {Promise<unknown>} Literal site values or effective theme settings. */
+export async function getConfig(root, scope, key, selector) {
+  const keys = key ? keyPath(key) : [];
+  let value;
+  if (scope === 'theme') value = getIn((await activeTheme(root, selector)).settings, keys);
+  else {
+    const filename = await configFilename(root, scope, selector);
+    const document = configSource(await readFile(filename, 'utf8'), filename);
+    const node = sourceNode(document, keys);
+    value = node ? sourceValue(document, node) : undefined;
+  }
+  if (value === undefined) throw new Error(`配置项未填写或不存在：${key}`);
+  return value;
+}
+
+/**
+ * Validate and edit one site/theme field, with source-preserving backup writes.
+ * Existing legacy inline overrides remain authoritative, so edits target that
+ * override when it owns the field; otherwise they target the theme-specific file.
+ * @param {string} root Site root.
+ * @param {'site'|'theme'} scope Which config family to change.
+ * @param {string} key Dotted field path.
+ * @param {string} raw Literal argument or JSON text.
+ * @param {{theme?:string,json?:boolean}} [options] Optional inactive theme and forced JSON.
+ * @returns {Promise<{filename:string,value:unknown,backup:string|null}>} Actual file, validated value and backup.
+ */
+export async function setConfig(root, scope, key, raw, options = {}) {
+  const keys = keyPath(key);
+  let filename;
+  let value;
+  let sourceKey = key;
+  if (scope === 'site') {
+    const field = siteField(keys);
+    value = inputValue(raw, candidate => field.parse(candidate), options.json);
+    filename = await configFilename(root, scope);
+  } else if (scope === 'theme') {
+    const active = await activeTheme(root, options.theme);
+    const validate = candidate => {
+      const settings = structuredClone(active.settings);
+      setIn(settings, keys, candidate);
+      resolveSettings(active.definition, settings);
+      return candidate;
+    };
+    value = inputValue(raw, validate, options.json);
+    if (active.same && getIn(active.selection.settings, keys) !== undefined) {
+      filename = path.join(root, 'theme.config.mjs');
+      sourceKey = `settings.${key}`;
+    } else {
+      filename = (await createThemeConfig(root, active.selector)).filename;
+    }
+  } else throw new Error('配置范围为 site 或 theme。');
+  await checkedPath(root, filename);
+  const original = await readFile(filename, 'utf8');
+  const source = setSourceValue(original, sourceKey, value, filename);
+  return { filename, value, backup: await saveFile(root, filename, original, source) };
+}
+
+/** @param {string} root @param {'site'|'theme'} scope @param {string} [selector] @returns {Promise<unknown>} Available setting names and constraints. */
+export async function configSchema(root, scope, selector) {
+  if (scope === 'theme') {
+    const theme = selector || (await readSelection(root)).theme || 'minimal';
+    return (await loadTheme({ root, theme, readUserConfig: false })).definition.settings;
+  }
+  if (scope !== 'site') throw new Error('配置范围为 site 或 theme。');
+  return {
+    site: ['title', 'url', 'description', 'language'],
+    profile: ['name', 'avatar', 'bio', 'location', 'signature'],
+    social: 'JSON 数组：{ platform, url, icon }',
+    skills: 'JSON 数组：{ category, items: [{ name, level: 0–100 }] }',
+    projects: 'JSON 数组：{ title, description, tags, link?, repo?, image? }',
+    contact: { email: '字符串', social: '平台名字符串数组' },
+    icp: '字符串',
+  };
+}

package/bin/lib/files.mjs

@@ -0,0 +1,103 @@
+import { mkdir, readFile, realpath, rename, stat, writeFile, unlink } from 'node:fs/promises';
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+
+/** @param {string} filename @returns {Promise<boolean>} Whether a filesystem entry exists. */
+export async function exists(filename) {
+  try { await stat(filename); return true; }
+  catch (error) { if (error.code === 'ENOENT') return false; throw error; }
+}
+
+/** @param {string} start Working directory, including a site subdirectory. @returns {Promise<string>} Real site root. */
+export async function findSite(start) {
+  let directory = await realpath(start);
+  while (true) {
+    if (await exists(path.join(directory, 'package.json')) && await exists(path.join(directory, 'theme.config.mjs'))) return directory;
+    const parent = path.dirname(directory);
+    if (parent === directory) throw new Error('当前目录不在 Mintfolio 站点中。请进入站点，或使用 mintfolio create <目录>。');
+    directory = parent;
+  }
+}
+
+/** @param {string} filename @param {string} root @returns {boolean} True when the path is contained by root. */
+export function within(filename, root) {
+  const relative = path.relative(root, filename);
+  return relative === '' || (!relative.startsWith(`..${path.sep}`) && relative !== '..' && !path.isAbsolute(relative));
+}
+
+/**
+ * Check both lexical and real ancestors before reading or writing host files.
+ * @param {string} root Allowed site/content root.
+ * @param {string} filename Absolute target, which may not exist yet.
+ * @returns {Promise<string>} Checked absolute filename; escaping symlinks fail.
+ */
+export async function checkedPath(root, filename) {
+  const base = await realpath(root);
+  const target = path.resolve(filename);
+  if (!within(target, base)) throw new Error('文件路径必须位于站点目录内。');
+  let ancestor = target;
+  while (!await exists(ancestor)) ancestor = path.dirname(ancestor);
+  if (!within(await realpath(ancestor), base)) throw new Error('文件路径通过符号链接离开了站点目录。');
+  return target;
+}
+
+/**
+ * Replace one file only if it still matches the inspected version. Keep an exact
+ * backup, then rename a complete sibling file so readers never see partial text.
+ * @param {string} root Site root.
+ * @param {string} filename Existing editable file within root.
+ * @param {string} original Expected UTF-8 content.
+ * @param {string} source Replacement UTF-8 content.
+ * @returns {Promise<string|null>} Backup path, or null when unchanged.
+ */
+export async function saveFile(root, filename, original, source) {
+  if (source === original) return null;
+  await checkedPath(root, filename);
+  if (await readFile(filename, 'utf8') !== original) throw new Error(`文件已被其他程序修改，请重试：${filename}`);
+  const backup = path.join(root, '.mintfolio', 'backups', `${Date.now()}-${randomUUID()}`, path.relative(root, filename));
+  await checkedPath(root, backup);
+  await mkdir(path.dirname(backup), { recursive: true });
+  await writeFile(backup, original, { flag: 'wx' });
+  const temporary = path.join(path.dirname(filename), `.${path.basename(filename)}.${randomUUID()}.tmp`);
+  try {
+    await writeFile(temporary, source, { flag: 'wx', mode: (await stat(filename)).mode });
+    if (await readFile(filename, 'utf8') !== original) throw new Error(`文件在保存前发生变化，请重试：${filename}`);
+    await rename(temporary, filename);
+  } finally {
+    await unlink(temporary).catch(error => { if (error.code !== 'ENOENT') throw error; });
+  }
+  return backup;
+}
+
+/** @param {unknown} value @returns {string} Human-readable values or JSON for structured CLI output. */
+export function display(value) { return typeof value === 'string' ? value : JSON.stringify(value, null, 2); }
+
+/** @param {string} key Dotted field path. @returns {string[]} Safe property segments, including array indices. */
+export function keyPath(key) {
+  const keys = key.split('.');
+  if (!key || keys.some(part => !/^(?:[A-Za-z_$][\w$-]*|0|[1-9]\d*)$/.test(part) || ['__proto__', 'prototype', 'constructor'].includes(part))) throw new Error(`无效配置路径：${key}`);
+  return keys;
+}
+
+/** @param {unknown} object @param {string[]} keys @returns {unknown} Own-property lookup without executing expressions. */
+export function getIn(object, keys) {
+  let current = object;
+  for (const key of keys) {
+    if (!current || typeof current !== 'object' || !Object.hasOwn(current, key)) return undefined;
+    current = current[key];
+  }
+  return current;
+}
+
+/** @param {Record<string,unknown>} object JSON-compatible settings clone. @param {string[]} keys @param {unknown} value */
+export function setIn(object, keys, value) {
+  let current = object;
+  for (const key of keys.slice(0, -1)) {
+    if (current[key] === undefined) current[key] = {};
+    if (!current[key] || typeof current[key] !== 'object') throw new Error(`不能在非对象字段下添加设置：${key}`);
+    current = current[key];
+  }
+  const last = keys.at(-1);
+  if (Array.isArray(current) && (!/^(0|[1-9]\d*)$/.test(last) || Number(last) >= current.length)) throw new Error('数组下标超出范围；请用 JSON 设置完整数组。');
+  current[last] = value;
+}

package/bin/lib/init.mjs

@@ -0,0 +1,67 @@
+import { readFile, writeFile, mkdir } from "node:fs/promises";
+import path from "node:path";
+import { syncThemeConfigs, reportThemeConfigs } from "../theme-config.mjs";
+import { checkedPath } from './files.mjs';
+
+/** Write scaffold files exclusively: initialization never overwrites site content. */
+async function writeNew(root, relative, source) {
+  const destination = path.resolve(root, relative);
+  const within = path.relative(root, destination);
+  if (!within || within.startsWith('..') || path.isAbsolute(within)) throw new Error('Invalid scaffold destination');
+  await checkedPath(root, destination);
+  await mkdir(path.dirname(destination), { recursive: true });
+  try { await writeFile(destination, source, { flag: 'wx' }); process.stdout.write(`Created ${relative}\n`); }
+  catch (error) { if (error.code !== 'EEXIST') throw error; }
+}
+
+/**
+ * Scaffold a site without replacing existing files or npm scripts.
+ * @param {string} root Existing absolute site directory with Core installed.
+ * @returns {Promise<void>} Creates missing config/content files and theme defaults.
+ */
+export async function initialize(root) {
+  await writeNew(root, '.gitignore', 'node_modules/\ndist/\n.astro/\n.mintfolio/\n.cache/\n.env\n.env.*\n');
+  await writeNew(root, 'astro.config.mjs', `import { defineConfig } from 'astro/config';
+import mintfolio from '@mintfolio/core';
+import theme from './theme.config.mjs';
+export default defineConfig({ integrations: [mintfolio(theme)] });
+`);
+  await writeNew(root, 'theme.config.mjs', `/** Omit theme to use Core's Minimal, or select an installed theme package. */
+export default {};
+`);
+  await writeNew(root, 'site.config.ts', `import { defineSiteConfig } from '@mintfolio/core/config';
+export default defineSiteConfig({
+  site: { title: '我的博客', description: '记录与分享', url: 'https://example.com', language: 'zh-CN' },
+  profile: { name: '作者', bio: '欢迎来到我的博客。' },
+});
+`);
+  await writeNew(root, 'src/content.config.ts', `import { createBlogCollection } from '@mintfolio/core/content';
+export const collections = { blog: createBlogCollection() };
+`);
+  await writeNew(root, 'tsconfig.json', JSON.stringify({ extends: 'astro/tsconfigs/strict', include: ['.astro/types.d.ts', 'src/**/*', 'site.config.ts'] }, null, 2) + '\n');
+  await mkdir(path.join(root, 'public'), { recursive: true });
+  await writeNew(root, 'content/blog/hello.md', `---
+title: "你好，Mintfolio"
+pubDate: 2026-01-01
+description: "这是你的第一篇文章。"
+category: "随笔"
+tags: ["开始"]
+---
+
+## 开始写作
+
+把 Markdown 文章放到 \`content/blog/\`，Core 会生成文章、归档和订阅源。
+
+安装主题包后，在 \`theme.config.mjs\` 中填写包名即可切换布局。
+`);
+  const filename = path.join(root, 'package.json');
+  const existing = await readFile(filename, 'utf8').catch((error) => { if (error.code === 'ENOENT') return '{}'; throw error; });
+  const pkg = JSON.parse(existing);
+  pkg.name ??= 'my-mintfolio-blog';
+  pkg.private ??= true;
+  pkg.type = 'module';
+  pkg.scripts = { dev: 'mintfolio dev', build: 'mintfolio build', preview: 'mintfolio preview', ...pkg.scripts };
+  await writeFile(filename, JSON.stringify(pkg, null, 2) + '\n');
+  reportThemeConfigs(await syncThemeConfigs(root));
+  process.stdout.write('Ready. Edit site.config.ts, then run npm run dev.\n');
+}