@icebreakers/monorepo-templates 1.0.2 → 1.0.3

package/templates/vitepress/en/repoctl/adopt-existing.md

@@ -0,0 +1,131 @@
+# Adopt Existing Repositories
+
+repoctl is not only for newly generated repositories. It can be adopted gradually in existing pnpm workspaces by using diagnostics and conservative asset syncs.
+
+## Good Candidates
+
+A repository is a good fit when:
+
+- It already uses pnpm, or is ready to move to pnpm.
+- It has a root `package.json`.
+- It can use workspace folders such as `apps/*`, `packages/*`, or `examples/*`.
+- The team wants stable daily entries such as `setup`, `doctor`, `new`, and `check`.
+
+If the repository is not yet a pnpm workspace, start with a minimal `pnpm-workspace.yaml`:
+
+```yaml
+packages:
+  - apps/*
+  - packages/*
+```
+
+## Step 1: Install And Setup
+
+```bash
+pnpm add -D repoctl
+pnpm exec repo setup --yes
+```
+
+`setup --yes` uses safe defaults. It adds recommended scripts and workspace patterns, but it does not blindly overwrite existing README, package.json, pnpm-workspace.yaml, or tooling files.
+
+## Step 2: Save The First Diagnostic Report
+
+```bash
+pnpm exec repo doctor --markdown --redact --out reports/doctor-before.md
+pnpm exec repo doctor --json --out reports/doctor-before.json
+```
+
+Prefer saving the first report as a PR comment or CI artifact instead of relying only on terminal output.
+
+Watch these checks:
+
+| Check                        | Common Issue                                                      |
+| ---------------------------- | ----------------------------------------------------------------- |
+| `package-json`               | Current directory is not the repository root                      |
+| `workspace-manifest`         | `pnpm-workspace.yaml` is missing                                  |
+| `node-version`               | Root package has no `engines.node`, or the version does not match |
+| `tool-package`               | `repoctl` is not installed                                        |
+| `root-scripts`               | `setup/new/check/doctor` scripts are missing                      |
+| `config-file`                | `repoctl.config.ts` and `monorepo.config.ts` coexist              |
+| `commit-hooks`               | Husky and lint-staged are only partially configured               |
+| `workspace-package-coverage` | Some package.json files are not covered by workspace patterns     |
+
+## Step 3: Sync Conservatively
+
+```bash
+pnpm exec repo upgrade --no-overwrite
+pnpm exec repo doctor --markdown --redact --out reports/doctor-after.md
+```
+
+Use `--no-overwrite` for the first adoption pass. It syncs missing assets while preserving changed managed files.
+
+## Step 4: Preview Verification
+
+```bash
+pnpm exec repo check --dry-run
+pnpm exec repo check --json --out reports/check-plan.json
+pnpm exec repo check --markdown --redact --out reports/check-plan.md
+```
+
+Review the plan before wiring hooks or CI.
+
+## Step 5: Use Root Scripts
+
+After `setup`, team docs can use:
+
+```bash
+pnpm doctor
+pnpm new
+pnpm check
+```
+
+CI and automation should still prefer explicit commands:
+
+```bash
+pnpm exec repo doctor --strict
+pnpm exec repo check --full
+```
+
+## Step 6: Resolve Legacy Config
+
+### Config Conflicts
+
+Keep only:
+
+```txt
+repoctl.config.ts
+```
+
+`monorepo.config.ts` is for compatibility with older projects.
+
+### Local Tooling Loader
+
+If `doctor` reports local source tooling loaders, migrate with:
+
+```bash
+pnpm exec repo upgrade --yes
+```
+
+### Workspace Pattern Gaps
+
+Run:
+
+```bash
+pnpm exec repo setup --yes
+```
+
+or manually extend `pnpm-workspace.yaml`.
+
+## Recommended PR Shape
+
+1. Install `repoctl` and add root scripts.
+2. Attach `doctor-before` and `doctor-after` reports.
+3. Sync or migrate tooling config.
+4. Wire hooks and CI.
+5. Verify scaffolding paths with `repo new --dry-run`.
+
+## Keep Reading
+
+- [Workflows and CI](./workflows.md)
+- [Troubleshooting](./troubleshooting.md)
+- [Configuration](./config.md)

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

@@ -0,0 +1,71 @@
+# Command Aliases
+
+repoctl keeps several aliases for terminal convenience. Team docs should still prefer full commands because they are easier for new users to read.
+
+## Binary Aliases
+
+The `repoctl` package exposes these bins:
+
+```bash
+repo
+repoctl
+monorepo
+rc
+mo
+```
+
+The docs recommend `repo`.
+
+Compatibility entry points remain available:
+
+```bash
+repoctl doctor
+monorepo doctor
+rc doctor
+mo doctor
+```
+
+## Top-Level Aliases
+
+| Recommended      | Alias       | Purpose                       |
+| ---------------- | ----------- | ----------------------------- |
+| `repo setup`     | `repo init` | Initialize workspace defaults |
+| `repo upgrade`   | `repo sync` | Sync standard template assets |
+| `repo templates` | `repo tpl`  | Inspect or check templates    |
+
+## Group Aliases
+
+| Full Command                   | Alias           |
+| ------------------------------ | --------------- |
+| `repo workspace`               | `repo ws`       |
+| `repo workspace upgrade`       | `repo ws up`    |
+| `repo workspace list`          | `repo ws ls`    |
+| `repo workspace clean`         | `repo ws rm`    |
+| `repo tooling`                 | `repo tg`       |
+| `repo tooling init`            | `repo tg i`     |
+| `repo package`                 | `repo pkg`      |
+| `repo package create`          | `repo pkg new`  |
+| `repo verify`                  | `repo v`        |
+| `repo verify pre-push`         | `repo v push`   |
+| `repo verify pre-commit`       | `repo v commit` |
+| `repo verify commit-msg`       | `repo v msg`    |
+| `repo verify staged-typecheck` | `repo v tc`     |
+| `repo env`                     | `repo e`        |
+| `repo env info`                | `repo e i`      |
+| `repo env snapshot`            | `repo e s`      |
+| `repo env paths`               | `repo e p`      |
+| `repo env support`             | `repo e b`      |
+| `repo env mirror`              | `repo e m`      |
+| `repo config`                  | `repo cfg`      |
+| `repo config inspect`          | `repo cfg i`    |
+| `repo skills`                  | `repo sk`       |
+| `repo skills sync`             | `repo sk s`     |
+| `repo ai prompt`               | `repo ai p`     |
+| `repo ai prompt create`        | `repo ai p new` |
+
+## Recommendation
+
+- Use full commands in onboarding docs.
+- Use root scripts in project README files.
+- Use short aliases in maintainer scripts only when the surrounding docs explain them.
+- Prefer full commands in CI logs.

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

@@ -0,0 +1,120 @@
+# Command Reference
+
+This page focuses on high-value repoctl commands and options.
+
+## Main Entry
+
+```bash
+pnpm exec repo setup
+pnpm exec repo doctor
+pnpm exec repo templates
+pnpm exec repo new
+pnpm exec repo check
+```
+
+Generated repositories also expose:
+
+```bash
+pnpm setup
+pnpm doctor
+pnpm new
+pnpm check
+```
+
+## `repo setup`
+
+```bash
+repo setup
+repo setup --yes
+repo setup --preset minimal
+repo setup --preset standard --force
+repo setup --overwrite
+```
+
+Use it to initialize recommended workspace defaults. It skips existing managed files by default, appends missing workspace patterns, and supports non-interactive CI usage with `--yes`.
+
+## `repo doctor`
+
+```bash
+repo doctor
+repo doctor --strict
+repo doctor --json --out reports/doctor.json
+repo doctor --markdown --redact --out reports/doctor.md
+```
+
+Use it to check root workspace files, Node compatibility, CLI dependency presence, root scripts, config conflicts, and commit hooks.
+
+`--strict` treats warnings as failures. `--redact` removes local absolute paths from shareable reports.
+
+## `repo templates`
+
+```bash
+repo templates
+repo templates tsdown
+repo templates --category library
+repo templates --check
+repo templates --json
+repo templates --markdown --out docs/templates.md
+```
+
+Use it to discover built-in template keys, inspect metadata, verify template health, or generate machine-readable output.
+
+## `repo new`
+
+```bash
+repo new
+repo new sdk --template tsdown
+repo new docs --template vitepress
+repo new docs --template vitepress --dry-run
+repo new docs --template vitepress --json --out plans/docs.json
+```
+
+Use it to create packages and apps. Explicit template keys are validated first; invalid keys fail with suggestions instead of silently falling back.
+
+## `repo check`
+
+```bash
+repo check
+repo check --staged
+repo check --full
+repo check --edit-file .git/COMMIT_EDITMSG
+repo check --dry-run
+repo check --json --out reports/check-plan.json
+repo check --markdown --redact --out reports/check-plan.md
+```
+
+Use it to preview or run the recommended local verification flow. `--staged` is closer to pre-commit; `--full` is closer to pre-push.
+
+## `repo upgrade`
+
+```bash
+repo upgrade
+repo upgrade --yes
+repo upgrade --overwrite
+repo upgrade --no-overwrite
+repo upgrade --core
+repo upgrade -i
+repo upgrade -s
+```
+
+Use it to sync standard assets and scripts. `--core` skips GitHub-related assets. `--no-overwrite` preserves changed files.
+
+## Grouped Commands
+
+```bash
+repo ws ls
+repo ws ls --json --out reports/workspaces.json
+repo ws up
+repo tg init --all
+repo verify pre-commit
+repo verify pre-push
+repo env support --markdown --redact --out reports/support.md
+repo config inspect
+repo skills sync --codex
+```
+
+## Keep Reading
+
+- [Workflows and CI](./workflows.md)
+- [Troubleshooting](./troubleshooting.md)
+- [Command Aliases](./aliases.md)

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

@@ -0,0 +1,69 @@
+# Configuration
+
+repoctl recommends one root config file:
+
+```txt
+repoctl.config.ts
+```
+
+`monorepo.config.ts` remains supported for compatibility, but the two files cannot coexist. `repo doctor` reports the conflict as a blocking issue.
+
+## Minimal Config
+
+```ts
+import { defineMonorepoConfig } from 'repoctl'
+
+export default defineMonorepoConfig({
+  commands: {
+    create: {
+      defaultTemplate: 'tsdown',
+    },
+  },
+})
+```
+
+After setting `commands.create.defaultTemplate`, this command can create a package without asking for the template:
+
+```bash
+repo new utils
+```
+
+## Common Config
+
+```ts
+import { defineMonorepoConfig } from 'repoctl'
+
+export default defineMonorepoConfig({
+  commands: {
+    init: {
+      preset: 'standard',
+    },
+    create: {
+      defaultTemplate: 'tsdown',
+    },
+    clean: {
+      autoConfirm: true,
+    },
+    upgrade: {
+      skipOverwrite: true,
+    },
+  },
+})
+```
+
+| Option                            | Purpose                                         |
+| --------------------------------- | ----------------------------------------------- |
+| `commands.init.preset`            | Default setup preset                            |
+| `commands.create.defaultTemplate` | Default template for `repo new <name>`          |
+| `commands.clean.autoConfirm`      | Whether clean commands confirm by default       |
+| `commands.upgrade.skipOverwrite`  | Whether upgrade preserves changed managed files |
+
+## Inspect Config
+
+```bash
+repo config inspect
+repo cfg i --json --out reports/config.json
+repo cfg i --markdown --redact --out reports/config.md
+```
+
+Use `--redact` before sharing reports in issues, PRs, or external support channels.

package/templates/vitepress/en/repoctl/getting-started.md

@@ -0,0 +1,116 @@
+# Getting Started
+
+This guide follows the order you would use when adding repoctl to a workspace.
+
+## Prerequisites
+
+- Node.js 20 or newer.
+- pnpm. Corepack is recommended: `corepack enable`.
+- Git. `repo doctor` reads repository metadata and checks the commit workflow.
+
+```bash
+node -v
+pnpm -v
+git --version
+```
+
+## Install
+
+```bash
+pnpm add -D repoctl
+```
+
+If the repository was generated from this template, the dependency and root scripts may already be present.
+
+## Initialize Defaults
+
+```bash
+pnpm install
+pnpm exec repo setup
+pnpm exec repo doctor
+```
+
+| Command        | Purpose                                                                     |
+| -------------- | --------------------------------------------------------------------------- |
+| `pnpm install` | Install workspace dependencies and local links                              |
+| `repo setup`   | Add recommended scripts, workspace patterns, and tooling entries            |
+| `repo doctor`  | Check root files, Node version, CLI dependency, config conflicts, and hooks |
+
+Fix blocking issues reported by `doctor`, then run it again.
+
+## Create A Package
+
+List templates first:
+
+```bash
+pnpm exec repo templates
+```
+
+Create a TypeScript library:
+
+```bash
+pnpm exec repo new sdk --template tsdown
+```
+
+Preview before writing files:
+
+```bash
+pnpm exec repo new sdk --template tsdown --dry-run
+pnpm exec repo new sdk --template tsdown --json --out plans/sdk.json
+```
+
+`--json` and `--out` imply `--dry-run`, which makes them suitable for CI, editor integrations, and scripts.
+
+## Use Short Root Scripts
+
+After `repo setup`, daily commands can be shorter:
+
+```bash
+pnpm setup
+pnpm doctor
+pnpm new sdk --template tsdown
+pnpm check
+```
+
+| Root script   | Equivalent CLI          |
+| ------------- | ----------------------- |
+| `pnpm setup`  | `pnpm exec repo setup`  |
+| `pnpm doctor` | `pnpm exec repo doctor` |
+| `pnpm new`    | `pnpm exec repo new`    |
+| `pnpm check`  | `pnpm exec repo check`  |
+
+## Verify Before Committing
+
+```bash
+pnpm build
+pnpm lint
+pnpm typecheck
+pnpm test
+```
+
+Or use the repoctl verification entry:
+
+```bash
+pnpm check
+pnpm exec repo check --dry-run
+pnpm exec repo check --json --out reports/check-plan.json
+```
+
+## Sync Template Assets
+
+```bash
+pnpm exec repo upgrade
+pnpm exec repo upgrade --no-overwrite
+pnpm exec repo upgrade --yes
+```
+
+- `--no-overwrite` preserves changed managed files.
+- `--yes` or `--overwrite` is for explicit automated overwrites.
+- Non-TTY environments do not open interactive prompts.
+
+## Next Steps
+
+- Adopt an existing repository: [Adopt Existing Repositories](./adopt-existing.md).
+- Set team defaults: [Configuration](./config.md).
+- Inspect template keys: [Templates](./templates.md).
+- Share diagnostic output: [Troubleshooting](./troubleshooting.md).

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

@@ -0,0 +1,74 @@
+# repoctl Overview
+
+`repoctl` is the user-facing package name for this monorepo toolkit. Its recommended command is `repo`.
+
+The CLI does not replace pnpm, Turborepo, or changesets. It gives teams a stable layer for common monorepo actions: setup, diagnostics, scaffolding, local verification, and template asset upgrades.
+
+## When To Use It
+
+| Goal                                                  | Command                  |
+| ----------------------------------------------------- | ------------------------ |
+| Add recommended scripts and workspace defaults        | `pnpm exec repo setup`   |
+| Check whether a repository is ready to develop        | `pnpm exec repo doctor`  |
+| Create a package, app, docs site, service, or CLI     | `pnpm exec repo new`     |
+| Reproduce the recommended pre-commit or pre-push flow | `pnpm exec repo check`   |
+| Sync newer standard assets from the template          | `pnpm exec repo upgrade` |
+| Persist output for CI, editors, or issue reports      | `--json --out <file>`    |
+
+## Recommended Command Layers
+
+### Root Scripts
+
+```bash
+pnpm setup
+pnpm doctor
+pnpm new
+pnpm check
+```
+
+These are the best commands for day-to-day team docs.
+
+### Explicit CLI Calls
+
+```bash
+pnpm exec repo setup
+pnpm exec repo doctor
+pnpm exec repo templates
+pnpm exec repo new sdk --template tsdown
+pnpm exec repo check --dry-run
+```
+
+Use this form in CI, scripts, troubleshooting docs, and reproducible examples.
+
+### Grouped Commands
+
+```bash
+pnpm exec repo ws ls
+pnpm exec repo tg init --all
+pnpm exec repo env support --markdown --redact
+pnpm exec repo config inspect
+```
+
+Grouped commands are for maintainers and automation that need finer control.
+
+## Compatibility
+
+The package still supports compatibility entry points:
+
+```bash
+pnpm exec repoctl doctor
+pnpm exec repoctl new
+```
+
+The docs prefer `repo` so new users only need to remember one command name.
+
+## Keep Reading
+
+- [Getting Started](./getting-started.md)
+- [Choose By Scenario](./scenarios.md)
+- [Command Reference](./commands.md)
+- [Configuration](./config.md)
+- [Templates](./templates.md)
+- [Workflows and CI](./workflows.md)
+- [Troubleshooting](./troubleshooting.md)
+- [Command Aliases](./aliases.md)

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).