@icebreakers/monorepo-templates 1.0.15 → 1.2.0

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

@@ -1,133 +0,0 @@
-# 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 `repo:init`, `repo:doctor`, `repo:new`, and `repo: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 init --yes
-```
-
-`repo init --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`               | `repo:init/repo:new/repo:check/repo:doctor` scripts are missing   |
-| `config-file`                | A stale `monorepo.config.ts` file is still present                |
-| `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 `repo init`, team docs can use:
-
-```bash
-pnpm run repo:doctor
-pnpm run repo:new -- sdk
-pnpm run repo: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 no longer loaded at runtime; rename it to `repoctl.config.ts`.
-
-### Local Tooling Loader
-
-If `doctor` reports local source tooling loaders, migrate with:
-
-```bash
-pnpm exec repo upgrade --yes
-```
-
-The same migration also converts simple wrappers from `@icebreakers/commitlint-config`, `@icebreakers/eslint-config`, and `@icebreakers/stylelint-config` to `repoctl/tooling`. Complex ESLint configs keep their rules, ignores, overrides, and extra flat config semantics.
-
-### Workspace Pattern Gaps
-
-Run:
-
-```bash
-pnpm exec repo init --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/commands.md

@@ -1,120 +0,0 @@
-# Command Reference
-
-This page focuses on high-value repoctl commands and options.
-
-## Main Entry
-
-```bash
-pnpm exec repo init
-pnpm exec repo doctor
-pnpm exec repo templates
-pnpm exec repo new
-pnpm exec repo check
-```
-
-Generated repositories also expose:
-
-```bash
-pnpm run repo:init
-pnpm run repo:doctor
-pnpm run repo:new
-pnpm run repo:check
-```
-
-## `repo init`
-
-```bash
-repo init
-repo init --yes
-repo init --preset minimal
-repo init --preset standard --force
-repo init --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, `repo:*` root scripts, stale config files, 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

@@ -1,69 +0,0 @@
-# Configuration
-
-repoctl recommends one root config file:
-
-```txt
-repoctl.config.ts
-```
-
-`monorepo.config.ts` is no longer loaded at runtime. Rename it to `repoctl.config.ts` before running repoctl.
-
-## 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

@@ -1,116 +0,0 @@
-# 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 init
-pnpm exec repo doctor
-```
-
-| Command        | Purpose                                                                       |
-| -------------- | ----------------------------------------------------------------------------- |
-| `pnpm install` | Install workspace dependencies and local links                                |
-| `repo init`    | Add recommended scripts, workspace patterns, and tooling entries              |
-| `repo doctor`  | Check root files, Node version, CLI dependency, stale config files, 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 Root Scripts
-
-After `repo init`, daily commands can be shorter:
-
-```bash
-pnpm run repo:init
-pnpm run repo:doctor -- --json
-pnpm run repo:new -- sdk --template tsdown
-pnpm run repo:check
-```
-
-| Root script                    | Equivalent CLI               |
-| ------------------------------ | ---------------------------- |
-| `pnpm run repo:init`           | `pnpm exec repo init`        |
-| `pnpm run repo:doctor -- args` | `pnpm exec repo doctor args` |
-| `pnpm run repo:new -- args`    | `pnpm exec repo new args`    |
-| `pnpm run repo: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 run repo: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

@@ -1,74 +0,0 @@
-# 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 init`    |
-| 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
-
-### repo:\* Root Scripts
-
-```bash
-pnpm run repo:init
-pnpm run repo:doctor
-pnpm run repo:new
-pnpm run repo:check
-```
-
-These are the best commands for day-to-day team docs. They are short, explicit, and do not collide with pnpm built-in commands.
-
-### Explicit CLI Calls
-
-```bash
-pnpm exec repo init
-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.
-
-## Command Entrypoints
-
-The package exposes multiple bins:
-
-```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/templates.md

@@ -1,128 +0,0 @@
-# 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)