create-bubbles 0.1.26 → 0.1.28

package/template-pnpm-vp-monorepo/apps/playground/vite.config.ts

@@ -0,0 +1,29 @@
+import { fileURLToPath, URL } from "node:url";
+
+import vue from "@vitejs/plugin-vue";
+import { defineConfig } from "vite-plus";
+
+export default defineConfig({
+  plugins: [vue()],
+  resolve: {
+    alias: {
+      "@bubblesjs/utils": fileURLToPath(
+        new URL("../../packages/utils/src/index.ts", import.meta.url),
+      ),
+    },
+  },
+  server: {
+    port: 5173,
+    strictPort: true,
+  },
+  run: {
+    tasks: {
+      bundle: {
+        command: "vp build",
+        cache: {
+          env: ["NODE_ENV"],
+        },
+      },
+    },
+  },
+});

package/template-pnpm-vp-monorepo/commitlint.config.mjs

@@ -0,0 +1,3 @@
+export default {
+  extends: ["@commitlint/config-conventional"],
+};

package/template-pnpm-vp-monorepo/eslint.config.mjs

@@ -0,0 +1,22 @@
+import antfu from "@antfu/eslint-config";
+
+export default antfu(
+  {
+    formatters: false,
+    lessOpinionated: true,
+    stylistic: false,
+    typescript: true,
+    vue: true,
+    ignores: ["**/dist/**", "**/coverage/**", "**/.vitepress/cache/**", "**/.vitepress/dist/**"],
+  },
+  {
+    files: ["**/*.vue"],
+    rules: {
+      "vue/html-indent": "off",
+      "vue/html-self-closing": "off",
+      "vue/html-closing-bracket-newline": "off",
+      "vue/singleline-html-element-content-newline": "off",
+      "vue/multiline-html-element-content-newline": "off",
+    },
+  },
+);

package/template-pnpm-vp-monorepo/mise.toml

@@ -0,0 +1,3 @@
+[tools]
+node = "24.21.0"
+pnpm = "12.10.1"

package/template-pnpm-vp-monorepo/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "pnpm-vp-monorepo",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "build": "vp run -r build",
+    "changeset": "changeset",
+    "check": "vp run quality",
+    "ci": "pnpm check && pnpm build && pnpm verify:packages",
+    "dev": "vp run playground#dev",
+    "docs:build": "vp run docs#build",
+    "docs:dev": "vp run docs#dev",
+    "docs:preview": "vp run docs#preview",
+    "format": "vp fmt --write .",
+    "format:check": "vp fmt --check .",
+    "hooks:install": "vp config --hooks-dir .vite-hooks --no-agent",
+    "lint": "pnpm lint:ox && pnpm lint:vue",
+    "lint:ox": "vp lint .",
+    "lint:vue": "eslint \"apps/**/*.vue\" \"packages/**/*.vue\" --no-error-on-unmatched-pattern --max-warnings=0",
+    "preview": "vp run playground#preview",
+    "ready": "pnpm run ci",
+    "release": "pnpm ready && changeset publish",
+    "test": "vp run -r test",
+    "typecheck": "tsc -p tsconfig.json --noEmit && vp run -r typecheck",
+    "verify:packages": "vp run -r verify:package",
+    "version-packages": "changeset version && pnpm install --lockfile-only --no-frozen-lockfile"
+  },
+  "devDependencies": {
+    "@antfu/eslint-config": "catalog:",
+    "@changesets/cli": "catalog:",
+    "@commitlint/cli": "catalog:",
+    "@commitlint/config-conventional": "catalog:",
+    "@types/node": "catalog:",
+    "eslint": "catalog:",
+    "typescript": "catalog:",
+    "vite": "catalog:",
+    "vite-plus": "catalog:"
+  }
+}

package/template-pnpm-vp-monorepo/packages/utils/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) [year] [copyright holder]
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/template-pnpm-vp-monorepo/packages/utils/README.md

@@ -0,0 +1,26 @@
+# @bubblesjs/utils
+
+模板中的内部共享 TypeScript 工具包，设置了 `private: true`，不发布到 npm。包名 `@bubblesjs/utils` 保留为工作区内部标识。通过 Vite+ Pack 输出 ESM、CommonJS 和对应的类型声明；应用通过 `workspace:*` 依赖它。
+
+```ts
+import { clamp } from "@bubblesjs/utils";
+
+clamp(125, 0, 100); // 100
+clamp(-20, 0, 100); // 0
+clamp(42, 0, 100); // 42
+```
+
+`clamp(value, min, max)` 要求参数均为有限数值，且 `min <= max`，否则抛出 `RangeError`。原有 `fn()` 导出保留，返回 `Hello, tsdown!`。
+
+在仓库根目录运行：
+
+```bash
+pnpm --filter @bubblesjs/utils test
+pnpm --filter @bubblesjs/utils build
+pnpm --filter @bubblesjs/utils typecheck
+pnpm --filter @bubblesjs/utils verify:package
+```
+
+`verify:package` 以及根目录的 `pnpm verify:packages` 仅检查本地 ESM/CJS、类型声明和打包文件，不执行 npm 发布。
+
+复制为内部共享包时保留 `private: true`。若将来复制为公开包，例如 `@bubblesjs/math`，须显式移除 `private: true`，设置 `publishConfig.access` 为 `public` 并完善发布元信息。发布到 npm 的账户需拥有 `@bubblesjs` scope 或对应组织的包发布权限。维护 `tests/consumer` 中的双格式消费类型测试和 `scripts/verify-package.mjs` 中的运行验证；仅在更换 scope 时同步替换 `@bubblesjs` 的引用。

package/template-pnpm-vp-monorepo/packages/utils/_gitignore

@@ -0,0 +1,4 @@
+node_modules
+dist
+*.log
+.DS_Store

package/template-pnpm-vp-monorepo/packages/utils/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@bubblesjs/utils",
+  "version": "0.0.0",
+  "private": true,
+  "description": "Monorepo 模板中的共享 TypeScript 工具包示例。",
+  "license": "MIT",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "build": "vp run bundle",
+    "dev": "vp pack --watch",
+    "test": "vp test run",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "verify:package": "vp pack && tsc -p tests/consumer/tsconfig.json --noEmit && node scripts/verify-package.mjs"
+  },
+  "devDependencies": {
+    "@types/node": "catalog:",
+    "typescript": "catalog:",
+    "vite-plus": "catalog:"
+  }
+}

package/template-pnpm-vp-monorepo/packages/utils/scripts/verify-package.mjs

@@ -0,0 +1,127 @@
+import assert from "node:assert/strict";
+import { spawnSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { delimiter, dirname, extname, isAbsolute, join, relative, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const packageRoot = fileURLToPath(new URL("../", import.meta.url));
+const manifest = JSON.parse(readFileSync(join(packageRoot, "package.json"), "utf8"));
+const requiredFiles = new Set(["package.json"]);
+
+assert.ok(manifest.name, "Package must have a name");
+
+function verifyFile(target, field) {
+  assert.equal(typeof target, "string", `${field} must reference a file`);
+  const absolutePath = resolve(packageRoot, target);
+  const relativePath = relative(packageRoot, absolutePath);
+  assert.ok(
+    relativePath && !relativePath.startsWith("..") && !isAbsolute(relativePath),
+    `${field} must stay inside the package`,
+  );
+  assert.ok(existsSync(absolutePath), `${field} references a missing file: ${target}`);
+  requiredFiles.add(relativePath.replaceAll("\\", "/"));
+}
+
+for (const field of ["main", "module", "types"]) {
+  verifyFile(manifest[field], field);
+}
+
+function verifyExports(value, field = "exports") {
+  if (typeof value === "string") {
+    verifyFile(value, field);
+    return;
+  }
+  assert.ok(value && typeof value === "object", `${field} must define export targets`);
+  for (const [condition, target] of Object.entries(value)) {
+    verifyExports(target, `${field}.${condition}`);
+  }
+}
+
+verifyExports(manifest.exports);
+const entry = manifest.exports["."];
+assert.ok(entry?.import?.types?.endsWith(".d.ts"), "ESM exports must declare .d.ts types");
+assert.ok(entry?.require?.types?.endsWith(".d.cts"), "CommonJS exports must declare .d.cts types");
+assert.equal(manifest.type, "module", "ESM .js output requires type: module");
+assert.ok(entry?.import?.default?.endsWith(".js"), "ESM exports must reference .js output");
+assert.ok(entry?.require?.default?.endsWith(".cjs"), "CommonJS exports must reference .cjs output");
+
+function verifyRuntime(module, format) {
+  assert.equal(module.fn(), "Hello, tsdown!", `${format}: fn()`);
+  assert.equal(module.clamp(5, 0, 10), 5, `${format}: value inside bounds`);
+  assert.equal(module.clamp(-2, 0, 10), 0, `${format}: lower bound`);
+  assert.equal(module.clamp(12, 0, 10), 10, `${format}: upper bound`);
+  assert.equal(module.clamp(3, 2, 2), 2, `${format}: equal bounds`);
+  for (const args of [
+    [NaN, 0, 10],
+    [Infinity, 0, 10],
+    [1, -Infinity, 10],
+    [1, 0, Infinity],
+    [1, 10, 0],
+  ]) {
+    assert.throws(() => module.clamp(...args), RangeError, `${format}: invalid bounds or value`);
+  }
+}
+
+verifyRuntime(await import(manifest.name), "ESM");
+verifyRuntime(createRequire(import.meta.url)(manifest.name), "CommonJS");
+
+// Invoke npm's JavaScript CLI directly when npm is installed as a Windows .cmd
+// wrapper. Passing arguments to Node avoids shell quoting and interpolation.
+function npmCommand() {
+  const cliCandidates = [
+    process.env.npm_execpath,
+    join(dirname(process.execPath), "node_modules", "npm", "bin", "npm-cli.js"),
+  ];
+  for (const candidate of cliCandidates) {
+    if (candidate?.endsWith("npm-cli.js") && existsSync(candidate)) {
+      return { command: process.execPath, prefix: [candidate] };
+    }
+  }
+
+  const extensions = process.platform === "win32" ? [".exe", ".cmd", ".bat"] : [""];
+  const pathValue = process.env.PATH ?? process.env.Path ?? "";
+  for (const directory of pathValue.split(delimiter).filter(Boolean)) {
+    for (const extension of extensions) {
+      const candidate = join(directory.replace(/^"|"$/g, ""), `npm${extension}`);
+      if (!existsSync(candidate)) continue;
+      if ([".cmd", ".bat"].includes(extname(candidate).toLowerCase())) {
+        const cli = join(dirname(candidate), "node_modules", "npm", "bin", "npm-cli.js");
+        if (existsSync(cli)) return { command: process.execPath, prefix: [cli] };
+        continue;
+      }
+      return { command: candidate, prefix: [] };
+    }
+  }
+  throw new Error("Cannot locate npm's executable or npm-cli.js; install Node.js with npm first.");
+}
+
+const { command, prefix } = npmCommand();
+const result = spawnSync(command, [...prefix, "pack", "--dry-run", "--json", "--ignore-scripts"], {
+  cwd: packageRoot,
+  encoding: "utf8",
+  shell: false,
+  windowsHide: true,
+  timeout: 60_000,
+});
+if (result.error) throw result.error;
+assert.equal(result.status, 0, `npm pack failed:\n${result.stderr || result.stdout}`);
+const [packed] = JSON.parse(result.stdout);
+assert.ok(packed?.files?.length, "npm pack must report publishable files");
+const publishedFiles = new Set(packed.files.map(({ path }) => path.replaceAll("\\", "/")));
+for (const target of requiredFiles) {
+  assert.ok(publishedFiles.has(target), `Published package is missing ${target}`);
+}
+for (const target of publishedFiles) {
+  assert.ok(!/^(src|tests)\//.test(target), `Source or tests must not be published: ${target}`);
+}
+assert.ok(
+  [...publishedFiles].some((target) => target.endsWith(".d.ts")),
+  "Published package must include ESM declarations",
+);
+assert.ok(
+  [...publishedFiles].some((target) => target.endsWith(".d.cts")),
+  "Published package must include CommonJS declarations",
+);
+
+console.log(`Verified ${manifest.name}: ESM, CommonJS, declarations, and npm package contents.`);

package/template-pnpm-vp-monorepo/packages/utils/src/index.ts

@@ -0,0 +1,12 @@
+export function fn() {
+  return "Hello, tsdown!";
+}
+
+/** 将有限数值限制在闭区间 [min, max] 内。 */
+export function clamp(value: number, min: number, max: number): number {
+  if (![value, min, max].every(Number.isFinite) || min > max) {
+    throw new RangeError("clamp 需要有限数值，且 min 不能大于 max。");
+  }
+
+  return Math.min(max, Math.max(min, value));
+}

package/template-pnpm-vp-monorepo/packages/utils/tests/consumer/commonjs.cts

@@ -0,0 +1,20 @@
+import utils = require("@bubblesjs/utils");
+
+const message: string = utils.fn();
+const value: number = utils.clamp(5, 0, 10);
+void message;
+void value;
+
+// @ts-expect-error Values must be numbers.
+utils.clamp("5", 0, 10);
+// @ts-expect-error Lower bounds must be numbers.
+utils.clamp(5, "0", 10);
+// @ts-expect-error Upper bounds must be numbers.
+utils.clamp(5, 0, "10");
+// @ts-expect-error All three arguments are required.
+utils.clamp(5, 0);
+// @ts-expect-error fn does not accept arguments.
+utils.fn("extra");
+// @ts-expect-error clamp returns a number.
+const wrongResult: string = utils.clamp(5, 0, 10);
+void wrongResult;

package/template-pnpm-vp-monorepo/packages/utils/tests/consumer/esm.mts

@@ -0,0 +1,20 @@
+import { clamp, fn } from "@bubblesjs/utils";
+
+const message: string = fn();
+const value: number = clamp(5, 0, 10);
+void message;
+void value;
+
+// @ts-expect-error Values must be numbers.
+clamp("5", 0, 10);
+// @ts-expect-error Lower bounds must be numbers.
+clamp(5, "0", 10);
+// @ts-expect-error Upper bounds must be numbers.
+clamp(5, 0, "10");
+// @ts-expect-error All three arguments are required.
+clamp(5, 0);
+// @ts-expect-error fn does not accept arguments.
+fn("extra");
+// @ts-expect-error clamp returns a number.
+const wrongResult: string = clamp(5, 0, 10);
+void wrongResult;

package/template-pnpm-vp-monorepo/packages/utils/tests/consumer/tsconfig.json

@@ -0,0 +1,10 @@
+{
+  "extends": "../../../../tsconfig/node.json",
+  "compilerOptions": {
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "noEmit": true,
+    "paths": {}
+  },
+  "include": ["*.mts", "*.cts"]
+}

package/template-pnpm-vp-monorepo/packages/utils/tests/index.test.ts

@@ -0,0 +1,30 @@
+import { describe, expect, test } from "vite-plus/test";
+import { clamp, fn } from "../src/index.ts";
+
+test("fn", () => {
+  expect(fn()).toBe("Hello, tsdown!");
+});
+
+describe("clamp", () => {
+  test.each([
+    [5, 0, 10, 5],
+    [-5, 0, 10, 0],
+    [15, 0, 10, 10],
+    [0, 0, 10, 0],
+    [10, 0, 10, 10],
+    [8, 3, 3, 3],
+    [-2.5, -5, -1, -2.5],
+  ])("限制 %s 到 [%s, %s] 得到 %s", (value, min, max, expected) => {
+    expect(clamp(value, min, max)).toBe(expected);
+  });
+
+  test.each([
+    [5, 10, 0],
+    [NaN, 0, 10],
+    [Infinity, 0, 10],
+    [5, -Infinity, 10],
+    [5, 0, Infinity],
+  ])("拒绝非法输入 (%s, %s, %s)", (value, min, max) => {
+    expect(() => clamp(value, min, max)).toThrow(RangeError);
+  });
+});

package/template-pnpm-vp-monorepo/packages/utils/tsconfig.json

@@ -0,0 +1,4 @@
+{
+  "extends": "../../tsconfig/node.json",
+  "include": ["src/**/*.ts", "tests/**/*.test.ts", "vite.config.ts"]
+}

package/template-pnpm-vp-monorepo/packages/utils/vite.config.ts

@@ -0,0 +1,20 @@
+import { defineConfig } from "vite-plus";
+
+export default defineConfig({
+  pack: {
+    entry: ["src/index.ts"],
+    format: ["esm", "cjs"],
+    dts: { generator: "tsc" },
+    platform: "neutral",
+    sourcemap: true,
+  },
+  test: {
+    include: ["tests/**/*.test.ts"],
+    environment: "node",
+  },
+  run: {
+    tasks: {
+      bundle: { command: "vp pack", cache: { env: ["NODE_ENV"] } },
+    },
+  },
+});

package/template-pnpm-vp-monorepo/pnpm-workspace.yaml

@@ -0,0 +1,27 @@
+packages:
+  - apps/*
+  - packages/*
+
+catalogMode: prefer
+
+catalog:
+  "@antfu/eslint-config": ^9.5.1
+  "@changesets/cli": ^3.0.3
+  "@commitlint/cli": ^21.2.2
+  "@commitlint/config-conventional": ^21.2.2
+  "@types/node": ^26
+  "@vitejs/plugin-vue": ^6.0.9
+  eslint: ^10.9.0
+  typescript: ^6.0.3
+  vite: npm:@voidzero-dev/vite-plus-core@1.1.0
+  vite-plus: 1.1.0
+  vitepress: 2.0.0-alpha.20
+  vue: ^3.5.43
+  vue-tsc: ^3.3.12
+overrides:
+  vite@*: "catalog:"
+peerDependencyRules:
+  allowAny:
+    - vite
+  allowedVersions:
+    vite: "*"

package/template-pnpm-vp-monorepo/tsconfig/base.json

@@ -0,0 +1,22 @@
+{
+  "$schema": "https://json.schemastore.org/tsconfig",
+  "compilerOptions": {
+    "allowImportingTsExtensions": true,
+    "esModuleInterop": true,
+    "forceConsistentCasingInFileNames": true,
+    "isolatedModules": true,
+    "lib": ["ES2022"],
+    "module": "ESNext",
+    "moduleDetection": "force",
+    "moduleResolution": "Bundler",
+    "noEmit": true,
+    "noUncheckedIndexedAccess": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "resolveJsonModule": true,
+    "skipLibCheck": true,
+    "strict": true,
+    "target": "ES2022",
+    "verbatimModuleSyntax": true
+  }
+}

package/template-pnpm-vp-monorepo/tsconfig/node.json

@@ -0,0 +1,8 @@
+{
+  "extends": "./base.json",
+  "compilerOptions": {
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "types": ["node"]
+  }
+}

package/template-pnpm-vp-monorepo/tsconfig/vue.json

@@ -0,0 +1,7 @@
+{
+  "extends": "./base.json",
+  "compilerOptions": {
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "types": ["node", "vite/client"]
+  }
+}

package/template-pnpm-vp-monorepo/tsconfig.json

@@ -0,0 +1,4 @@
+{
+  "extends": "./tsconfig/node.json",
+  "include": ["vite.config.ts"]
+}

package/template-pnpm-vp-monorepo/vite.config.ts

@@ -0,0 +1,38 @@
+import { defineConfig } from "vite-plus";
+
+export default defineConfig({
+  staged: {
+    "*.{js,jsx,ts,tsx,mjs,cjs,mts,cts,json,jsonc,yaml,yml,md,css,scss}": "vp check --fix",
+    "*.vue": ["vp fmt --write", "eslint --fix --max-warnings=0"],
+  },
+  fmt: {
+    ignorePatterns: [
+      "**/dist/**",
+      "**/coverage/**",
+      "**/.vitepress/cache/**",
+      "**/.vitepress/dist/**",
+    ],
+  },
+  lint: {
+    ignorePatterns: [
+      "**/dist/**",
+      "**/coverage/**",
+      "**/.vitepress/cache/**",
+      "**/.vitepress/dist/**",
+      "**/*.vue",
+      "packages/utils/tests/consumer/**",
+    ],
+    jsPlugins: [{ name: "vite-plus", specifier: "vite-plus/oxlint-plugin" }],
+    rules: { "vite-plus/prefer-vite-plus-imports": "error" },
+    options: { typeAware: true, typeCheck: true },
+  },
+  run: {
+    cache: { scripts: false, tasks: true },
+    tasks: {
+      quality: {
+        command: ["pnpm format:check", "pnpm lint", "pnpm typecheck", "pnpm test"],
+        cache: false,
+      },
+    },
+  },
+});

package/template-vp-monorepo-react-nestjs/.agents/rules//345/205/261/344/272/253/344/273/243/347/240/201.md

@@ -1,4 +1,4 @@
 # 共享代码
 
-- 前后端的接口类型和返回类型统一放在 `packages/shared/types` 中。
-- 公用方法统一放在 `packages/shared/utils` 中。
+- 前后端的接口类型和返回类型统一放在 `packages/shared/src/types` 中。
+- 公用方法统一放在 `packages/shared/src/utils` 中。

package/template-vp-monorepo-react-nestjs/.agents/rules//351/234/200/346/261/202/344/270/216/350/256/276/350/256/241/346/226/207/346/241/243.md

@@ -0,0 +1,50 @@
+# 需求与设计文档规则
+
+## 正式来源
+
+- `.spaces/` 是本项目需求、设计、PRD、技术契约、UI 产物、测试报告和交付记录的唯一正式来源（Single Source of Truth）。完整规则见 [文档规范](../../.spaces/文档规范.md)，目录索引见 [项目空间文档索引](../../.spaces/README.md)。
+- 不再使用 `artifacts/` 保存或生成项目产物，也不在其中保留导航副本；历史内容应迁入所属 `.spaces/` 功能目录，生成脚本的输出路径也必须同步迁移。
+- 临时目录、聊天记录和代码注释不得保存上述文档的正文副本；聊天内容只能提炼为正式需求、设计、契约或待确认事项。
+- 开发、评审、联调和测试引用文档时，必须以 `.spaces/` 中的当前内容为准。
+
+## 分类与目录
+
+- 一级主题目录统一使用 `<序号>.<主题>/` 命名，例如 `.spaces/01.企业级项目级/`；序号用于稳定排序，主题名应能准确概括业务范围。
+- 新增、移动、合并或重命名一级主题与主要功能目录时，必须同步更新 `.spaces/README.md` 的目录索引、状态和相关决策链接。
+- 同一功能只有一个文档时可直接放在所属主题目录；同一功能存在两个或以上文档、截图或其他产物时，必须建立功能子目录集中管理，例如 `.spaces/01.企业级项目级/组织架构/`。
+- 功能目录内优先使用清晰、稳定的名称：`需求文档.md`、`设计方案.md`、`技术契约.md`、`测试报告.md`、`交付记录.md`。不要把文档阶段、日期或人员姓名写入文件名来制造副本。
+- UI 原型、截图、标注图和相关说明统一放在对应功能目录的 `ui/` 子目录；文件名应能说明页面或场景，必要时在同目录补充索引说明。
+- 跨主题内容应选择一个主归属目录，其余位置使用相对链接引用，不复制正文。
+
+## 新需求与需求变更
+
+- 收到新增、澄清或变更需求时，第一步必须定位并更新对应的 `.spaces/` 主题、功能目录和现行文档；没有目录时按本规则创建。需求、设计和契约同步完成前，不得先开始实现并把文档留到事后补写。
+- 新需求应写入对应功能的正式文档，并明确目标、范围、业务规则、关键流程、权限边界、数据约束、验收标准以及仍待确认的事项。
+- 需求变更必须直接修改原文档中的现行结论，同时在原文档的“变更记录”中记录日期、变更摘要、影响范围和决策原因；不得仅在文末追加互相矛盾的新结论。
+- 禁止创建 `v2`、`v3`、`final`、`最终版`、`最新版`、`新方案` 等并行正文副本。需要保留历史时依赖版本控制；只有确有独立业务语义的方案才可单独建文档，并写明与现行方案的关系和状态。
+- 澄清后被废弃的规则应从现行正文删除或明确标注为“已废弃”，不能继续以当前规则的口吻存在。
+
+## 需求、设计与契约同步
+
+- 开发前必须确认需求文档和技术契约已同步到当前决策；涉及接口、数据模型、权限、状态流转或跨端协作时，不得只改实现而遗漏文档。
+- 需求文档描述业务目标和验收标准；设计方案描述交互、领域设计和技术取舍；技术契约描述可供实现与联调使用的字段、接口、错误、权限及兼容约束。三者不得互相冲突。
+- 需求变化影响设计、契约、UI、测试或交付说明时，必须在同一任务中同步更新所有受影响文档，并检查引用它们的链接和状态说明。
+- 尚未确认或尚未实现的内容必须明确标注状态，不得写成已经生效的事实；旧契约与当前决策冲突时，应先修正或标记失效后再据此开发。
+
+## 链接与引用
+
+- 仓库内 Markdown 文档优先使用相对链接，链接目标必须指向 `.spaces/` 内的正式文件或仓库内真实存在的实现文件；移动或重命名文档后必须同步修复所有引用。
+- 文档应引用一个权威来源而非复制大段内容。确需摘要时，应标明摘要性质并附正式来源链接。
+- 外部链接应说明用途和来源；会失效、需要权限或仅供参考的链接，应在附近注明限制。
+- 提交前应检查旧路径、重复正文、失效相对链接、`artifacts/` 残留，以及仍会向 `artifacts/` 输出文件的脚本或命令。
+
+## 对话决策留存
+
+- Codex 对话、评审讨论和口头澄清中形成的有效需求，必须提炼进所属功能的现行文档；跨轮次的重要决策可在同目录维护 `决策记录.md`。
+- 不把原始聊天全文保存为项目文档。决策记录只保留日期、结论、状态、原因、影响范围和正式文档链接；后续推翻旧结论时，直接修改原文档并标明替代关系。
+
+## 敏感信息边界
+
+- 文档、截图和示例不得包含真实密码、访问令牌、密钥、Cookie、连接串、私有证书、验证码、个人身份信息或未脱敏的生产数据。
+- 账号、手机号、邮箱、企业名称、项目名称和业务数据应使用明显的虚构值或脱敏值；截图入库前必须检查界面、地址栏、终端输出和开发者工具中的敏感信息。
+- 需要说明配置项时只记录变量名、用途和获取方式，不记录真实值；敏感配置应由受控的密钥或环境变量机制管理。

package/template-vp-monorepo-react-nestjs/.codegraph/.gitignore

@@ -0,0 +1,5 @@
+# CodeGraph data files — local to each machine, not for committing.
+# Ignore everything in .codegraph/ except this file itself, so transient
+# files (the database, daemon.pid, sockets, logs) never show up in git.
+*
+!.gitignore