aico-cli 2.1.7 → 2.1.23

package/templates/skills/pnpm/references/core-workspaces.md

@@ -0,0 +1,205 @@
+---
+name: pnpm-workspaces
+description: Monorepo support with workspaces for managing multiple packages
+---
+
+# pnpm Workspaces
+
+pnpm has built-in support for monorepos (multi-package repositories) through workspaces.
+
+## Setting Up Workspaces
+
+Create `pnpm-workspace.yaml` at the repository root:
+
+```yaml
+packages:
+  # Include all packages in packages/ directory
+  - 'packages/*'
+  # Include all apps
+  - 'apps/*'
+  # Include nested packages
+  - 'tools/*/packages/*'
+  # Exclude test directories
+  - '!**/test/**'
+```
+
+## Workspace Protocol
+
+Use `workspace:` protocol to reference local packages:
+
+```json
+{
+  "dependencies": {
+    "@myorg/utils": "workspace:*",
+    "@myorg/core": "workspace:^",
+    "@myorg/types": "workspace:~"
+  }
+}
+```
+
+### Protocol Variants
+
+| Protocol | Behavior | Published As |
+|----------|----------|--------------|
+| `workspace:*` | Any version | Actual version (e.g., `1.2.3`) |
+| `workspace:^` | Compatible version | `^1.2.3` |
+| `workspace:~` | Patch version | `~1.2.3` |
+| `workspace:^1.0.0` | Semver range | `^1.0.0` |
+
+## Filtering Packages
+
+Run commands on specific packages using `--filter`:
+
+```bash
+# By package name
+pnpm --filter @myorg/app build
+pnpm -F @myorg/app build
+
+# By directory path
+pnpm --filter "./packages/core" test
+
+# Glob patterns
+pnpm --filter "@myorg/*" lint
+pnpm --filter "!@myorg/internal-*" publish
+
+# All packages
+pnpm -r build
+pnpm --recursive build
+```
+
+### Dependency-based Filtering
+
+```bash
+# Package and all its dependencies
+pnpm --filter "...@myorg/app" build
+
+# Package and all its dependents
+pnpm --filter "@myorg/core..." test
+
+# Both directions
+pnpm --filter "...@myorg/shared..." build
+
+# Changed since git ref
+pnpm --filter "...[origin/main]" test
+pnpm --filter "[HEAD~5]" lint
+```
+
+## Workspace Commands
+
+### Install dependencies
+```bash
+# Install all workspace packages
+pnpm install
+
+# Add dependency to specific package
+pnpm --filter @myorg/app add lodash
+
+# Add workspace dependency
+pnpm --filter @myorg/app add @myorg/utils
+```
+
+### Run scripts
+```bash
+# Run in all packages with that script
+pnpm -r run build
+
+# Run in topological order (dependencies first)
+pnpm -r --workspace-concurrency=1 run build
+
+# Run in parallel
+pnpm -r --parallel run test
+
+# Stream output
+pnpm -r --stream run dev
+```
+
+### Execute commands
+```bash
+# Run command in all packages
+pnpm -r exec pwd
+
+# Run in specific packages
+pnpm --filter "./packages/**" exec rm -rf dist
+```
+
+## Workspace Settings
+
+Configure in `.npmrc` or `pnpm-workspace.yaml`:
+
+```ini
+# Link workspace packages automatically
+link-workspace-packages=true
+
+# Prefer workspace packages over registry
+prefer-workspace-packages=true
+
+# Single lockfile (recommended)
+shared-workspace-lockfile=true
+
+# Workspace protocol handling
+save-workspace-protocol=rolling
+
+# Concurrent workspace scripts
+workspace-concurrency=4
+```
+
+## Publishing Workspaces
+
+When publishing, `workspace:` protocols are converted:
+
+```json
+// Before publish
+{
+  "dependencies": {
+    "@myorg/utils": "workspace:^"
+  }
+}
+
+// After publish
+{
+  "dependencies": {
+    "@myorg/utils": "^1.2.3"
+  }
+}
+```
+
+Use `--no-git-checks` for publishing from CI:
+```bash
+pnpm publish -r --no-git-checks
+```
+
+## Best Practices
+
+1. **Use workspace protocol** for internal dependencies
+2. **Enable `link-workspace-packages`** for automatic linking
+3. **Use shared lockfile** for consistency
+4. **Filter by dependencies** when building to ensure correct order
+5. **Use catalogs** for shared external dependency versions
+
+## Example Project Structure
+
+```
+my-monorepo/
+├── pnpm-workspace.yaml
+├── package.json
+├── pnpm-lock.yaml
+├── packages/
+│   ├── core/
+│   │   └── package.json
+│   ├── utils/
+│   │   └── package.json
+│   └── types/
+│       └── package.json
+└── apps/
+    ├── web/
+    │   └── package.json
+    └── api/
+        └── package.json
+```
+
+<!-- 
+Source references:
+- https://pnpm.io/workspaces
+- https://pnpm.io/filtering
+- https://pnpm.io/npmrc#workspace-settings
+-->

package/templates/skills/pnpm/references/features-aliases.md

@@ -0,0 +1,168 @@
+---
+name: pnpm-aliases
+description: Install packages under custom names for versioning, forks, or alternatives
+---
+
+# pnpm Aliases
+
+pnpm supports package aliases using the `npm:` protocol. This lets you install packages under different names, use multiple versions of the same package, or substitute packages.
+
+## Basic Syntax
+
+```bash
+pnpm add <alias>@npm:<package>@<version>
+```
+
+In `package.json`:
+```json
+{
+  "dependencies": {
+    "<alias>": "npm:<package>@<version>"
+  }
+}
+```
+
+## Use Cases
+
+### Multiple Versions of Same Package
+
+Install different versions side by side:
+
+```json
+{
+  "dependencies": {
+    "lodash3": "npm:lodash@3",
+    "lodash4": "npm:lodash@4"
+  }
+}
+```
+
+Usage:
+```js
+import lodash3 from 'lodash3'
+import lodash4 from 'lodash4'
+```
+
+### Replace Package with Fork
+
+Substitute a package with a fork or alternative:
+
+```json
+{
+  "dependencies": {
+    "original-pkg": "npm:my-fork@^1.0.0"
+  }
+}
+```
+
+All imports of `original-pkg` will resolve to `my-fork`.
+
+### Replace Deprecated Package
+
+```json
+{
+  "dependencies": {
+    "request": "npm:@cypress/request@^3.0.0"
+  }
+}
+```
+
+### Scoped to Unscoped (or vice versa)
+
+```json
+{
+  "dependencies": {
+    "vue": "npm:@anthropic/vue@^3.0.0",
+    "@myorg/utils": "npm:lodash@^4.17.21"
+  }
+}
+```
+
+## CLI Usage
+
+### Add with alias
+
+```bash
+# Add lodash under alias
+pnpm add lodash4@npm:lodash@4
+
+# Add fork as original name
+pnpm add request@npm:@cypress/request
+```
+
+### Add multiple versions
+
+```bash
+pnpm add react17@npm:react@17 react18@npm:react@18
+```
+
+## With TypeScript
+
+For type resolution with aliases, you may need to configure TypeScript:
+
+```json
+// tsconfig.json
+{
+  "compilerOptions": {
+    "paths": {
+      "lodash3": ["node_modules/lodash3"],
+      "lodash4": ["node_modules/lodash4"]
+    }
+  }
+}
+```
+
+Or use `@types` packages with aliases:
+
+```json
+{
+  "devDependencies": {
+    "@types/lodash3": "npm:@types/lodash@3",
+    "@types/lodash4": "npm:@types/lodash@4"
+  }
+}
+```
+
+## Combined with Overrides
+
+Force all transitive dependencies to use an alias:
+
+```yaml
+# pnpm-workspace.yaml
+overrides:
+  "underscore": "npm:lodash@^4.17.21"
+```
+
+This replaces all `underscore` imports (including in dependencies) with lodash.
+
+## Git and Local Aliases
+
+Aliases work with any valid pnpm specifier:
+
+```json
+{
+  "dependencies": {
+    "my-fork": "npm:user/repo#commit",
+    "local-pkg": "file:../local-package"
+  }
+}
+```
+
+## Best Practices
+
+1. **Clear naming**: Use descriptive alias names that indicate purpose
+   ```json
+   "lodash-legacy": "npm:lodash@3"
+   "lodash-modern": "npm:lodash@4"
+   ```
+
+2. **Document aliases**: Add comments or documentation explaining why aliases exist
+
+3. **Prefer overrides for global replacement**: If you want to replace a package everywhere, use overrides instead of aliases
+
+4. **Test thoroughly**: Aliased packages may have subtle differences in behavior
+
+<!-- 
+Source references:
+- https://pnpm.io/aliases
+-->

package/templates/skills/pnpm/references/features-catalogs.md

@@ -0,0 +1,159 @@
+---
+name: pnpm-catalogs
+description: Centralized dependency version management for workspaces
+---
+
+# pnpm Catalogs
+
+Catalogs provide a centralized way to manage dependency versions across a workspace. Define versions once, use everywhere.
+
+## Basic Usage
+
+Define a catalog in `pnpm-workspace.yaml`:
+
+```yaml
+packages:
+  - 'packages/*'
+
+catalog:
+  react: ^18.2.0
+  react-dom: ^18.2.0
+  typescript: ~5.3.0
+  vite: ^5.0.0
+```
+
+Reference in `package.json` with `catalog:`:
+
+```json
+{
+  "dependencies": {
+    "react": "catalog:",
+    "react-dom": "catalog:"
+  },
+  "devDependencies": {
+    "typescript": "catalog:",
+    "vite": "catalog:"
+  }
+}
+```
+
+## Named Catalogs
+
+Create multiple catalogs for different scenarios:
+
+```yaml
+packages:
+  - 'packages/*'
+
+# Default catalog
+catalog:
+  lodash: ^4.17.21
+
+# Named catalogs
+catalogs:
+  react17:
+    react: ^17.0.2
+    react-dom: ^17.0.2
+  
+  react18:
+    react: ^18.2.0
+    react-dom: ^18.2.0
+  
+  testing:
+    vitest: ^1.0.0
+    "@testing-library/react": ^14.0.0
+```
+
+Reference named catalogs:
+
+```json
+{
+  "dependencies": {
+    "react": "catalog:react18",
+    "react-dom": "catalog:react18"
+  },
+  "devDependencies": {
+    "vitest": "catalog:testing"
+  }
+}
+```
+
+## Benefits
+
+1. **Single source of truth**: Update version in one place
+2. **Consistency**: All packages use the same version
+3. **Easy upgrades**: Change version once, affects entire workspace
+4. **Type-safe**: TypeScript support in pnpm-workspace.yaml
+
+## Catalog vs Overrides
+
+| Feature | Catalogs | Overrides |
+|---------|----------|-----------|
+| Purpose | Define versions for direct dependencies | Force versions for any dependency |
+| Scope | Direct dependencies only | All dependencies (including transitive) |
+| Usage | `"pkg": "catalog:"` | Applied automatically |
+| Opt-in | Explicit per package.json | Global to workspace |
+
+## Publishing with Catalogs
+
+When publishing, `catalog:` references are replaced with actual versions:
+
+```json
+// Before publish (source)
+{
+  "dependencies": {
+    "react": "catalog:"
+  }
+}
+
+// After publish (published package)
+{
+  "dependencies": {
+    "react": "^18.2.0"
+  }
+}
+```
+
+## Migration from Overrides
+
+If you're using overrides for version consistency:
+
+```yaml
+# Before (using overrides)
+overrides:
+  react: ^18.2.0
+  react-dom: ^18.2.0
+```
+
+Migrate to catalogs for cleaner dependency management:
+
+```yaml
+# After (using catalogs)
+catalog:
+  react: ^18.2.0
+  react-dom: ^18.2.0
+```
+
+Then update package.json files to use `catalog:`.
+
+## Best Practices
+
+1. **Use default catalog** for commonly shared dependencies
+2. **Use named catalogs** for version variants (e.g., different React versions)
+3. **Keep catalog minimal** - only include shared dependencies
+4. **Combine with workspace protocol** for internal packages
+
+```yaml
+catalog:
+  # External shared dependencies
+  lodash: ^4.17.21
+  zod: ^3.22.0
+
+# Internal packages use workspace: protocol instead
+# "dependencies": { "@myorg/utils": "workspace:^" }
+```
+
+<!-- 
+Source references:
+- https://pnpm.io/catalogs
+-->