@vobs/cli 1.8.4 → 1.8.6

package/dist/index.js

@@ -1171,6 +1171,216 @@ async function checkCommand(options = {}) {
 }
 __name(checkCommand, "checkCommand");
 
+// packages/cli/src/commands/agent-doc.ts
+import { existsSync as existsSync4, readFileSync as readFileSync4, writeFileSync as writeFileSync3 } from "fs";
+import { resolve as resolve6 } from "path";
+
+// packages/cli/src/templates/agent-contract.ts
+var AGENT_CONTRACT = `# vobs \u6846\u67B6\u5951\u7EA6\uFF08\u5199\u4EE3\u7801\u524D\u5FC5\u8BFB\uFF09
+
+vobs \u662F**\u7F16\u8BD1\u578B / \u7EC6\u7C92\u5EA6 / \u54CD\u5E94\u5F0F**\u6846\u67B6\uFF0C\u4E0E React \u7684\u5FC3\u667A\u6A21\u578B\u6709\u51E0\u5904**\u6839\u672C\u4E0D\u540C**\u3002
+\u4E0B\u9762\u7684\u6BCF\u4E00\u6761\u90FD\u6765\u81EA\u771F\u5B9E\u4E8B\u6545\uFF0C**\u8FDD\u53CD\u65F6\u901A\u5E38\u7F16\u8BD1\u901A\u8FC7\u3001\u8FD0\u884C\u671F\u624D\u9519**\u3002
+
+> \u672C\u6587\u6863\u7531 \`vobs agent-doc\` \u4ECE\u6846\u67B6\u7248\u672C\u751F\u6210 \u2014\u2014 \u4E0D\u8981\u624B\u6539\u751F\u6210\u7684\u5757\u3002
+> \u6BCF\u6761\u540E\u9762\u62EC\u53F7\u91CC\u662F**\u8FDD\u53CD\u65F6\u6846\u67B6\u4F1A\u62A5\u7684\u8BCA\u65AD\u7801**\u3002
+
+## \u4E00\u3001\u7EC4\u4EF6\u4F53\u53EA\u6267\u884C\u4E00\u6B21\uFF08run-once\uFF09
+
+**\u7EC4\u4EF6\u51FD\u6570\u4F53\u53EA\u5728\u521B\u5EFA\u65F6\u8DD1\u4E00\u6B21**\uFF0C\u4E4B\u540E\u53EA\u6709 JSX \u91CC\u8BA2\u9605\u7684\u4F4D\u7F6E\u66F4\u65B0\u3002
+
+- \u274C \`const filtered = list.value.filter(...)\` \u2014\u2014 \u4E00\u6B21\u5FEB\u7167\uFF0C\u4E4B\u540E\u6C38\u4E0D\u66F4\u65B0
+- \u2705 \u6D3E\u751F\u653E\u8FDB JSX\uFF1A\`<div>{list.value.filter(...).map(render)}</div>\`
+- \u274C \u7EC4\u4EF6\u4F53\u91CC\u53D6\u5FEB\u7167\u7ED9\u56DE\u8C03\u7528\uFF1A\`const v = name.value; onClick={() => save(v)}\`
+- \u2705 \u56DE\u8C03\u5185\u91CD\u8BFB\uFF1A\`onClick={() => save(name.value)}\`
+- \u52A8\u6001 props \u7528 getter \u5F62\u6001\uFF0C\u4E0D\u8981\u4F20\u6C42\u503C\u540E\u7684\u503C
+
+## \u4E8C\u3001\u6761\u4EF6\u6E32\u67D3\uFF1A**\u4E0D\u8981\u5728\u7EC4\u4EF6\u4F53\u91CC \`return\` \u5206\u652F**\uFF08\`VOBS_C107\` / \`VOBS_C104\`\uFF09
+
+\u7EC4\u4EF6\u4F53\u91CC\u8BFB\u4FE1\u53F7\u7684 \`return\` \u5728\u6302\u8F7D\u65F6\u56FA\u5316\uFF0C**\u4E09\u79CD\u5199\u6CD5\u574F\u5F97\u4E00\u6A21\u4E00\u6837**\uFF1A
+
+\`\`\`tsx
+return cond.value ? <A/> : <B/>        // \u274C \u51BB\u7ED3
+if (cond.value) return <A/>            // \u274C \u51BB\u7ED3
+return cond.value ? <A/> : null        // \u274C \u51BB\u7ED3
+\`\`\`
+
+\u9876\u5C42 \`return\` \u5904**\u6CA1\u6709 parent/anchor**\uFF0C\u6240\u4EE5\u4E24\u652F\u90FD\u662F JSX \u4E5F\u4E00\u6837\u4E0D\u4F1A\u91CD\u5206\u652F\u3002
+
+| \u573A\u666F | \u7528\u4EC0\u4E48 |
+|---|---|
+| **\u8DEF\u7531\u5206\u652F** | **\`<RouterView/>\`**\uFF08\u58F0\u660E\u5F0F\uFF0C\u5185\u90E8 \`insertDynamic\` + \`resetKey\`\uFF09 |
+| \u4FDD\u7559\u6302\u8F7D\u3001\u53EA\u5207\u663E\u9690 | **\`<Show when={cond}>\`**\uFF08\u5207 \`hidden\` + \`inert\`\uFF0C\u7126\u70B9/\u6EDA\u52A8/\u5185\u90E8\u72B6\u6001\u4E0D\u4E22\uFF09 |
+| \u53EA\u5207\u7C7B\u540D | \`class="base" classList={{ 'is-on': cond.value }}\` |
+| \u666E\u901A\u6761\u4EF6\u6E32\u67D3 | \u653E\u8FDB **JSX \u5B50\u8282\u70B9\u4F4D\u7F6E**\uFF1A\`<div>{cond.value ? <A/> : <B/>}</div>\` |
+
+## \u4E09\u3001effect \u91CC\u4E0D\u8981\u5199\u81EA\u5DF1\u8BFB\u8FC7\u7684\u4FE1\u53F7\uFF08\`VOBS_C210\` / \`VOBS_C211\`\uFF09
+
+**\u4F9D\u8D56\u662F\u81EA\u52A8\u6536\u96C6\u7684**\uFF1Aeffect \u8FD0\u884C\u671F\u95F4\u8BFB\u5230\u7684**\u4EFB\u4F55**\u4FE1\u53F7\u90FD\u4F1A\u53D8\u6210\u4F9D\u8D56\u3002
+
+- \u274C \`effect(() => { count.value++ })\` \u2014\u2014 \u8BFB+\u5199\u540C\u4E00\u4E2A\u4FE1\u53F7 = \u81EA\u8BA2\u9605\u5FAA\u73AF
+- \u274C \`effect(() => { if (session.value) void sync() })\` \u2014\u2014 **\u300C\u53EA\u8C03\u4E86\u4E2A\u51FD\u6570\u300D\u4E0D\u7B49\u4E8E\u6CA1\u4F9D\u8D56**\uFF1A
+  \u88AB\u8C03\u51FD\u6570\u5728**\u9996\u4E2A \`await\` \u4E4B\u524D**\u7684\u4EE3\u7801\u662F**\u540C\u6B65\u6267\u884C**\u7684\uFF0C\u5B83\u8BFB\u7684\u4FE1\u53F7\u7B97\u5728 effect \u5934\u4E0A
+- \u2705 \u53EA\u60F3\u58F0\u660E\u4F9D\u8D56\uFF1A**\`effect(on(deps, () => { \u2026 }))\`** \u2014\u2014 \u56DE\u8C03\u5728 untrack \u4F5C\u7528\u57DF\u91CC\u8DD1\uFF0C
+  \u5B83\u8C03\u7528\u7684\u51FD\u6570\u78B0\u4EC0\u4E48\u4FE1\u53F7\u90FD\u4E0D\u4F1A\u53CD\u5411\u8BA2\u9605
+- \u2705 \u6D3E\u751F\u503C\u7528 \`memo\`\uFF0C\u4E0D\u8981"\u8BFB A \u5199 B"
+- \u515C\u5E95\u624D\u662F \`untrack(() => { X.value = next })\`
+
+**\u522B\u5728 effect \u91CC\u8C03 async \u51FD\u6570**\uFF08\`VOBS_C106\`\uFF09\uFF1A\`effect\` \u4E0D\u7B49\u5B83\uFF0C
+\u4E14\u9996\u4E2A \`await\` \u4E4B\u524D\u7684\u90E8\u5206\u662F\u540C\u6B65\u7684\u3002\u5F02\u6B65\u53D6\u6570\u7528 **\`@vobs/resource\`**\u3002
+
+## \u56DB\u3001\u5BA2\u6237\u7AEF\u526F\u4F5C\u7528\u4E0E SSR
+
+- \u5B9A\u65F6\u5668 / \u76D1\u542C / \`matchMedia\` / \`localStorage\` \u2192 **\`onMount\` \u542F\u52A8\u3001\`onDestroy\` \u6E05\u7406**
+  \uFF08**\u4E0D\u8981\u624B\u5199 \`typeof window\` \u5B88\u536B**\uFF09
+- **\u6E32\u67D3\u8F93\u51FA\u672C\u8EAB**\u4F9D\u8D56\u6D4F\u89C8\u5668\uFF08\u7A97\u53E3\u5C3A\u5BF8 / \`localStorage\` \u56DE\u586B / \`Date.now\` / \u968F\u673A\u503C\uFF09
+  \u2192 **\`<ClientOnly fallback={\u2026}>\`**\uFF08\u9996\u8F6E\u4E24\u4FA7\u90FD\u6E32\u67D3 fallback\uFF0C\u6C34\u5408\u5BF9\u5F97\u4E0A\uFF09
+- \u6A21\u5757\u9876\u5C42**\u7981\u6B62** JSX\uFF08\`VOBS_C105\`\uFF09\uFF1Aimport \u6C42\u503C\u65E9\u4E8E\u6E32\u67D3\u5668\u5B89\u88C5
+
+## \u4E94\u3001\u5217\u8868\u4E0E\u6570\u636E
+
+- **\u6570\u7EC4\u66F4\u65B0\u5FC5\u987B\u6362\u5F15\u7528**\uFF1A\`list.value = [...list.value, item]\`\uFF1B
+  \u539F\u5730 \`push\` / \u6539\u5B57\u6BB5**\u4E0D\u89E6\u53D1\u66F4\u65B0**
+- JSX **\u5B50\u8282\u70B9\u4F4D\u7F6E**\u53EA\u653E\u56DB\u79CD\u5F62\u6001\uFF1A\u7EC4\u4EF6\u6807\u7B7E / \u5143\u7D20 / \u4E24\u5206\u652F\u4E09\u5143 / \`.map()\`
+- \u6570\u636E\u7ED3\u6784\u91CC**\u53EA\u5B58\u7EAF\u63CF\u8FF0**\uFF08\u5B57\u7B26\u4E32/\u6837\u5F0F/\u7ED3\u6784\u5B57\u6BB5\uFF09\uFF0C**\u8282\u70B9\u5BF9\u8C61\u522B\u8FDB\u6570\u636E\u5E38\u91CF**
+  \uFF08SSG \u5E8F\u5217\u5316\u4F1A\u70B8\uFF0C\u4EA7\u7269\u51FA\u73B0 \`[object Xxx]\` \u65F6\u6846\u67B6\u4F1A\u76F4\u63A5\u62A5\u9519\uFF09
+
+## \u516D\u3001\u8F93\u5165
+
+- **\u6570\u5B57\u8F93\u5165\u8D70 \`parseNumber\`**\uFF08\`<Field type="number">\` \u5DF2\u5185\u7F6E\uFF09\uFF1A
+  \u7A7A\u4E32 / \u975E\u6CD5 / \u8D85\u754C**\u4E0D\u63D0\u4EA4**\uFF0C\u4FDD\u6301\u539F\u503C
+  \u2014\u2014 \`Number('') === 0\` \u4F1A\u628A\u8F93\u5165\u6E05\u6210 0 \u5E76\u6CBF\u8054\u52A8\u94FE\u8DEF\u6E05\u96F6\u5144\u5F1F\u7EF4\u5EA6
+- \`<select>\` \u7684 value \u76F4\u63A5\u7ED1\uFF0C**\u4E0D\u8981\u5199 ref \u515C\u5E95**\uFF081.5.1+ \u5DF2\u4FEE\u65F6\u5E8F\uFF09
+
+## \u4E03\u3001\u56FE\u6807\u4E0E SVG
+
+- **SVG \u76F4\u63A5\u5199 JSX**\uFF08\`<svg><path/></svg>\`\uFF0C1.7.4+ \u6309 namespace \u521B\u5EFA\u4E0E\u6C34\u5408\uFF09
+- \u56FE\u6807\u8981**\u767B\u8BB0\u8FDB\u767D\u540D\u5355**\uFF1B\u67E5\u8868 miss \u65F6 \`@vobs/icon-core\` \u4F1A\u8B66\u544A\u70B9\u540D\uFF08\u4F46\u4ECD\u5E94\u767B\u8BB0\uFF09
+
+## \u516B\u3001\u63D0\u4EA4\u524D\u81EA\u6D4B
+
+\`\`\`bash
+pnpm run check:source            # = vobs check\uFF0C\u5168\u4ED3\u4E00\u6B21\u5217\u51FA\u5168\u90E8\u8BCA\u65AD
+pnpm run check:runtime           # \u771F\u5B9E\u6D4F\u89C8\u5668\u9010\u8DEF\u7531\u8DD1\u62A4\u680F\uFF08\u9700 Chrome\uFF09
+pnpm run check:runtime:interact  # \u518D\u70B9\u6240\u6709\u6309\u94AE\u3001\u89E6\u53D1\u6240\u6709\u8F93\u5165
+\`\`\`
+
+\`vite build\` **\u4F1A**\u6253\u5370\u7F16\u8BD1\u671F\u8B66\u544A\uFF08\`C104\`/\`C105\`/\`C106\`/\`C107\`\uFF09\uFF0C\u4F46\u53EA\u8986\u76D6\u5B83\u7F16\u8BD1\u5230\u7684\u6587\u4EF6\uFF1B
+\`check:source\` \u624D\u662F\u5168\u4ED3\u5165\u53E3\u3002
+
+---
+
+## \u4E00\u53E5\u8BDD\u901F\u8BB0
+
+| \u4E3B\u9898 | \u4E00\u53E5\u8BDD |
+|---|---|
+| \u7EC4\u4EF6\u4F53 | \u53EA\u8DD1\u4E00\u6B21\uFF0C\u6D3E\u751F\u8FDB JSX |
+| \u56DE\u8C03 | \u89E6\u53D1\u65F6\u91CD\u8BFB \`.value\` |
+| \u6761\u4EF6\u6E32\u67D3 | \u8DEF\u7531\u7528 \`RouterView\`\uFF0C\u663E\u9690\u7528 \`Show\`\uFF0C\u522B\u5728\u7EC4\u4EF6\u4F53 return \u5206\u652F |
+| effect | \u522B\u5199\u81EA\u5DF1\u8BFB\u7684\u4FE1\u53F7\uFF0C\u7528 \`on(deps, fn)\` |
+| async | \u522B\u585E\u8FDB effect\uFF0C\u7528 \`@vobs/resource\` |
+| \u5BA2\u6237\u7AEF | \`onMount\`/\`onDestroy\`/\`ClientOnly\`\uFF0C\u522B\u624B\u5199 \`typeof window\` |
+| \u5217\u8868 | \u6362\u5F15\u7528 |
+| \u6570\u5B57 | \`parseNumber\` |
+| SVG | \u76F4\u63A5\u5199 |
+| \u81EA\u6D4B | \`check:source\` + \`check:runtime\` |
+`;
+
+// packages/cli/src/commands/agent-doc.ts
+var BEGIN = "<!-- vobs:begin \u7531 `vobs agent-doc --write` \u751F\u6210\uFF0C\u8BF7\u52FF\u624B\u6539 -->";
+var END = "<!-- vobs:end -->";
+function readContract() {
+  return AGENT_CONTRACT.trim();
+}
+__name(readContract, "readContract");
+function buildAgentsDoc(contract) {
+  return [
+    BEGIN,
+    "",
+    contract,
+    "",
+    END,
+    "",
+    "<!-- \u4EE5\u4E0B\u662F\u672C\u9879\u76EE\u7684\u81EA\u6709\u7EA6\u5B9A\uFF0C`vobs agent-doc --write` \u4E0D\u4F1A\u8986\u76D6\u3002 -->",
+    "",
+    "## \u672C\u9879\u76EE\u7EA6\u5B9A",
+    "",
+    "\uFF08\u5728\u8FD9\u91CC\u5199\u4F60\u81EA\u5DF1\u7684\u76EE\u5F55\u7ED3\u6784\u3001\u547D\u540D\u3001\u4E1A\u52A1\u6D41\u7A0B\u7B49\u89C4\u5219\u3002\uFF09",
+    ""
+  ].join("\n");
+}
+__name(buildAgentsDoc, "buildAgentsDoc");
+function extractBlock(text5) {
+  const start2 = text5.indexOf(BEGIN);
+  const end = text5.indexOf(END);
+  if (start2 < 0 || end < 0 || end < start2) return null;
+  return text5.slice(start2, end + END.length);
+}
+__name(extractBlock, "extractBlock");
+function mergeAgentsDoc(existing, generated) {
+  if (existing === null) return generated;
+  const block = extractBlock(generated);
+  if (block === null) return generated;
+  if (extractBlock(existing) === null) return `${existing.trimEnd()}
+
+${block}
+`;
+  return existing.replace(extractBlock(existing), block);
+}
+__name(mergeAgentsDoc, "mergeAgentsDoc");
+async function agentDocCommand(options = {}) {
+  const root = resolve6(options.dir ?? process.cwd());
+  const contract = readContract();
+  if (options.body === true) {
+    process.stdout.write(`${contract}
+`);
+    return;
+  }
+  const generated = buildAgentsDoc(contract);
+  const agentsPath = resolve6(root, "AGENTS.md");
+  const claudePath = resolve6(root, "CLAUDE.md");
+  const claudeDoc = "@AGENTS.md\n";
+  if (options.check === true) {
+    const problems = [];
+    if (!existsSync4(agentsPath)) {
+      problems.push("AGENTS.md \u4E0D\u5B58\u5728 \u2014\u2014 \u8DD1 `vobs agent-doc --write` \u751F\u6210");
+    } else {
+      const existing = readFileSync4(agentsPath, "utf8");
+      const block = extractBlock(existing);
+      if (block === null) {
+        problems.push("AGENTS.md \u91CC\u627E\u4E0D\u5230 vobs \u6807\u8BB0\u5757 \u2014\u2014 \u8DD1 `vobs agent-doc --write` \u8865\u4E0A");
+      } else if (block !== extractBlock(generated)) {
+        problems.push("AGENTS.md \u7684 vobs \u5951\u7EA6\u5757\u4E0E\u5F53\u524D\u6846\u67B6\u7248\u672C\u4E0D\u4E00\u81F4 \u2014\u2014 \u8DD1 `vobs agent-doc --write` \u540C\u6B65");
+      }
+    }
+    if (!existsSync4(claudePath)) {
+      problems.push("CLAUDE.md \u4E0D\u5B58\u5728 \u2014\u2014 \u8DD1 `vobs agent-doc --write` \u751F\u6210\uFF08\u5185\u5BB9\u53EA\u9700\u4E00\u884C `@AGENTS.md`\uFF09");
+    } else if (!readFileSync4(claudePath, "utf8").includes("@AGENTS.md")) {
+      problems.push("CLAUDE.md \u6CA1\u6709\u6307\u5411 @AGENTS.md");
+    }
+    if (problems.length > 0) {
+      console.error("[agent-doc] \u5951\u7EA6\u4E0E\u6846\u67B6\u7248\u672C\u4E0D\u540C\u6B65\uFF1A");
+      for (const problem of problems) console.error(`  - ${problem}`);
+      process.exitCode = 1;
+      return;
+    }
+    console.log("[agent-doc] \u5951\u7EA6\u4E0E\u5F53\u524D\u6846\u67B6\u7248\u672C\u4E00\u81F4 \u2713");
+    return;
+  }
+  if (options.write !== true) {
+    process.stdout.write(generated);
+    return;
+  }
+  const existingAgents = existsSync4(agentsPath) ? readFileSync4(agentsPath, "utf8") : null;
+  writeFileSync3(agentsPath, mergeAgentsDoc(existingAgents, generated), "utf8");
+  writeFileSync3(claudePath, claudeDoc, "utf8");
+  console.log(`[agent-doc] \u5DF2\u5199\u5165 ${agentsPath}`);
+  console.log(`[agent-doc] \u5DF2\u5199\u5165 ${claudePath}\uFF08\u5185\u5BB9\u4E3A @AGENTS.md\uFF09`);
+  if (existingAgents !== null && extractBlock(existingAgents) === null) {
+    console.log("[agent-doc] \u4F60\u539F\u6709\u7684 AGENTS.md \u5185\u5BB9\u5DF2\u4FDD\u7559\uFF0Cvobs \u5951\u7EA6\u5757\u8FFD\u52A0\u5728\u540E\u3002");
+  }
+}
+__name(agentDocCommand, "agentDocCommand");
+
 // packages/cli/src/banner.ts
 var BANNER_LINE1 = "\u{1D5E9}\u{1D5E2}\u{1D5D5}\u{1D5E6} \u{1D5D6}\u{1D5DF}\u{1D5DC}";
 var BANNER_TAGLINE = "Signals First \xB7 Zero Re-renders \xB7 Ultra Lightweight";
@@ -1255,6 +1465,14 @@ function createCLI() {
       includeTests: options.includeTests === true
     });
   });
+  cli.command("agent-doc", "\u751F\u6210/\u6821\u9A8C\u7ED9 LLM \u8BFB\u7684\u6846\u67B6\u5951\u7EA6\uFF08AGENTS.md + CLAUDE.md\uFF09").option("--dir <dir>", "\u76EE\u6807\u76EE\u5F55", { default: process.cwd() }).option("--write", "\u5199\u5165\u6587\u4EF6\uFF08\u9ED8\u8BA4\u6253\u5230 stdout\uFF09").option("--check", "\u6821\u9A8C\u9879\u76EE\u91CC\u90A3\u4EFD\u662F\u5426\u4E0E\u5F53\u524D\u6846\u67B6\u7248\u672C\u4E00\u81F4\uFF08\u53EF\u8FDB CI\uFF09").option("--body", "\u53EA\u8F93\u51FA\u5951\u7EA6\u6B63\u6587\uFF08\u4E0D\u542B\u6807\u8BB0\u5757\u5916\u8BF4\u660E\uFF09").action(async (options) => {
+    await agentDocCommand({
+      dir: options.dir,
+      write: options.write === true,
+      check: options.check === true,
+      body: options.body === true
+    });
+  });
   cli.command("dsh [action] [target]", "DSH \u63D2\u4EF6\u5DE5\u5177\u94FE\uFF08init / dev / build / check / install\uFF09").option("--dir <dir>", "init\uFF1A\u76EE\u6807\u76EE\u5F55").option("--pm <pm>", "init\uFF1A\u5305\u7BA1\u7406\u5668\uFF08pnpm/npm\uFF09").option("--port <port>", "dev\uFF1A\u9884\u89C8\u7AEF\u53E3", { default: 5199 }).option("--profile <name>", "install\uFF1ADSH profile \u540D", { default: "desktop" }).option("--spec <spec>", "install\uFF1A\u5B8C\u6574\u5B89\u88C5 spec").option("--repo <owner/name>", "install\uFF1AGitHub owner/name").option("--tag <ref>", "install\uFF1AGit tag / \u5206\u652F / commit").option("--subpath <path>", "install\uFF1A\u4ED3\u5E93\u5185\u5B50\u76EE\u5F55").option("--from <path>", "install\uFF1A\u4ECE\u672C\u5730\u76EE\u5F55\u5B89\u88C5").option("--dry", "install\uFF1A\u53EA\u6253\u5370\u547D\u4EE4\uFF0C\u4E0D\u6267\u884C").action(async (action, target, options) => {
     await dshCommand(action, target, {
       dir: options.dir,
@@ -1290,6 +1508,7 @@ var KNOWN_SUBCOMMANDS = [
   "add",
   "check",
   "dsh",
+  "agent-doc",
   "logo"
 ];