@icebreakers/monorepo-templates 0.1.15 → 1.0.0

package/README.md

@@ -6,3 +6,15 @@ This package ships:
 
 - `templates/`: app and package templates
 - `assets/`: root workspace config files and upgrade assets for `monorepo`
+- template metadata helpers such as `getTemplateChoices()`, `getTemplateChoice()`, and `getTemplateDefinition()`
+
+## Template Discovery
+
+```ts
+import { getTemplateChoices, getTemplateDefinition } from '@icebreakers/monorepo-templates'
+
+const libraries = getTemplateChoices({ category: 'library' })
+const vitepress = getTemplateDefinition('vitepress')
+```
+
+The returned metadata is a cloned snapshot, so callers can safely format it for CLI help, docs, or scaffold previews without mutating the package registry.

package/assets/.changeset/config.json

@@ -8,9 +8,14 @@
   ],
   "commit": false,
   "fixed": [],
-  "linked": [],
+  "linked": [
+    [
+      "@icebreakers/monorepo",
+      "repoctl"
+    ]
+  ],
   "access": "public",
   "baseBranch": "main",
   "updateInternalDependencies": "patch",
   "ignore": []
-}
+}

package/assets/.github/workflows/ci.yml

@@ -31,7 +31,7 @@ jobs:
         with:
           fetch-depth: 2
 
-      - uses: pnpm/action-setup@v4
+      - uses: pnpm/action-setup@v6
 
       - name: Setup Node.js environment
         uses: actions/setup-node@v6
@@ -53,10 +53,16 @@ jobs:
       - name: Build
         run: pnpm build
 
+      - name: Typecheck
+        run: pnpm typecheck
+
+      - name: TSD
+        run: pnpm tsd
+
       - name: Test
         run: pnpm test
 
       - name: Upload coverage reports to Codecov
-        uses: codecov/codecov-action@v5
+        uses: codecov/codecov-action@v6
         env:
           CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}

package/assets/.github/workflows/release.yml

@@ -24,7 +24,7 @@ jobs:
       - name: Checkout Repo
         uses: actions/checkout@v6
 
-      - uses: pnpm/action-setup@v4
+      - uses: pnpm/action-setup@v6
 
       - name: Setup Node.js environment
         uses: actions/setup-node@v6
@@ -52,6 +52,6 @@ jobs:
           NPM_CONFIG_PROVENANCE: true
 
       - name: Upload coverage reports to Codecov
-        uses: codecov/codecov-action@v5
+        uses: codecov/codecov-action@v6
         env:
           CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}

package/assets/.husky/commit-msg

@@ -1,4 +1,4 @@
 #!/usr/bin/env sh
 set -e
 
-pnpm exec commitlint --edit "$1"
+pnpm exec repo verify commit-msg "$1"

package/assets/.husky/pre-commit

@@ -1,4 +1,4 @@
 #!/usr/bin/env sh
 set -e
 
-pnpm exec nano-staged
+pnpm exec repo verify pre-commit

package/assets/.husky/pre-push

@@ -0,0 +1,5 @@
+#!/usr/bin/env sh
+set -e
+
+pnpm lint
+pnpm typecheck

package/assets/.vscode/settings.json

@@ -67,12 +67,7 @@
     "xml",
     "gql",
     "graphql",
-    "astro",
-    "css",
-    "less",
-    "scss",
-    "pcss",
-    "postcss"
+    "astro"
   ],
   "css.validate": false,
   "less.validate": false,

package/assets/AGENTS.md

@@ -2,7 +2,7 @@
 
 ## Project Structure & Module Organization
 
-This pnpm + Turbo monorepo keeps template sources under `templates/` (`cli`, `client`, `server`, `vitepress`, `tsup`, `tsdown`, `unbuild`, `vue-lib`) and reusable tooling under `packages/` (e.g., `monorepo`, `create-icebreaker`). Shared TypeScript and build settings live in root configs such as `turbo.json`, `tsconfig.json`, and `eslint.config.js`. Tests sit alongside their targets in `test/*.test.ts`, and each app owns its public assets (`public/`, `worker/`) to keep deployments self-contained.
+This pnpm + Turbo monorepo keeps template sources under `templates/` (`cli`, `client`, `server`, `vitepress`, `tsdown`, `vue-lib`) and reusable tooling under `packages/` (e.g., `monorepo`, `create-icebreaker`). Shared TypeScript and build settings live in root configs such as `turbo.json`, `tsconfig.json`, and `eslint.config.js`. Tests sit alongside their targets in `test/*.test.ts`, and each app owns its public assets (`public/`, `worker/`) to keep deployments self-contained.
 
 ## Build, Test, and Development Commands
 
@@ -15,11 +15,11 @@ This pnpm + Turbo monorepo keeps template sources under `templates/` (`cli`, `cl
 
 ## Coding Style & Naming Conventions
 
-Follow the root `.editorconfig`: two-space indentation, LF line endings, UTF-8. Prefer TypeScript (`.ts`/`.tsx`) and Vue SFCs; name files with kebab-case (`user-table.vue`) and exported symbols with PascalCase for components or camelCase for utilities. ESLint (`@icebreakers/eslint-config`) and Stylelint enforce formatting; run `pnpm lint` before committing, and rely on Husky + lint-staged to auto-fix staged files. Any style-related code changes (CSS, SCSS, Less, Vue style blocks, and similar files) must pass Stylelint checks before commit. All changed code must pass ESLint checks before commit.
+Follow the root `.editorconfig`: two-space indentation, LF line endings, UTF-8. Prefer TypeScript (`.ts`/`.tsx`) and Vue SFCs; name files with kebab-case (`user-table.vue`) and exported symbols with PascalCase for components or camelCase for utilities. ESLint (`@icebreakers/eslint-config`) and Stylelint enforce formatting; run `pnpm lint` before committing, and rely on Husky + lint-staged to auto-fix staged files. Any style-related code changes (CSS, SCSS, Less, Vue style blocks, and similar files) must pass Stylelint checks before commit. All changed JavaScript, TypeScript, and Vue code must pass ESLint checks before commit.
 
-`nano-staged.js` must include Stylelint checks for staged style files so style validation also runs during pre-commit.
+`lint-staged.config.js` must include Stylelint checks for staged style files so style validation also runs during pre-commit. It must also route staged TypeScript and Vue files into workspace `typecheck` scripts so Vue workspaces run `vue-tsc` and non-Vue TypeScript workspaces run `tsc`.
 
-When a single code file exceeds 300 lines, treat it as a refactor signal and split it into smaller modules.
+When a single code file exceeds 300 lines, treat it as a refactor signal and split it into smaller modules before commit whenever the change touches that area. Do not keep appending responsibilities to an already large file when a folder-based split would make the design clearer.
 
 When splitting code, do not create suffix-based sibling files such as `xxx.config.ts` or `xxx.filter.ts` just to move logic around. Create a dedicated folder (for example `xxx/`) and place the split modules inside it with clear responsibilities.
 
@@ -34,7 +34,7 @@ Before running tests, build the packages first and run tests against build artif
 
 TypeScript issues must be fixed before commit. Do not commit with unresolved TypeScript compile or type-check errors.
 
-TypeScript code must be validated with `tsc` (`pnpm typecheck` or the relevant workspace `typecheck` script) and must not contain type errors.
+TypeScript code must be validated with the relevant workspace `typecheck` script and must not contain type errors. Pure TypeScript workspaces are expected to validate with `tsc` (`pnpm typecheck` or `tsc -p tsconfig.json`). Vue workspaces are expected to validate with `vue-tsc` (typically `vue-tsc -b`).
 
 When building TypeScript libraries (type-focused APIs or public type definitions), add and maintain `tsd` type tests to verify exported type behavior.
 
@@ -45,7 +45,8 @@ Commits must conform to Conventional Commit syntax; recent history uses prefixes
 For AI-generated or AI-assisted changes, use this verification order before commit or PR:
 
 1. Run build first (`pnpm build` or the relevant workspace build command).
-2. Run lint checks, ensuring all changed code passes ESLint and style-related code passes Stylelint.
-3. Run TypeScript checks and fix all type errors before proceeding.
+2. Run lint checks, ensuring all changed JavaScript, TypeScript, and Vue code passes ESLint and all style-related code passes Stylelint.
+3. Run TypeScript checks and fix all type errors before proceeding. Vue workspaces must pass `vue-tsc`; TypeScript workspaces must pass `tsc`.
 4. For TypeScript libraries, run `tsd` type tests and fix all failures before proceeding.
 5. Run tests against built artifacts, including unit, integration, and E2E suites (when available in the affected workspace).
+6. Before commit, review whether the touched files need splitting or refactoring; do not commit avoidable large-file growth when a clearer module boundary is apparent.

package/assets/commitlint.config.ts

@@ -1,3 +1,3 @@
-import { icebreaker } from '@icebreakers/commitlint-config'
+import { defineCommitlintConfig } from 'repoctl/tooling'
 
-export default icebreaker()
+export default await defineCommitlintConfig()

package/assets/eslint.config.js

@@ -1,7 +1,3 @@
-import { icebreaker } from '@icebreakers/eslint-config'
+import { defineEslintConfig } from 'repoctl/tooling'
 
-export default icebreaker(
-  {
-    ignores: ['**/fixtures/**'],
-  },
-)
+export default await defineEslintConfig()

package/assets/lint-staged.config.js

@@ -0,0 +1,3 @@
+import { defineLintStagedConfig } from 'repoctl/tooling'
+
+export default await defineLintStagedConfig()

package/assets/package.json

@@ -3,7 +3,7 @@
   "type": "module",
   "version": "0.0.0",
   "private": true,
-  "packageManager": "pnpm@10.32.1",
+  "packageManager": "pnpm@10.33.2",
   "author": "ice breaker <hi@sonofmagic.top>",
   "repository": {
     "type": "git",
@@ -17,15 +17,17 @@
   },
   "scripts": {
     "build": "turbo run build",
+    "tooling:build": "turbo run build --filter=@icebreakers/monorepo --filter=repoctl",
     "dev": "turbo run dev --parallel",
     "test": "vitest run",
     "test:dev": "vitest",
     "lint": "turbo run lint",
+    "tsd": "turbo run tsd",
     "audit": "pnpm audit --audit-level=moderate",
     "audit:fix": "pnpm audit --fix",
     "typecheck": "turbo run typecheck",
     "format": "eslint . --fix",
-    "validate": "pnpm run typecheck && pnpm run lint && pnpm run test",
+    "validate": "pnpm run build && pnpm run lint && pnpm run typecheck && pnpm run tsd && pnpm run test",
     "release": "changeset",
     "publish-packages": "turbo run build lint test && changeset version && changeset publish",
     "------": "--------------",
@@ -34,49 +36,58 @@
     "commit": "commit",
     "commitlint": "commitlint --edit",
     "-------": "---------------",
+    "setup": "repo setup",
+    "new": "repo new",
+    "check": "repo check",
+    "doctor": "repo doctor",
+    "sync": "repo sync",
+    "clean:repo": "repo clean",
+    "mirror": "repo mirror",
+    "------simple": "--------------",
     "pr:alpha": "changeset pre enter alpha",
     "pr:beta": "changeset pre enter beta",
     "pr:rc": "changeset pre enter rc",
     "pr:exit": "changeset pre exit",
     "--------": "----------------",
-    "script:init": "monorepo init",
-    "script:sync": "monorepo sync",
-    "script:clean": "monorepo clean",
-    "script:mirror": "monorepo mirror"
+    "script:init": "repo init",
+    "script:sync": "repo sync",
+    "script:clean": "repo clean",
+    "script:mirror": "repo mirror"
   },
   "devDependencies": {
-    "@changesets/cli": "^2.30.0",
-    "@commitlint/cli": "^20.4.4",
-    "@icebreakers/changelog-github": "^0.2.1",
-    "@icebreakers/commitlint-config": "^1.2.11",
-    "@icebreakers/eslint-config": "^1.6.29",
+    "@changesets/cli": "^2.31.0",
+    "@commitlint/cli": "^20.5.3",
+    "@icebreakers/changelog-github": "^1.0.2",
+    "@icebreakers/commitlint-config": "^2.0.0",
+    "@icebreakers/eslint-config": "^4.0.10",
     "@icebreakers/monorepo": "workspace:*",
-    "@icebreakers/stylelint-config": "^2.0.4",
-    "@types/node": "^25.5.0",
+    "@icebreakers/stylelint-config": "^3.0.6",
+    "@types/node": "^25.6.0",
     "@types/semver": "^7.7.1",
-    "@vitest/coverage-v8": "~4.1.0",
+    "@vitest/coverage-v8": "~4.1.5",
     "ci-info": "^4.4.0",
     "cross-env": "^10.1.0",
-    "defu": "^6.1.4",
-    "es-toolkit": "^1.45.1",
-    "eslint": "^10.0.3",
+    "defu": "^6.1.7",
+    "es-toolkit": "^1.46.1",
+    "eslint": "^10.3.0",
     "husky": "^9.1.7",
-    "nano-staged": "^0.9.0",
+    "lint-staged": "^16.4.0",
     "only-allow": "^1.2.2",
     "pathe": "^2.0.3",
-    "pkg-types": "^2.3.0",
-    "stylelint": "^17.4.0",
-    "tailwindcss": "^4.2.1",
-    "tsdown": "0.21.2",
+    "pkg-types": "^2.3.1",
+    "repoctl": "workspace:*",
+    "stylelint": "^17.9.1",
+    "tailwindcss": "^4.2.4",
+    "tsd": "^0.33.0",
+    "tsdown": "0.21.10",
     "tslib": "^2.8.1",
     "tsup": "^8.5.1",
     "tsx": "^4.21.0",
-    "turbo": "^2.8.17",
-    "type-fest": "^5.4.4",
-    "typescript": "^5.9.3",
-    "unbuild": "^3.6.1",
-    "vitest": "~4.1.0",
-    "yaml": "^2.8.2"
+    "turbo": "^2.9.7",
+    "type-fest": "^5.6.0",
+    "typescript": "^6.0.3",
+    "vitest": "~4.1.5",
+    "yaml": "^2.8.4"
   },
   "publishConfig": {
     "access": "public",

package/assets/repoctl.config.ts

@@ -0,0 +1,68 @@
+import type { MonorepoConfig } from 'repoctl'
+
+function createLintStagedConfig(monorepoCommand: string) {
+  return {
+    '*.{js,jsx,mjs,ts,tsx,mts,cts}': [
+      'eslint --fix',
+    ],
+    '*.vue': [
+      'eslint --fix',
+      'stylelint --fix --allow-empty-input',
+    ],
+    '*.{ts,tsx,mts,cts,vue}': (files: string[]) => {
+      const uniqueFiles = [...new Set(files)]
+      if (uniqueFiles.length === 0) {
+        return []
+      }
+      return `${monorepoCommand} verify staged-typecheck ${uniqueFiles.map(file => `'${file.replaceAll('\'', '\'\\\'\'')}'`).join(' ')}`
+    },
+    '*.{json,md,mdx,html,yml,yaml}': [
+      'eslint --fix',
+    ],
+    '*.{css,scss,sass,less}': [
+      'stylelint --fix --allow-empty-input',
+    ],
+  }
+}
+
+export default {
+  commands: {
+    create: {
+      defaultTemplate: 'tsdown',
+      renameJson: false,
+    },
+    clean: {
+      autoConfirm: false,
+      ignorePackages: ['@icebreakers/website'],
+    },
+    upgrade: {
+      skipOverwrite: false,
+      mergeTargets: true,
+    },
+  },
+  tooling: {
+    commitlint: {
+      extends: ['@commitlint/config-conventional'],
+    },
+    eslint: {
+      ignores: ['**/fixtures/**'],
+    },
+    stylelint: {
+      rules: {},
+    },
+    lintStaged: {
+      config: createLintStagedConfig('pnpm exec repoctl'),
+    },
+    tsconfig: {
+      compilerOptions: {},
+    },
+    vitest: {
+      includeWorkspaceRootConfig: false,
+      coverageSkipFull: true,
+    },
+    vitestProject: {
+      globals: true,
+      testTimeout: 60_000,
+    },
+  },
+} satisfies MonorepoConfig

package/assets/stylelint.config.js

@@ -1,3 +1,3 @@
-import { icebreaker } from '@icebreakers/stylelint-config'
+import { defineStylelintConfig } from 'repoctl/tooling'
 
-export default icebreaker()
+export default await defineStylelintConfig()

package/assets/tooling/ensure-tooling-built.mjs

@@ -0,0 +1,24 @@
+import { execSync } from 'node:child_process'
+import { existsSync } from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const toolingMarkerPaths = [
+  ['packages', 'monorepo', 'dist', 'tooling-entry.mjs'],
+  ['packages', 'repoctl', 'dist', 'tooling-entry.mjs'],
+]
+
+const rootDir = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..')
+
+export async function ensureToolingBuilt() {
+  const missingBuildOutput = toolingMarkerPaths.some(segments => !existsSync(path.join(rootDir, ...segments)))
+
+  if (!missingBuildOutput) {
+    return
+  }
+
+  execSync('pnpm tooling:build', {
+    cwd: rootDir,
+    stdio: 'inherit',
+  })
+}

package/assets/tooling/load-tooling-module.mjs

@@ -0,0 +1,71 @@
+import path from 'node:path'
+import { fileURLToPath, pathToFileURL } from 'node:url'
+import { ensureToolingBuilt } from './ensure-tooling-built.mjs'
+
+const rootDir = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..')
+
+const toolingEntryPaths = {
+  monorepo: path.join(rootDir, 'packages', 'monorepo', 'dist', 'tooling-entry.mjs'),
+  repoctl: path.join(rootDir, 'packages', 'repoctl', 'dist', 'tooling-entry.mjs'),
+}
+
+function getToolingImportSpecifier(entryPath, cacheBust = false) {
+  const fileUrl = pathToFileURL(entryPath)
+  return cacheBust ? `${fileUrl.href}?t=${Date.now()}` : fileUrl.href
+}
+
+export function isRecoverableToolingLoadError(error) {
+  if (!(error instanceof Error)) {
+    return false
+  }
+
+  const nodeError = /** @type {NodeJS.ErrnoException} */ (error)
+  return nodeError.code === 'ERR_MODULE_NOT_FOUND'
+    || nodeError.code === 'ENOENT'
+    || error.message.includes('Cannot find module')
+    || error.message.includes('No such file or directory')
+}
+
+async function importToolingEntry(entryPath, cacheBust = false) {
+  const specifier = getToolingImportSpecifier(entryPath, cacheBust)
+  return import(specifier)
+}
+
+export function createToolingModuleLoader({
+  ensureBuilt = ensureToolingBuilt,
+  importModule = importToolingEntry,
+} = {}) {
+  return async function loadToolingModule(entryPath) {
+    await ensureBuilt()
+
+    try {
+      return await importModule(entryPath)
+    }
+    catch (error) {
+      if (!isRecoverableToolingLoadError(error)) {
+        throw error
+      }
+
+      await ensureBuilt()
+      return importModule(entryPath, true)
+    }
+  }
+}
+
+const loadToolingModule = createToolingModuleLoader()
+
+export function loadMonorepoToolingModule() {
+  return loadToolingModule(toolingEntryPaths.monorepo)
+}
+
+export async function loadRepoctlToolingModule() {
+  try {
+    return await loadToolingModule(toolingEntryPaths.repoctl)
+  }
+  catch (error) {
+    if (!isRecoverableToolingLoadError(error)) {
+      throw error
+    }
+    return loadToolingModule(toolingEntryPaths.monorepo)
+  }
+}

package/assets/tsconfig.json

@@ -1,51 +1,3 @@
 {
-  "compilerOptions": {
-    // 指定 ECMAScript 目标版本，ESNext 表示支持最新的 ES 特性
-    "target": "ESNext",
-
-    // 指定模块系统，ESNext 使用原生 ES 模块 (import/export)
-    "module": "ESNext",
-
-    // 模块解析策略，Bundler 模式适用于打包工具（如 Vite、Webpack），支持更宽松的解析规则
-    "moduleResolution": "Bundler",
-
-    // 允许导入 .json 文件，并自动生成类型声明
-    "resolveJsonModule": true,
-
-    // 指定要包含的类型声明文件，node 提供 Node.js API 类型，vitest/globals 提供测试全局变量类型
-    "types": [
-      "node",
-      "vitest/globals"
-    ],
-
-    // 允许编译 JavaScript 文件，使其可以被导入和进行类型检查
-    "allowJs": true,
-
-    // 启用所有严格类型检查选项，包括 noImplicitAny、strictNullChecks 等
-    "strict": true,
-
-    // 严格检查可选属性类型，区分 undefined 和缺失的属性
-    "exactOptionalPropertyTypes": true,
-
-    // 要求子类重写父类方法时必须使用 override 关键字
-    "noImplicitOverride": true,
-
-    // 禁止通过索引签名（如 obj['key']）访问未在索引签名中定义的属性
-    "noPropertyAccessFromIndexSignature": true,
-
-    // 访问索引签名时返回 undefined | T，而不是 T（防止未定义访问错误）
-    "noUncheckedIndexedAccess": true,
-
-    // 不生成输出文件（仅用于类型检查，实际由打包工具处理编译）
-    "noEmit": true,
-
-    // 允许从没有默认导出的模块中默认导入（如 import React from 'react'）
-    "allowSyntheticDefaultImports": true,
-
-    // 启用 ES 模块互操作性，为 CommonJS 模块提供 synthetic default imports
-    "esModuleInterop": true,
-
-    // 跳过库文件的类型检查，提高编译速度（库文件通常已经有类型声明）
-    "skipLibCheck": true
-  }
+  "extends": "repoctl/tsconfig"
 }

package/assets/turbo.json

@@ -14,7 +14,8 @@
       ],
       "outputs": [
         "dist/**",
-        "bin/**"
+        "bin/**",
+        ".vitepress/dist/**"
       ]
     },
     "lint": {
@@ -22,12 +23,12 @@
         "^lint"
       ],
       "inputs": [
-        "src/**",
-        "lib/**",
-        "test/**",
-        "*.config.{js,ts}",
+        "**/*.{js,jsx,cjs,mjs,ts,tsx,cts,mts,vue}",
+        "**/*.{json,html,md,mdx,yml,yaml}",
+        "*.config.{js,ts,mjs,mts}",
         ".eslintrc*",
-        ".stylelintrc*"
+        ".stylelintrc*",
+        "package.json"
       ],
       "outputs": []
     },
@@ -64,6 +65,16 @@
       ],
       "outputs": []
     },
+    "tsd": {
+      "inputs": [
+        "src/**",
+        "lib/**",
+        "test-d/**",
+        "package.json",
+        "tsconfig*.json"
+      ],
+      "outputs": []
+    },
     "release": {
       "cache": false
     },