@icebreakers/monorepo-templates 1.0.2 → 1.0.4

package/templates/vitepress/en/repoctl/scenarios.md

@@ -0,0 +1,117 @@
+# Choose By Scenario
+
+Start here when you know what you want to do, but not which repoctl command to use.
+
+## I Just Opened A Repository
+
+```bash
+pnpm install
+pnpm doctor
+```
+
+If `pnpm doctor` does not exist yet:
+
+```bash
+pnpm add -D repoctl
+pnpm exec repo setup --yes
+pnpm exec repo doctor
+```
+
+Keep reading: [Getting Started](./getting-started.md).
+
+## I Want To Adopt repoctl In An Existing Repo
+
+```bash
+pnpm add -D repoctl
+pnpm exec repo setup --yes
+pnpm exec repo doctor --markdown --redact --out reports/doctor-before.md
+pnpm exec repo upgrade --no-overwrite
+pnpm exec repo doctor --markdown --redact --out reports/doctor-after.md
+```
+
+Keep reading: [Adopt Existing Repositories](./adopt-existing.md).
+
+## I Want To Create A Package Or App
+
+```bash
+pnpm exec repo templates
+pnpm exec repo new sdk --template tsdown
+pnpm exec repo new docs --template vitepress --dry-run
+```
+
+For daily development, root scripts also work:
+
+```bash
+pnpm new sdk --template tsdown
+```
+
+Keep reading: [Templates](./templates.md).
+
+## I Want To Check Before Committing
+
+```bash
+pnpm check
+pnpm exec repo check --dry-run
+pnpm exec repo check --full
+```
+
+Save the plan when automation needs it:
+
+```bash
+pnpm exec repo check --json --out reports/check-plan.json
+pnpm exec repo check --markdown --redact --out reports/check-plan.md
+```
+
+Keep reading: [Workflows and CI](./workflows.md).
+
+## I Want To Debug CI Or Another Machine
+
+```bash
+pnpm exec repo doctor --markdown --redact --out reports/doctor.md
+pnpm exec repo env support --markdown --redact --out reports/support.md
+pnpm exec repo env snapshot --json --out reports/snapshot.json
+```
+
+Keep reading: [Troubleshooting](./troubleshooting.md).
+
+## I Want To Sync Standard Assets
+
+```bash
+pnpm exec repo upgrade --no-overwrite
+pnpm exec repo upgrade --yes
+pnpm exec repo upgrade --core
+```
+
+| Goal                                       | Command                       |
+| ------------------------------------------ | ----------------------------- |
+| First adoption pass, preserve local config | `repo upgrade --no-overwrite` |
+| Explicitly overwrite managed assets        | `repo upgrade --yes`          |
+| Sync only core config                      | `repo upgrade --core`         |
+
+## I Want To Inspect Workspace Structure
+
+```bash
+pnpm exec repo ws ls
+pnpm exec repo ws ls --json --out reports/workspaces.json
+pnpm exec repo ws ls --markdown --redact --out reports/workspaces.md
+```
+
+## I Want To Inspect Config
+
+```bash
+pnpm exec repo config inspect
+pnpm exec repo cfg i --json --out reports/config.json
+```
+
+Keep reading: [Configuration](./config.md).
+
+## I Want Shorter Commands
+
+```bash
+repo tpl
+repo ws ls
+repo e support --markdown --redact
+repo cfg i
+```
+
+Keep reading: [Command Aliases](./aliases.md).

package/templates/vitepress/en/repoctl/templates.md

@@ -0,0 +1,128 @@
+# Templates
+
+repoctl templates are maintained by `@icebreakers/monorepo-templates`. The CLI, scaffolder, and docs share the same template metadata.
+
+## Built-In Templates
+
+| Key           | Category | Default target     | Use case                |
+| ------------- | -------- | ------------------ | ----------------------- |
+| `tsdown`      | library  | `packages/tsdown`  | TypeScript library      |
+| `vue-lib`     | library  | `packages/vue-lib` | Vue 3 component library |
+| `vue-hono`    | app      | `apps/client`      | Vue 3 + Hono app        |
+| `hono-server` | service  | `apps/server`      | Hono API service        |
+| `vitepress`   | docs     | `apps/website`     | VitePress docs site     |
+| `cli`         | tool     | `apps/cli`         | TypeScript CLI          |
+
+## Discover Templates
+
+```bash
+repo templates
+repo templates tsdown
+repo templates --category library
+repo templates --json
+repo templates --markdown --out docs/templates.md
+```
+
+## Create From A Template
+
+```bash
+repo new sdk --template tsdown
+repo new ui --template vue-lib
+repo new api --template hono-server
+repo new website --template vitepress
+repo new toolbox --template cli
+```
+
+Simple names are placed in the conventional target folder. Library templates go under `packages/`; app templates go under `apps/`. If you pass an explicit path such as `packages/shared-utils`, repoctl respects it.
+
+## Choose By Goal
+
+### Publish an npm library
+
+```bash
+repo new sdk --template tsdown
+```
+
+Check first:
+
+- `package.json` `name`, `exports`, and `types`.
+- Whether `tsdown.config.ts` matches the desired output format.
+- Whether public types need `tsd` tests.
+
+### Build reusable Vue components
+
+```bash
+repo new ui --template vue-lib
+```
+
+Check first:
+
+- Component entry points only expose stable APIs.
+- Styles pass Stylelint.
+- A docs site or example app should be created alongside it if needed.
+
+### Create an app or service
+
+```bash
+repo new web --template vue-hono
+repo new api --template hono-server
+```
+
+Check first:
+
+- Runtime environment variables and deployment constraints.
+- `dev`, `build`, and `typecheck` scripts are part of root tasks.
+- CI needs integration or E2E tests.
+
+### Create a docs site
+
+```bash
+repo new docs --template vitepress
+```
+
+Check first:
+
+- Nav and sidebar are organized around the product or package.
+- A second locale is required.
+- `repo templates --markdown` output should be written into docs.
+
+### Create a CLI
+
+```bash
+repo new toolbox --template cli
+```
+
+Check first:
+
+- The `bin` field matches the final command name.
+- Argument parsing, exit codes, and help output are testable.
+- README documents command usage.
+
+## Preview Creation
+
+```bash
+repo new website --template vitepress --dry-run
+repo new website --template vitepress --json
+repo new website --template vitepress --json --out plans/website.json
+```
+
+`--dry-run` does not write files. It shows the template, source directory, target directory, package name, and output files.
+
+`--json` emits the same plan as structured data and implies `--dry-run`.
+
+`--out <file>` persists the preview and also implies `--dry-run`.
+
+## Check Template Health
+
+```bash
+repo templates --check
+repo templates --check --json
+```
+
+The check validates duplicate sources and targets, existing source directories, package metadata, categories, descriptions, and temporary files that would be filtered by the scaffolder.
+
+## Keep Reading
+
+- [Adopt Existing Repositories](./adopt-existing.md)
+- [Workflows and CI](./workflows.md)
+- [Configuration](./config.md)

package/templates/vitepress/en/repoctl/troubleshooting.md

@@ -0,0 +1,96 @@
+# Troubleshooting
+
+repoctl focuses on reports that can be reproduced, saved, and shared.
+
+## Start With Doctor
+
+```bash
+repo doctor
+repo doctor --strict
+```
+
+`doctor` checks:
+
+- Current directory and repository root.
+- Node.js version.
+- `pnpm-workspace.yaml`.
+- The `repoctl` CLI dependency.
+- Recommended root scripts.
+- Conflicting config files.
+- Husky and lint-staged wiring.
+
+## Save A Diagnostic Report
+
+```bash
+repo doctor --json --out reports/doctor.json
+repo doctor --markdown --redact --out reports/doctor.md
+```
+
+Markdown reports are useful in issues and PRs. `--redact` removes local absolute paths.
+
+## Inspect The Verification Plan
+
+```bash
+repo check --dry-run
+repo check --json --out reports/check-plan.json
+repo check --markdown --redact --out reports/check-plan.md
+```
+
+Use this when you need to understand why a file triggers a workspace typecheck or which tasks pre-push would run.
+
+## Collect Environment Information
+
+```bash
+repo env info
+repo env support --markdown --redact --out reports/support.md
+repo env snapshot --json --out reports/snapshot.json
+repo env paths --markdown --redact --out reports/paths.md
+```
+
+These commands help compare local, CI, Git, Node, pnpm, and workspace differences.
+
+## Common Fixes
+
+### Not At Repository Root
+
+Change into the directory that contains `pnpm-workspace.yaml` and the root `package.json`, then run:
+
+```bash
+repo doctor
+```
+
+### Conflicting Config Files
+
+Keep only:
+
+```txt
+repoctl.config.ts
+```
+
+`monorepo.config.ts` is for compatibility with older projects.
+
+### Unknown Template Key
+
+List available templates:
+
+```bash
+repo templates
+```
+
+Explicit `--template` values are validated first. Invalid keys fail with suggestions.
+
+### Automation Should Not Prompt
+
+Use non-interactive options:
+
+```bash
+repo setup --yes
+repo upgrade --no-overwrite
+repo check --json --out reports/check-plan.json
+```
+
+## Keep Reading
+
+- [Workflows and CI](./workflows.md)
+- [Command Reference](./commands.md)
+- [Command Aliases](./aliases.md)

package/templates/vitepress/en/repoctl/workflows.md

@@ -0,0 +1,89 @@
+# Workflows and CI
+
+repoctl commands have two audiences: humans using short daily commands, and automation consuming stable reports.
+
+## Local Daily Workflow
+
+```bash
+pnpm install
+pnpm doctor
+pnpm new sdk --template tsdown
+pnpm check
+pnpm build
+```
+
+| Step           | What It Proves                                          |
+| -------------- | ------------------------------------------------------- |
+| `pnpm install` | Workspace dependencies and local links are ready        |
+| `pnpm doctor`  | Root files, Node, scripts, config, and hooks are usable |
+| `pnpm new`     | New packages follow template conventions                |
+| `pnpm check`   | The lightweight local verification flow is reproducible |
+| `pnpm build`   | The workspace build graph has no obvious breakage       |
+
+## Adopt An Existing Repository
+
+```bash
+pnpm add -D repoctl
+pnpm exec repo setup --yes
+pnpm exec repo doctor --markdown --out reports/doctor.md
+pnpm exec repo upgrade --no-overwrite
+pnpm exec repo doctor
+```
+
+Start conservatively with `--no-overwrite`. After reviewing asset drift, decide whether `--yes` or `--overwrite` is appropriate.
+
+## Fast CI Gate
+
+```bash
+pnpm install --frozen-lockfile
+pnpm exec repo doctor --strict
+pnpm exec repo check --full
+```
+
+This is a simple gate for small repositories or early projects. `doctor --strict` treats warnings as failures.
+
+## CI Report Mode
+
+```bash
+pnpm exec repo doctor --json --out reports/doctor.json
+pnpm exec repo check --json --out reports/check-plan.json
+pnpm exec repo env support --markdown --redact --out reports/support.md
+```
+
+Use these outputs as CI artifacts:
+
+- `doctor.json` for scripts.
+- `check-plan.json` to explain verification routing.
+- `support.md` for issues, PRs, and external collaboration.
+
+## Hooks
+
+```bash
+repo verify pre-commit
+repo verify staged-typecheck packages/app/src/main.ts
+repo verify commit-msg .git/COMMIT_EDITMSG
+repo verify pre-push
+```
+
+| Stage      | Recommended Behavior                                      |
+| ---------- | --------------------------------------------------------- |
+| pre-commit | Focus on staged files, lint, and workspace typecheck      |
+| commit-msg | Enforce Conventional Commit messages                      |
+| pre-push   | Run root lint/typecheck and affected build/test/tsd tasks |
+
+## Non-Interactive Options
+
+| Scenario                              | Option                                             |
+| ------------------------------------- | -------------------------------------------------- |
+| Accept setup defaults                 | `repo setup --yes`                                 |
+| Preserve changed files during upgrade | `repo upgrade --no-overwrite`                      |
+| Explicitly overwrite standard assets  | `repo upgrade --yes` or `repo upgrade --overwrite` |
+| Preview only                          | `--dry-run`                                        |
+| Output for scripts                    | `--json --out <file>`                              |
+| Share a redacted report               | `--markdown --redact --out <file>`                 |
+
+## Keep Reading
+
+- [Command Reference](./commands.md)
+- [Troubleshooting](./troubleshooting.md)
+- [Command Aliases](./aliases.md)

package/templates/vitepress/getting-started.md

@@ -1,243 +1,40 @@
----
-layout: doc
----
-
 # 新手使用指南
 
-这篇指南按第一次接手仓库的顺序写。你不需要先理解所有工具，只要先把仓库跑起来，再慢慢看更细的命令。
-
-## 你需要先准备什么
+这篇旧入口已经收敛到 repoctl 主线。新读者建议直接阅读：
 
-- Node.js 20 或更高版本。
-- pnpm。推荐通过 Corepack 启用：`corepack enable`。
-- Git。`repo doctor` 会读取仓库信息，用来补全新包的 repository、bugs 和 author。
+- [repoctl 快速开始](./repoctl/getting-started.md)
+- [repoctl 命令速查](./repoctl/commands.md)
+- [repoctl 配置文件](./repoctl/config.md)
 
-确认版本：
+## 先这样用
 
 ```bash
-node -v
-pnpm -v
-git --version
+pnpm add -D repoctl
+pnpm exec repo setup
+pnpm exec repo doctor
+pnpm exec repo new
+pnpm exec repo check
 ```
 
-## 第一次进入仓库
+模板生成仓库里可以使用更短的根脚本：
 
 ```bash
-pnpm install
 pnpm setup
 pnpm doctor
-```
-
-这三步分别解决三件事：
-
-| 命令           | 作用                               |
-| -------------- | ---------------------------------- |
-| `pnpm install` | 安装 workspace 依赖                |
-| `pnpm setup`   | 同步推荐的根脚本、配置和工具链入口 |
-| `pnpm doctor`  | 检查当前仓库能不能顺利开始开发     |
-
-如果 `doctor` 报错，先按输出里的 `fix:` 处理。处理完再跑一次 `pnpm doctor`，直到没有 blocking issue。
-
-如果要在 CI 或脚本里读取诊断结果：
-
-```bash
-pnpm exec repo doctor --json
-pnpm exec repo doctor --json --out reports/doctor.json
-```
-
-如果希望 CI 把建议项也当成失败，使用 strict 模式：
-
-```bash
-pnpm exec repo doctor --strict
-pnpm exec repo doctor --strict --json --out reports/doctor.json
-```
-
-## 创建第一个包或应用
-
-不知道要用哪个模板时，先看列表：
-
-```bash
-pnpm exec repo templates
-```
-
-只看库包模板：
-
-```bash
-pnpm exec repo templates --category library
-```
-
-常用模板：
-
-| 模板          | 适合什么          |
-| ------------- | ----------------- |
-| `tsdown`      | TypeScript 库包   |
-| `vue-lib`     | Vue 3 组件库      |
-| `vue-hono`    | Vue 3 + Hono 应用 |
-| `hono-server` | Hono API 服务     |
-| `vitepress`   | 文档站            |
-| `cli`         | 命令行工具        |
-
-创建时可以走交互式：
-
-```bash
 pnpm new
-```
-
-也可以直接指定：
-
-```bash
-pnpm new my-lib --template tsdown
-pnpm new website --template vitepress
-pnpm new api --template hono-server
-```
-
-创建前想先确认目标目录：
-
-```bash
-pnpm new website --template vitepress --dry-run
-pnpm new website --template vitepress --json
-pnpm new website --template vitepress --json --out plans/website.json
-```
-
-如果模板 key 拼错，CLI 会直接失败并提示最接近的模板 key；它不会静默回退到默认模板。
-`--json` 用于脚本读取创建计划，隐含 `--dry-run`，不会写入文件。
-`--out` 会把创建计划写入文件，也隐含 `--dry-run`。
-
-普通名字会自动放进合适目录，比如库包放到 `packages/`，应用放到 `apps/`。如果你传入了带 `/` 的路径，例如 `packages/shared-utils`，CLI 会尊重这个路径。
-
-## 开发时怎么跑
-
-先看新建 workspace 的 `package.json`，确认它提供了哪些脚本。常见流程是：
-
-```bash
-pnpm dev
-pnpm build
-pnpm typecheck
-pnpm test
-```
-
-整仓命令由 Turborepo 调度。你在根目录执行 `pnpm build`，会构建所有声明了 `build` 脚本的 workspace 包。
-
-## 提交前检查
-
-提交前推荐按这个顺序跑：
-
-```bash
-pnpm build
-pnpm lint
-pnpm typecheck
-pnpm test
-```
-
-如果只是想跑模板推荐的本地检查：
-
-```bash
 pnpm check
 ```
 
-如果你改了公开类型 API，并且对应包有 `tsd`：
-
-```bash
-pnpm tsd
-```
-
-## 什么时候用 repo 命令
-
-生成仓库里优先记住短命令：
-
-| 日常命令      | 等价 CLI                |
-| ------------- | ----------------------- |
-| `pnpm setup`  | `pnpm exec repo setup`  |
-| `pnpm new`    | `pnpm exec repo new`    |
-| `pnpm doctor` | `pnpm exec repo doctor` |
-| `pnpm check`  | `pnpm exec repo check`  |
-
-需要更细的能力时再用 `repo`：
-
-```bash
-pnpm exec repo templates
-pnpm exec repo env paths
-pnpm exec repo env support --json --out reports/support.json
-pnpm exec repo config inspect
-pnpm exec repo ws ls
-pnpm exec repo ws ls --json --out reports/workspaces.json
-pnpm exec repo tg init --all
-pnpm exec repo upgrade
-```
-
-`repoctl`、`monorepo`、`rc`、`mo` 这些入口仍然兼容。新项目文档统一推荐 `repo`，减少新人记忆负担。
-
-## 更新模板标准资产
-
-当模板仓库升级后，可以同步最新推荐配置：
-
-```bash
-pnpm exec repo upgrade
-pnpm doctor
-```
-
-如果只想同步核心配置，跳过 GitHub、Renovate、开源社区文件：
-
-```bash
-pnpm exec repo upgrade --core
-```
-
-如果你不希望覆盖已有文件：
-
-```bash
-pnpm exec repo upgrade --skip-overwrite
-```
-
-## 常见问题
-
-### 提示目录已经存在
-
-`pnpm new` 不会覆盖已有目录。换一个名字，或者手动处理已有目录后再创建。
-
-### 不知道模板 key 怎么写
-
-运行：
-
-```bash
-pnpm exec repo templates
-```
-
-查看单个模板详情：
-
-```bash
-pnpm exec repo templates tsdown
-```
-
-需要给脚本读取时：
+## 知识点保留
 
-```bash
-pnpm exec repo templates --json
-```
-
-### `repoctl.config.ts` 和 `monorepo.config.ts` 同时存在
-
-只保留一个。推荐保留 `repoctl.config.ts`，旧文件名仅作为兼容入口。
-
-### 新建包之后依赖没装上
-
-新建模板只负责生成文件。生成后回到根目录运行：
-
-```bash
-pnpm install
-```
-
-然后再跑：
-
-```bash
-pnpm build
-pnpm typecheck
-pnpm test
-```
+理解工具前，先理解这几个边界：
 
-## 下一步
+| 命令           | 解决的问题                                            |
+| -------------- | ----------------------------------------------------- |
+| `repo setup`   | 补齐仓库默认脚本、workspace patterns 和基础工具链入口 |
+| `repo doctor`  | 判断仓库当前是否可用，并输出可保存的诊断报告          |
+| `repo new`     | 从内置模板创建包、应用、服务、文档站或 CLI            |
+| `repo check`   | 预览或执行提交前推荐校验                              |
+| `repo upgrade` | 同步模板最新标准资产                                  |
 
-- 想看完整命令：[命令速查](./monorepo/commands.md)
-- 想选择合适模板：[模板速查](./monorepo/templates.md)
-- 想理解 workspace 管理：[如何管理 monorepo](./monorepo/manage.md)
-- 遇到校验问题：[常见问题排障](./monorepo/troubleshooting.md)
-- 准备发包：[发包与变更日志](./monorepo/publish.md)
+如果你是在学习 monorepo 的基础概念，可以继续看 [为什么往 monorepo 方向演进](./monorepo/index.md)。