@icebreakers/monorepo-templates 1.2.1 → 1.3.1

package/templates/vitepress/.vitepress/theme/index.ts

@@ -1,4 +1,14 @@
+import type { EnhanceAppContext, Theme } from 'vitepress'
 import DefaultTheme from 'vitepress/theme'
+import HomePage from './components/HomePage.vue'
+import Layout from './Layout.vue'
 import './tailwind.css'
+import './home/index.css'
 
-export default DefaultTheme
+export default {
+  ...DefaultTheme,
+  Layout,
+  enhanceApp({ app }: EnhanceAppContext) {
+    app.component('HomePage', HomePage)
+  },
+} satisfies Theme

package/templates/vitepress/ai/llms-txt.md

@@ -9,8 +9,8 @@ The documentation build generates `/llms.txt` and `/llms-full.txt`. English is t
 ## Usage
 
 ```text
-https://repo.icebreaker.top/llms.txt
-https://repo.icebreaker.top/llms-full.txt
+https://repoctl.icebreaker.top/llms.txt
+https://repoctl.icebreaker.top/llms-full.txt
 ```
 
 Use the compact index for discovery and the full file only when the consumer has enough context budget.

package/templates/vitepress/index.md

@@ -1,63 +1,9 @@
 ---
-layout: home
-
-hero:
-  name: repoctl
-  text: Short, stable workflows for pnpm monorepos
-  tagline: Initialize, diagnose, scaffold, verify, and upgrade practical Turborepo workspaces from one CLI.
-  image:
-    src: /logo.jpg
-    alt: repoctl logo
-  actions:
-    - theme: brand
-      text: Get Started
-      link: /repoctl/getting-started
-    - theme: alt
-      text: Commands
-      link: /repoctl/commands
-    - theme: alt
-      text: AI Docs
-      link: /ai/
-
-features:
-  - title: Adopt existing workspaces
-    details: Run setup and doctor to align workspace patterns, root scripts, config files, and commit hooks.
-  - title: Create packages and apps
-    details: Scaffold libraries, apps, services, docs, and CLIs with interactive prompts or explicit template keys.
-  - title: Make checks repeatable
-    details: Preview and run local verification plans that match your lint, typecheck, build, test, and tsd workflow.
-  - title: AI-readable documentation
-    details: Generate llms.txt, llms-full.txt, and Markdown page output so AI coding tools can read the repoctl docs directly.
+layout: page
+aside: false
+pageClass: repoctl-home-page
+title: repoctl
+description: Task-first CLI for initializing, maintaining, validating, and releasing pnpm and Turborepo monorepos.
 ---
 
-## Fast Path
-
-```bash
-pnpm add -D repoctl
-pnpm exec repo init
-pnpm exec repo doctor
-pnpm exec repo new
-pnpm exec repo check
-```
-
-Generated repositories expose the same workflow as shorter root scripts:
-
-```bash
-pnpm run repo:init
-pnpm run repo:doctor
-pnpm run repo:new
-pnpm run repo:check
-```
-
-## Keep Reading
-
-- [repoctl Overview](./repoctl/index.md)
-- [Getting Started](./repoctl/getting-started.md)
-- [Adopt Existing Repositories](./repoctl/adopt-existing.md)
-- [Choose By Scenario](./repoctl/scenarios.md)
-- [Command Reference](./repoctl/commands.md)
-- [Configuration](./repoctl/config.md)
-- [Templates](./repoctl/templates.md)
-- [Workflows and CI](./repoctl/workflows.md)
-- [AI Docs: llms.txt](./ai/llms-txt.md)
-- [Knowledge Base](./knowledge/index.md)
+<HomePage locale="en" />

package/templates/vitepress/learn/index.md

@@ -0,0 +1,18 @@
+# Learn the system
+
+Use Learn after the first workflow works. These pages explain the boundaries around repoctl, monorepos, packages, templates, and the tools that run underneath.
+
+## Concepts
+
+- [How repoctl fits into a repository](./repoctl-model)
+- [Monorepo foundations](./monorepo/)
+- [Modern npm packages](./packages/)
+- [Template systems](./monorepo/templates)
+
+## Tools
+
+The [tool guides](./tools/) explain pnpm, Turborepo, versioning, hooks, staged checks, and dependency automation.
+
+## Reading order
+
+Start with the repository model, then choose either monorepo foundations or package publishing. Return to the [tasks](/tasks/) section whenever you need an executable sequence.

package/templates/vitepress/{monorepo → learn/monorepo}/commands.md

@@ -13,4 +13,4 @@
 
 One command layer matters because scripts, documentation, CI, and contributor expectations otherwise drift independently. repoctl keeps task names stable while pnpm and Turborepo continue to perform dependency installation and task execution.
 
-See the complete [repoctl command reference](../repoctl/commands.md).
+See the complete [repoctl command reference](/reference/commands).

package/templates/vitepress/{monorepo → learn/monorepo}/index.md

@@ -32,6 +32,6 @@ repoctl adds the missing workflow layer:
 
 ## Keep Reading
 
-- [repoctl Overview](../repoctl/index.md)
-- [Command Reference](../repoctl/commands.md)
-- [Templates](../repoctl/templates.md)
+- [repoctl Overview](/learn/repoctl-model)
+- [Command Reference](/reference/commands)
+- [Templates](/reference/templates)

package/templates/vitepress/{monorepo → learn/monorepo}/templates.md

@@ -11,4 +11,4 @@ repo templates --check
 
 The publishable `@icebreakers/monorepo-templates` package owns the registry and packaged assets. Individual `templates/*` workspaces are private and are not release units.
 
-See [Templates](../repoctl/templates.md) and [Template Asset Management](../repoctl/template-assets.md).
+See [Templates](/reference/templates) and [Template Asset Management](/reference/template-assets).

package/templates/vitepress/learn/packages/examples/2.npm-basic-package/README.md

@@ -0,0 +1 @@
+https://repoctl.icebreaker.top/

package/templates/vitepress/learn/packages/examples/3.npm-basic-package/README.md

@@ -0,0 +1 @@
+https://repoctl.icebreaker.top/

package/templates/vitepress/learn/packages/index.md

@@ -0,0 +1,36 @@
+# What Is An npm Package?
+
+An npm package is a versioned archive with a `package.json` contract. It may provide runtime JavaScript, type declarations, a command-line binary, configuration presets, or assets. Publishing a folder is easy; maintaining that contract is the real work.
+
+## The package boundary
+
+```text
+package.json  name, version, exports, files, engines
+README.md     install and supported usage
+dist/         built runtime and type declarations
+LICENSE       license terms for consumers
+```
+
+Only files named by `files`, exports, and package metadata should be treated as public. Internal source layout is free to change until it appears in the published contract.
+
+## Inspect what ships
+
+```bash
+npm pack --dry-run
+pnpm pack --pack-destination ./artifacts
+```
+
+Review the archive after every material packaging change. This catches missing declarations, accidental source publication, and files referenced by `exports` that were not included.
+
+## Version with intent
+
+- Patch: compatible fix or metadata correction.
+- Minor: compatible capability, such as a new public command or template.
+- Major: incompatible API, behavior, or supported runtime change.
+
+Repository versioning tools record that decision, but they cannot determine whether a consumer will be broken. Write the release note from the consumer's point of view.
+
+## Keep Reading
+
+- [Publishing A Package](/learn/packages/publish)
+- [Modern Package Guide](./modern/)

package/templates/vitepress/learn/packages/modern/bundlers.md

@@ -0,0 +1,40 @@
+# Bundlers
+
+Choose a bundler by the package boundary you need to ship. A library build needs reliable entry points and declarations; a component library also needs framework and CSS handling; an application build needs an optimized browser bundle.
+
+## Current choices
+
+| Tool       | Good fit                                        | Notes                                             |
+| ---------- | ----------------------------------------------- | ------------------------------------------------- |
+| `tsdown`   | TypeScript libraries and tooling                | Produces modern library output with declarations  |
+| `vite`     | Applications and component libraries            | Strong development server and library mode        |
+| `rolldown` | Toolchains that need Rollup-compatible behavior | Evaluate ecosystem compatibility before migration |
+
+The repoctl generic library template uses `tsdown`. Vue component libraries continue to use Vite library mode.
+
+## tsdown library configuration
+
+:::code-group
+
+```ts [tsdown.config.ts]
+import { defineConfig } from 'tsdown'
+
+export default defineConfig({
+  entry: ['./src/index.ts'],
+  format: ['cjs', 'esm'],
+  dts: true,
+  clean: true,
+  target: 'node18',
+})
+```
+
+:::
+
+## Retired defaults
+
+`tsup` and `unbuild` are not recommended for new repoctl templates. Existing projects can migrate when their build behavior and published artifacts are covered by tests. Do not rewrite a working package merely to follow a tooling trend.
+
+## Keep Reading
+
+- [TypeScript](./typescript.md)
+- [Package Entry Points](./package-entry-points.md)

package/templates/vitepress/learn/packages/modern/dts.md

@@ -0,0 +1,48 @@
+# Type Declarations
+
+Type declarations describe the public TypeScript contract of a JavaScript package. They must be generated from the same source and exported through the same public entry points as the runtime code.
+
+## Emit declarations
+
+```json
+{
+  "compilerOptions": {
+    "declaration": true,
+    "declarationMap": true,
+    "emitDeclarationOnly": false,
+    "outDir": "./dist"
+  }
+}
+```
+
+Bundlers such as tsdown can emit declaration files alongside runtime output. The important rule is that declaration paths are stable and match the package exports map.
+
+## Link types to exports
+
+```json
+{
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  }
+}
+```
+
+The top-level `types` field is useful for simple packages. Per-entry `types` declarations are necessary when a package exposes subpaths or format-specific output.
+
+## Test the public contract
+
+```bash
+pnpm tsd
+pnpm pack --dry-run
+```
+
+Type tests should import from the package name, not a source file. That proves the declarations consumers receive are compatible with the documented API.
+
+## Keep Reading
+
+- [Package Entry Points](./package-entry-points.md)
+- [TypeScript](./typescript.md)

package/templates/vitepress/learn/packages/modern/esm-vs-cjs.md

@@ -0,0 +1,42 @@
+# ESM vs CommonJS
+
+Node supports two JavaScript module systems. ESM uses `import` and `export`; CommonJS uses `require` and `module.exports`. A package can support both, but it must state how each consumer reaches the correct file.
+
+## Identify the format
+
+| Signal                          | Meaning             |
+| ------------------------------- | ------------------- |
+| `.mjs`                          | Always ESM          |
+| `.cjs`                          | Always CommonJS     |
+| `.js` with `"type": "module"`   | ESM                 |
+| `.js` without that package type | CommonJS by default |
+
+Avoid guessing from syntax alone. Node resolves a `.js` file from its extension and the nearest package boundary.
+
+## Publish both formats
+
+```json
+{
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  }
+}
+```
+
+Use an exports map rather than asking consumers to reach into `dist`. It gives each module system an intentional entry point and prevents accidental private imports becoming a public API.
+
+## Interoperability rules
+
+- Keep the package API identical across formats where possible.
+- Test both `import` and `require` from a consumer fixture.
+- Do not publish TypeScript source as the runtime entry point.
+- Use `.cjs` for CommonJS output when the package itself declares `type: module`.
+
+## Keep Reading
+
+- [Package Entry Points](./package-entry-points.md)
+- [Type Declarations](./dts.md)

package/templates/vitepress/learn/packages/modern/index.md

@@ -0,0 +1,38 @@
+# Modern Package Guide
+
+A publishable package is more than a source folder. Consumers depend on its runtime format, type declarations, entry points, files list, and compatibility policy. This guide explains the decisions that keep those contracts explicit.
+
+## Start with the consumer
+
+Before choosing a bundler or module format, answer these questions:
+
+- Will consumers load the package through ESM, CommonJS, or both?
+- Does the package ship runtime code, types, a CLI, or generated assets?
+- Which Node versions must work?
+- Should consumers import one public entry point or several intentional subpaths?
+
+The answers define the package boundary. Tooling should implement that boundary, not invent it.
+
+## Recommended shape
+
+```text
+src/          source code
+dist/         generated ESM, CommonJS, and declaration files
+package.json  public metadata and exports map
+README.md     installation and usage contract
+```
+
+Use `files` to publish only the built output and deliberately included documentation. Run `npm pack --dry-run` before publishing to inspect the actual package tarball.
+
+## Topics
+
+- [ESM vs CommonJS](./esm-vs-cjs.md)
+- [Type Declarations](./dts.md)
+- [Package Entry Points](./package-entry-points.md)
+- [Bundlers](./bundlers.md)
+- [TypeScript](./typescript.md)
+
+## Keep Reading
+
+- [What Is An npm Package?](/learn/packages/)
+- [Publishing A Package](/learn/packages/publish)

package/templates/vitepress/learn/packages/modern/package-entry-points.md

@@ -0,0 +1,46 @@
+# Package Entry Points
+
+The `exports` field is the public map of a package. It selects files for ESM, CommonJS, types, and intentional subpath imports while preventing consumers from coupling to internal folders.
+
+## Define one primary entry
+
+```json
+{
+  "name": "example-package",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  }
+}
+```
+
+Consumers can now use `import { feature } from 'example-package'` or `require('example-package')` without knowing your output layout.
+
+## Add a deliberate subpath
+
+```json
+{
+  "exports": {
+    ".": "./dist/index.js",
+    "./cli": "./dist/cli.js",
+    "./package.json": "./package.json"
+  }
+}
+```
+
+Each subpath is a public promise. Add one only when it has a stable purpose, documentation, and tests. Do not expose `./dist/*` as a shortcut around API design.
+
+## Verify consumers
+
+- Test the root import and every documented subpath.
+- Verify both ESM and CommonJS branches when both are published.
+- Check `npm pack --dry-run` includes every exported file.
+- Treat removing or changing a public subpath as a breaking change.
+
+## Keep Reading
+
+- [ESM vs CommonJS](./esm-vs-cjs.md)
+- [Type Declarations](./dts.md)

package/templates/vitepress/learn/packages/modern/typescript.md

@@ -0,0 +1,43 @@
+# TypeScript
+
+TypeScript gives a package one source language for implementation and public types. Build output should remain JavaScript plus declarations so consumers do not need your development compiler configuration.
+
+## Start with a strict package config
+
+```jsonc
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "declaration": true,
+    "declarationMap": true,
+    "outDir": "./dist",
+    "skipLibCheck": true
+  },
+  "include": ["src"]
+}
+```
+
+Use a separate configuration only when an output format genuinely needs different compiler behavior. Prefer a bundler configuration for output strategy and keep the TypeScript configuration focused on source checking and declaration generation.
+
+## Build and test from artifacts
+
+```bash
+pnpm build
+pnpm typecheck
+pnpm tsd
+```
+
+Run type tests against the generated package contract. A source-only test can pass while the published declaration path or exports map is broken.
+
+## Runtime execution
+
+For local scripts, `tsx` can run TypeScript without creating a development `dist` directory. That is convenient for tooling, but it is not a replacement for building libraries before testing the package that consumers install.
+
+## Keep Reading
+
+- [Type Declarations](./dts.md)
+- [Bundlers](./bundlers.md)
+- [Publishing A Package](/learn/packages/publish)

package/templates/vitepress/{why/index.md → learn/packages/modern-overview.md}

@@ -11,4 +11,4 @@ A modern package needs a deliberate module format, export map, declaration strat
 - [Bundlers](./modern/bundlers.md)
 - [TypeScript](./modern/typescript.md)
 
-Runnable evolution examples remain under `why/examples/` and are intentionally excluded from the generated AI documentation index.
+Runnable evolution examples remain under `learn/packages/examples/` and are intentionally excluded from the generated AI documentation index.

package/templates/vitepress/learn/packages/module-extensions.md

@@ -0,0 +1,34 @@
+# JavaScript, CommonJS, and ESM Files
+
+File extensions tell Node which module loader should read a file. Use them deliberately when a package publishes both module formats or when a script must work independently of the nearest `package.json`.
+
+## Extension rules
+
+| Extension | Module format                                         |
+| --------- | ----------------------------------------------------- |
+| `.mjs`    | ESM in every package                                  |
+| `.cjs`    | CommonJS in every package                             |
+| `.js`     | Determined by the nearest `package.json` `type` field |
+
+```json
+{
+  "type": "module"
+}
+```
+
+With this declaration, `.js` files are ESM. Use `.cjs` for CommonJS output such as a compatibility build or an older tooling configuration file.
+
+## Avoid ambiguous output
+
+```text
+dist/index.js     ESM output
+dist/index.cjs    CommonJS output
+dist/index.d.ts   Type declarations
+```
+
+Connect these files through `exports`; do not ask consumers to infer a `dist` layout. A clear output layout also makes package tarball checks easier.
+
+## Keep Reading
+
+- [ESM vs CommonJS](./modern/esm-vs-cjs.md)
+- [Package Entry Points](./modern/package-entry-points.md)

package/templates/vitepress/learn/packages/publish.md

@@ -0,0 +1,43 @@
+# Publishing A Package
+
+Publishing is the point where the repository's package contract becomes public. Build first, test the built artifacts, inspect the tarball, and publish only after the version intent and changelog describe the consumer-visible change.
+
+## Prepare the package
+
+```bash
+pnpm --filter example-package build
+pnpm --filter example-package typecheck
+pnpm --filter example-package test
+pnpm --filter example-package tsd
+pnpm --filter example-package pack --pack-destination ../../artifacts
+```
+
+Run the package commands against generated output where possible. A source-only test does not prove that `exports`, files, or declarations will resolve after installation.
+
+## Verify package metadata
+
+```json
+{
+  "name": "example-package",
+  "version": "1.0.0",
+  "files": ["dist", "README.md", "LICENSE"],
+  "publishConfig": { "access": "public" }
+}
+```
+
+Use `npm pack --dry-run` to see what users receive. Confirm the runtime entry point, declaration files, README, and license are present.
+
+## Release through the repository workflow
+
+```bash
+pnpm change
+pnpm version -r
+pnpm publish -r
+```
+
+The version ledger preserves why the release exists. Do not manually edit a package version to bypass fixed-group or changelog rules.
+
+## Keep Reading
+
+- [pnpm Versioning](/learn/tools/changeset.md)
+- [Modern Package Guide](./modern/)

package/templates/vitepress/learn/packages/reuse-javascript.md

@@ -0,0 +1,39 @@
+# Reusing JavaScript
+
+Reuse source code through an explicit package boundary. Copying files between applications is fast once and expensive every time the shared behavior changes; a local workspace package makes ownership, versioning, and tests visible.
+
+## Start with a workspace package
+
+```json
+{
+  "dependencies": {
+    "@example/shared": "workspace:*"
+  }
+}
+```
+
+The workspace protocol uses the local package during development and protects the repository from accidentally resolving an unrelated registry version.
+
+## Export a narrow API
+
+```ts
+export function normalizeName(value: string) {
+  return value.trim().toLowerCase()
+}
+```
+
+Keep the public entry point small. A shared package should expose behavior that has a real consumer, not a collection of unrelated helpers that happen to be nearby.
+
+## Choose the right reuse level
+
+| Need                         | Better boundary                        |
+| ---------------------------- | -------------------------------------- |
+| Shared runtime behavior      | A versioned package                    |
+| Shared build and lint policy | A preset package or managed asset      |
+| Shared application feature   | A feature package with clear ownership |
+| One-off project setup        | A template, not a dependency           |
+
+## Keep Reading
+
+- [What Is An npm Package?](/learn/packages/)
+- [Template Systems](/learn/monorepo/templates.md)

package/templates/vitepress/learn/packages/runtime-globals.md

@@ -0,0 +1,36 @@
+# JavaScript Runtime Keywords
+
+Modern JavaScript modules have different runtime globals depending on whether Node loads them as CommonJS or ESM. Know the boundary before copying code between build tools, scripts, and package entry points.
+
+## CommonJS values
+
+```js
+console.log(__filename)
+console.log(__dirname)
+console.log(require.main)
+```
+
+These values are available in CommonJS modules. They are not automatically present in ESM files.
+
+## ESM equivalents
+
+```js
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const filename = fileURLToPath(import.meta.url)
+const dirname = path.dirname(filename)
+```
+
+Use `import.meta.url` as the starting point for resolving files relative to an ESM module. Prefer explicit Node built-in imports such as `node:path` so bundlers and readers can identify runtime-only dependencies.
+
+## Keep code portable
+
+- Keep filesystem access behind a small module when browser builds share source code.
+- Do not use CommonJS globals in a package that declares `type: module`.
+- Test generated ESM and CommonJS outputs independently when both are published.
+
+## Keep Reading
+
+- [JavaScript, CommonJS, and ESM Files](/learn/packages/module-extensions)
+- [Reusing JavaScript](/learn/packages/reuse-javascript)

package/templates/vitepress/{repoctl/index.md → learn/repoctl-model.md}

@@ -64,11 +64,11 @@ 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)
+- [Install and initialize](/start/install)
+- [Task index](/tasks/)
+- [Command Reference](/reference/commands)
+- [Configuration](/reference/config)
+- [Templates](/reference/templates)
+- [Add checks to CI](/tasks/ci)
+- [Troubleshoot](/tasks/troubleshooting)
+- [Command Aliases](/reference/aliases)

package/templates/vitepress/learn/tools/changeset.md

@@ -0,0 +1,30 @@
+# pnpm Versioning
+
+repoctl uses pnpm's native versioning workflow. A change intent records why a publishable package needs a release, and the repository ledger keeps that intent with the source change.
+
+## Record release intent
+
+```bash
+pnpm change
+pnpm version -r
+pnpm publish -r
+```
+
+Choose the smallest version bump that matches the public contract. Removing a managed asset from a published template package is a minor change because consumers no longer receive that asset. Metadata-only URL changes are patch changes.
+
+## Fixed packages
+
+Some packages version together because they share a public contract. The versioning configuration defines those groups; do not manually align versions in package manifests.
+
+## Before publishing
+
+1. Build the affected packages.
+2. Run lint and typecheck.
+3. Run unit, integration, and end-to-end tests where available.
+4. Confirm the generated changelog and package contents match the intent.
+
+## Keep Reading
+
+- [Publishing and Changelogs](/learn/monorepo/publish.md)
+- [Add checks to CI](/tasks/ci)
+- [Template Assets](/reference/template-assets)