hd-garden 0.3.9 → 0.3.11

package/scripts/build-ui-preview.mjs

@@ -0,0 +1,29 @@
+import fs from "node:fs";
+import path from "node:path";
+import { build } from "esbuild";
+import { gardenPackageRoot } from "./garden-paths.mjs";
+
+const root = gardenPackageRoot;
+const out = path.join(root, "ui", "preview", "dist");
+fs.rmSync(out, { recursive: true, force: true });
+fs.mkdirSync(out, { recursive: true });
+
+const shared = {
+  entryPoints: [path.join(root, "ui", "preview", "index.tsx")],
+  bundle: true,
+  minify: true,
+  jsx: "automatic",
+  platform: "browser",
+  target: ["es2020"],
+  define: { "process.env.NODE_ENV": '"production"' },
+  alias: { mermaid: path.join(root, "ui", "preview", "mermaid-shim.ts") },
+  legalComments: "none",
+  logLevel: "warning",
+};
+
+await build({ ...shared, format: "iife", globalName: "GardenUI", outfile: path.join(out, "garden-ui.iife.js") });
+await build({ ...shared, format: "esm", outfile: path.join(out, "garden-ui.esm.js") });
+fs.copyFileSync(path.join(root, "ui", "react", "ui.css"), path.join(out, "garden-ui.css"));
+
+const size = (file) => `${(fs.statSync(path.join(out, file)).size / 1024).toFixed(0)} KB`;
+process.stdout.write(`预览包已生成：garden-ui.iife.js ${size("garden-ui.iife.js")}，garden-ui.esm.js ${size("garden-ui.esm.js")}，garden-ui.css\n`);

package/scripts/check-post.mjs

@@ -4,6 +4,7 @@ import matter from "gray-matter";
 import { parse as parseYaml } from "yaml";
 import { canonicalSiteDate } from "./site-date.mjs";
 import { gardenSiteRoot } from "./garden-paths.mjs";
+import { checkUiBlock } from "../ui/core/validate.mjs";
 
 const siteRoot = gardenSiteRoot();
 const calloutTypes = new Set([
@@ -184,7 +185,22 @@ const checkEmbed = (errors, body, sourcePath, line) => {
   }
 };
 
-const scanBody = (errors, content, markdownPath, sourcePath) => {
+const checkUi = (errors, warnings, body, markdownPath, sourcePath, line) => {
+  const relative = path.relative(path.join(siteRoot, "content"), markdownPath).split(path.sep).join("/");
+  const result = checkUiBlock(body, {
+    lineOffset: line,
+    markdownPath: relative,
+    readData: (src) => {
+      const absolute = path.resolve(path.dirname(markdownPath), src);
+      return fs.existsSync(absolute) ? fs.readFileSync(absolute, "utf8") : undefined;
+    },
+  });
+  for (const item of result.diagnostics) {
+    (item.severity === "warning" ? warnings : errors).push({ code: item.code, line: item.line, message: `${sourcePath}: ${item.message}` });
+  }
+};
+
+const scanBody = (errors, content, markdownPath, sourcePath, { warnings = [], draft = false } = {}) => {
   let fence = null;
   let previousDepth = 1;
   const lines = content.split(/\r?\n/u);
@@ -195,6 +211,10 @@ const scanBody = (errors, content, markdownPath, sourcePath) => {
       if (opener && opener[1][0] === fence.marker && opener[1].length >= fence.marker.length && !opener[2].trim()) {
         if (fence.lang === "widget") checkWidget(errors, fence.body.join("\n"), markdownPath, sourcePath, fence.line);
         if (fence.lang === "embed") checkEmbed(errors, fence.body.join("\n"), sourcePath, fence.line);
+        if (fence.lang === "ui") checkUi(errors, warnings, fence.body.join("\n"), markdownPath, sourcePath, fence.line);
+        if (fence.lang === "intent" && !draft) {
+          error(errors, "intent-uncompiled", fence.line, `${sourcePath}: 还有没编译的 intent 块；对 AI 说「编译这篇」`);
+        }
         fence = null;
       } else {
         fence.body.push(line);
@@ -238,9 +258,10 @@ const checkFile = (filePath) => {
   const absolute = path.resolve(siteRoot, filePath);
   const sourcePath = path.relative(siteRoot, absolute);
   const errors = [];
+  const warnings = [];
   if (!fs.existsSync(absolute)) {
     error(errors, "missing-file", 1, `${sourcePath}: 找不到文件`);
-    return { file: sourcePath, errors };
+    return { file: sourcePath, errors, warnings };
   }
   const parsed = matter(fs.readFileSync(absolute, "utf8"), matterOptions);
   const data = parsed.data ?? {};
@@ -266,8 +287,9 @@ const checkFile = (filePath) => {
     }
   }
   checkReferences(data, sourcePath, errors);
-  scanBody(errors, parsed.content, absolute, sourcePath);
-  return { file: sourcePath, errors };
+  const draft = data.draft === true || (typeof data.publishAt === "string" && Date.parse(canonicalSiteDate(data.publishAt) ?? "") > Date.now());
+  scanBody(errors, parsed.content, absolute, sourcePath, { warnings, draft });
+  return { file: sourcePath, errors, warnings };
 };
 
 const files = process.argv.slice(2);

package/scripts/ui-cli.mjs

@@ -0,0 +1,303 @@
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import matter from "gray-matter";
+import { parse as parseYaml } from "yaml";
+import { applyBlock, ApplyError } from "../ui/core/apply.mjs";
+import { catalogSchema } from "../ui/core/catalog.mjs";
+import { buildFixPrompt } from "../ui/core/fix-prompt.mjs";
+import { scanMarkdown } from "../ui/core/scan.mjs";
+import { buildPrompt, RECIPE_FILES } from "../ui/prompt/build.mjs";
+import { canonicalSiteDate } from "./site-date.mjs";
+import { gardenPackageRoot, gardenSiteRoot } from "./garden-paths.mjs";
+
+const siteRoot = gardenSiteRoot();
+const [command, ...rest] = process.argv.slice(2);
+
+function fail(message, code = 1) {
+  process.stderr.write(`${message}\n`);
+  process.exit(code);
+}
+
+function flag(name) {
+  return rest.includes(`--${name}`);
+}
+
+function option(name) {
+  const index = rest.indexOf(`--${name}`);
+  if (index < 0) return null;
+  const value = rest[index + 1];
+  if (!value || value.startsWith("--")) fail(`--${name} 需要一个值`);
+  return value;
+}
+
+function positional() {
+  const values = [];
+  for (let index = 0; index < rest.length; index += 1) {
+    const value = rest[index];
+    if (value.startsWith("--")) {
+      if (["id", "at", "intent-hash", "base", "file", "out"].includes(value.slice(2))) index += 1;
+      continue;
+    }
+    values.push(value);
+  }
+  return values;
+}
+
+const promptRoot = path.join(gardenPackageRoot, "ui", "prompt");
+
+function promptText({ studio = false } = {}) {
+  return buildPrompt({
+    rules: fs.readFileSync(path.join(promptRoot, "rules.md"), "utf8"),
+    recipes: RECIPE_FILES.map((file) => fs.readFileSync(path.join(promptRoot, "recipes", file), "utf8")),
+    studio: studio ? fs.readFileSync(path.join(promptRoot, "studio.md"), "utf8") : null,
+  });
+}
+
+const toPosix = (value) => value.split(path.sep).join("/");
+
+function git(args, { input, allowFail = false } = {}) {
+  const result = spawnSync("git", args, { cwd: siteRoot, encoding: "utf8", input, maxBuffer: 64 * 1024 * 1024 });
+  if (result.status !== 0) {
+    if (allowFail) return null;
+    fail(`git ${args.join(" ")} 失败：${(result.stderr || "").trim()}`);
+  }
+  return result.stdout;
+}
+
+function isDraft(markdown) {
+  try {
+    const { data } = matter(markdown, { engines: { yaml: { parse: (input) => parseYaml(input) ?? {} } } });
+    if (data.draft === true) return true;
+    const publish = canonicalSiteDate(data.publishAt ?? data.date);
+    return Boolean(publish) && Date.parse(publish) > Date.now();
+  } catch {
+    return false;
+  }
+}
+
+function listContentFiles(directory) {
+  if (!fs.existsSync(directory)) return [];
+  return fs.readdirSync(directory, { withFileTypes: true }).flatMap((entry) => {
+    const full = path.join(directory, entry.name);
+    if (entry.isDirectory()) return listContentFiles(full);
+    return entry.name.endsWith(".md") ? [full] : [];
+  });
+}
+
+/** Files to check, each with a reader for itself and its same-name directory. */
+function targets() {
+  if (flag("staged")) {
+    const top = git(["rev-parse", "--show-toplevel"]).trim();
+    const names = git(["diff", "--cached", "--name-only", "--diff-filter=ACMR", "-z"]).split("\0").filter(Boolean);
+    return names
+      .filter((name) => name.endsWith(".md"))
+      .map((name) => ({ absolute: path.join(top, name), repoPath: name }))
+      .filter((item) => toPosix(path.relative(siteRoot, item.absolute)).startsWith("content/"))
+      .map((item) => ({
+        file: toPosix(path.relative(siteRoot, item.absolute)),
+        read: () => git(["show", `:${item.repoPath}`]),
+        readSibling: (relative) => {
+          const repoRelative = toPosix(path.join(path.dirname(item.repoPath), relative));
+          return git(["show", `:${repoRelative}`], { allowFail: true }) ?? undefined;
+        },
+      }));
+  }
+  const files = flag("all") ? listContentFiles(path.join(siteRoot, "content")) : positional().map((file) => path.resolve(siteRoot, file));
+  return files.map((absolute) => ({
+    file: toPosix(path.relative(siteRoot, absolute)),
+    read: () => {
+      if (!fs.existsSync(absolute)) fail(`找不到文件 ${absolute}`);
+      return fs.readFileSync(absolute, "utf8");
+    },
+    readSibling: (relative) => {
+      const target = path.resolve(path.dirname(absolute), relative);
+      return fs.existsSync(target) && fs.statSync(target).isFile() ? fs.readFileSync(target, "utf8") : undefined;
+    },
+  }));
+}
+
+function scanTarget(target) {
+  const markdown = target.read();
+  const blocks = scanMarkdown(markdown, { markdownPath: target.file, readData: target.readSibling });
+  return { markdown, blocks, draft: isDraft(markdown) };
+}
+
+function copyToClipboard(text) {
+  const candidates = process.platform === "darwin"
+    ? [["pbcopy", []]]
+    : process.platform === "win32"
+      ? [["clip", []]]
+      : [["wl-copy", []], ["xclip", ["-selection", "clipboard"]], ["xsel", ["--clipboard", "--input"]]];
+  for (const [binary, args] of candidates) {
+    const result = spawnSync(binary, args, { input: text });
+    if (result.status === 0) return true;
+  }
+  return false;
+}
+
+function commandScan() {
+  const files = targets();
+  if (!files.length) fail("用法：garden ui scan content/posts/文章.md");
+  const output = files.map((target) => {
+    const { blocks, draft } = scanTarget(target);
+    return {
+      file: target.file,
+      draft,
+      blocks: blocks.map((block) => Object.fromEntries(Object.entries(block).filter(([key]) => key !== "raw"))),
+    };
+  });
+  process.stdout.write(`${JSON.stringify(output.length === 1 ? output[0] : output, null, 2)}\n`);
+}
+
+function commandCheck() {
+  const files = targets();
+  if (!files.length) {
+    if (flag("staged")) process.exit(0);
+    fail("用法：garden ui check content/posts/文章.md [--staged] [--all] [--standalone]");
+  }
+  const problems = [];
+  const warnings = [];
+  for (const target of files) {
+    const { blocks, draft } = scanTarget(target);
+    for (const block of blocks) {
+      const errors = block.diagnostics.filter((item) => item.severity === "error");
+      for (const item of block.diagnostics.filter((entry) => entry.severity === "warning")) {
+        warnings.push(`${target.file}:${item.line}  ${block.id ?? "-"}  ${item.code}  ${item.message}`);
+      }
+      if (block.lang === "intent" && !draft) problems.push({ file: target.file, block, diagnostics: [] });
+      else if (errors.length) problems.push({ file: target.file, block, diagnostics: errors });
+    }
+  }
+  for (const line of warnings) process.stderr.write(`提醒  ${line}\n`);
+  if (!problems.length) {
+    if (!flag("quiet")) process.stdout.write(`ui 检查通过（${files.length} 个文件）\n`);
+    return;
+  }
+  for (const problem of problems) {
+    if (problem.block.lang === "intent") {
+      process.stderr.write(`${problem.file}:${problem.block.startLine}  ${problem.block.id ?? "-"}  intent-uncompiled  还有没编译的 intent 块\n`);
+    }
+    for (const item of problem.diagnostics) {
+      process.stderr.write(`${problem.file}:${item.line}  ${problem.block.id ?? "-"}  ${item.code}  ${item.message}\n`);
+    }
+  }
+  const prompt = buildFixPrompt(problems, { standaloneReference: flag("standalone") ? promptText() : null });
+  const separator = "─".repeat(24);
+  process.stderr.write(`\n${separator} 发给 AI 的修复提示词 ${separator}\n${prompt}${separator}${separator}${"─".repeat(12)}\n`);
+  const promptFile = path.join(siteRoot, ".garden", "ui-fix-prompt.md");
+  fs.mkdirSync(path.dirname(promptFile), { recursive: true });
+  fs.writeFileSync(promptFile, prompt);
+  const copied = !flag("no-copy") && process.env.GARDEN_UI_NO_COPY !== "1" && copyToClipboard(prompt);
+  process.stderr.write(`已写入 ${toPosix(path.relative(siteRoot, promptFile))}${copied ? "，并已复制到剪贴板" : ""}。确实要先提交，可以用 git commit --no-verify。\n`);
+  process.exit(1);
+}
+
+function readStdin() {
+  try {
+    return fs.readFileSync(0, "utf8");
+  } catch {
+    return "";
+  }
+}
+
+function commandApply() {
+  const [file] = positional();
+  if (!file) fail("用法：garden ui apply content/posts/文章.md --id <id> [--base <哈希>] [--file 新内容.md]");
+  const absolute = path.resolve(siteRoot, file);
+  if (!fs.existsSync(absolute)) fail(`找不到文件 ${file}`);
+  const source = option("file");
+  const replacement = source ? fs.readFileSync(path.resolve(process.cwd(), source), "utf8") : readStdin();
+  if (!replacement.trim()) fail("没有拿到新内容：用 --file 指定，或从标准输入传入");
+  const target = { id: option("id"), at: option("at"), intentHash: option("intent-hash") };
+  try {
+    const markdown = fs.readFileSync(absolute, "utf8");
+    const result = applyBlock(markdown, target, replacement, {
+      base: option("base"),
+      markdownPath: toPosix(path.relative(siteRoot, absolute)),
+      readData: (relative) => {
+        const sibling = path.resolve(path.dirname(absolute), relative);
+        return fs.existsSync(sibling) ? fs.readFileSync(sibling, "utf8") : undefined;
+      },
+    });
+    fs.writeFileSync(absolute, result.markdown);
+    process.stdout.write(`${JSON.stringify({ ok: true, file: toPosix(path.relative(siteRoot, absolute)), kind: result.kind, line: result.block.startLine })}\n`);
+  } catch (error) {
+    if (!(error instanceof ApplyError)) throw error;
+    process.stderr.write(`${JSON.stringify({ ok: false, code: error.code, message: error.message, diagnostics: error.diagnostics }, null, 2)}\n`);
+    process.exit(1);
+  }
+}
+
+function openPath(target) {
+  const opener = process.platform === "darwin" ? ["open", [target]] : process.platform === "win32" ? ["cmd", ["/c", "start", "", target]] : ["xdg-open", [target]];
+  spawnSync(opener[0], opener[1], { stdio: "ignore" });
+}
+
+function commandCatalog() {
+  const dist = path.join(gardenPackageRoot, "ui", "preview", "dist");
+  const script = path.join(dist, "garden-ui.iife.js");
+  const style = path.join(dist, "garden-ui.css");
+  if (!fs.existsSync(script) || !fs.existsSync(style)) {
+    fail("缺少编辑器预览包。在引擎仓库运行 npm run ui:build 后再试。");
+  }
+  const recipes = RECIPE_FILES.map((file) => ({ file, markdown: fs.readFileSync(path.join(promptRoot, "recipes", file), "utf8") }));
+  const json = JSON.stringify(recipes).replaceAll("<", "\\u003c");
+  const html = `<!doctype html>
+<html lang="zh-CN">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Garden 组件清单</title>
+<style>body{margin:0;background:#f8f8f6;color:#202124}main{max-width:760px;margin:0 auto;padding:32px 20px 80px}@media (prefers-color-scheme: dark){body{background:#171819;color:#ededeb}}</style>
+<style>${fs.readFileSync(style, "utf8")}</style>
+</head>
+<body>
+<main id="catalog"></main>
+<script>${fs.readFileSync(script, "utf8").replaceAll("</script", "<\\/script")}</script>
+<script>
+const root = document.getElementById("catalog");
+if (window.matchMedia("(prefers-color-scheme: dark)").matches) root.setAttribute("data-theme", "dark");
+GardenUI.renderCatalog(root, { recipes: ${json} });
+</script>
+</body>
+</html>
+`;
+  const out = path.resolve(siteRoot, option("out") ?? path.join(".garden", "ui-catalog.html"));
+  fs.mkdirSync(path.dirname(out), { recursive: true });
+  fs.writeFileSync(out, html);
+  process.stdout.write(`组件清单已生成：${toPosix(path.relative(siteRoot, out))}\n`);
+  if (!flag("no-open")) openPath(out);
+}
+
+switch (command) {
+  case "scan":
+    commandScan();
+    break;
+  case "check":
+    commandCheck();
+    break;
+  case "apply":
+    commandApply();
+    break;
+  case "prompt":
+    process.stdout.write(promptText({ studio: flag("studio") }));
+    break;
+  case "schema":
+    process.stdout.write(`${JSON.stringify(catalogSchema(), null, 2)}\n`);
+    break;
+  case "catalog":
+    commandCatalog();
+    break;
+  default:
+    fail(`用法：garden ui <scan|check|apply|prompt|schema|catalog>
+
+  garden ui scan <稿件.md>                 列出块、状态、行号和哈希（JSON）
+  garden ui check <稿件.md>... | --staged | --all [--standalone]
+                                           检查 ui / intent 块，失败时给出修复提示词
+  garden ui apply <稿件.md> --id <id> [--base <哈希>] [--file 新内容.md]
+                                           只替换一块，围栏外逐字节不变
+  garden ui prompt [--studio]              打印写作规则、组件参考和配方
+  garden ui schema                         打印组件目录 JSON
+  garden ui catalog [--out 文件] [--no-open] 生成离线组件清单并打开`);
+}

package/tsconfig.json

@@ -30,5 +30,5 @@
     ".next/dev/types/**/*.ts",
     "**/*.mts"
   ],
-  "exclude": ["node_modules"]
+  "exclude": ["node_modules", "editors"]
 }

package/ui/core/apply.mjs

@@ -0,0 +1,81 @@
+import { parse as parseYaml } from "yaml";
+import { fenceHash, findBlocks, idOf, intentHash, intentOf, normalizeNewlines, scanFences, setCompiled, splitUiBody } from "./fence.mjs";
+import { checkUiBlock } from "./validate.mjs";
+
+export class ApplyError extends Error {
+  constructor(code, message, diagnostics = []) {
+    super(message);
+    this.code = code;
+    this.diagnostics = diagnostics;
+  }
+}
+
+function locate(markdown, target) {
+  const blocks = findBlocks(markdown);
+  let matches = [];
+  if (target.id) matches = blocks.filter((block) => idOf(block) === target.id);
+  else if (target.at) matches = blocks.filter((block) => block.startLine === Number(target.at));
+  else if (target.intentHash) {
+    matches = blocks.filter((block) => {
+      const intent = intentOf(block);
+      return intent !== null && intentHash(intent) === target.intentHash;
+    });
+  } else {
+    throw new ApplyError("apply-target", "要用 --id、--at 或 --intent-hash 指定一块");
+  }
+  if (!matches.length) throw new ApplyError("apply-not-found", "找不到要替换的块");
+  if (matches.length > 1) throw new ApplyError("apply-ambiguous", "匹配到多块，请改用更精确的定位");
+  return matches[0];
+}
+
+/** Classifies replacement text as one `ui` fence, one `widget` fence, or plain Markdown. */
+export function classifyReplacement(text) {
+  const trimmed = normalizeNewlines(text).trim();
+  const fences = scanFences(trimmed);
+  const whole = fences.length === 1 && fences[0].start === 0 && fences[0].end === trimmed.length && fences[0].closed;
+  if (whole && fences[0].lang === "ui") return { kind: "ui", text: trimmed, fence: fences[0] };
+  if (whole && fences[0].lang === "widget") return { kind: "widget", text: trimmed, fence: fences[0] };
+  if (fences.some((fence) => fence.lang === "ui" || fence.lang === "intent")) {
+    throw new ApplyError("apply-content", "写回正文时，内容里不能再有 ui 或 intent 围栏");
+  }
+  return { kind: "markdown", text: trimmed };
+}
+
+/**
+ * Replaces exactly one block. Everything outside the target fence stays
+ * byte-identical; the result is verified before it is returned.
+ */
+export function applyBlock(markdown, target, replacementText, options = {}) {
+  const { base = null, markdownPath = null, readData = null } = options;
+  const block = locate(markdown, target);
+  if (base && fenceHash(block.raw) !== base) {
+    throw new ApplyError("apply-base", "本地这一块已经改过，和打开时的版本不一致，没有覆盖");
+  }
+  const replacement = classifyReplacement(replacementText);
+  let text = replacement.text;
+  if (replacement.kind === "ui") {
+    const check = checkUiBlock(replacement.fence.body, { lineOffset: block.startLine, markdownPath, readData });
+    if (!check.ok) throw new ApplyError("apply-invalid", "新的 ui 块没有通过检查", check.diagnostics.filter((item) => item.severity === "error"));
+    const { header } = splitUiBody(replacement.fence.body);
+    if (typeof header?.intent === "string") text = setCompiled(text, intentHash(header.intent));
+  } else if (replacement.kind === "widget") {
+    let data = null;
+    try {
+      data = parseYaml(replacement.fence.body);
+    } catch {
+      data = null;
+    }
+    if (!data || typeof data.src !== "string" || !data.src.trim() || typeof data.caption !== "string" || !data.caption.trim()) {
+      throw new ApplyError("apply-invalid", "widget 围栏需要 src 和 caption");
+    }
+  }
+  const newline = markdown.includes("\r\n") ? "\r\n" : "\n";
+  if (newline === "\r\n") text = text.replace(/\n/gu, "\r\n");
+  const before = markdown.slice(0, block.start);
+  const after = markdown.slice(block.end);
+  const next = `${before}${text}${after}`;
+  if (!next.startsWith(before) || !next.endsWith(after) || next.length !== before.length + text.length + after.length) {
+    throw new ApplyError("apply-verify", "替换后围栏之外的内容发生了变化，已放弃");
+  }
+  return { markdown: next, kind: replacement.kind, block };
+}