repoctl

English

简体中文

English

简体中文

Appearance

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:

CheckCommon Issue
package-jsonCurrent directory is not the repository root
workspace-manifestpnpm-workspace.yaml is missing
node-versionRoot package has no engines.node, or the version does not match
tool-packagerepoctl is not installed
root-scriptsrepo:init/repo:new/repo:check/repo:doctor scripts are missing
config-fileA stale monorepo.config.ts file is still present
commit-hooksHusky and lint-staged are only partially configured
workspace-package-coverageSome 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.

  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 ​