aico-cli 2.1.7 → 2.1.23

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

@@ -0,0 +1,229 @@
+---
+name: pnpm-cli-commands
+description: Essential pnpm commands for package management, running scripts, and workspace operations
+---
+
+# pnpm CLI Commands
+
+pnpm provides a comprehensive CLI for package management with commands similar to npm/yarn but with unique features.
+
+## Installation Commands
+
+### Install all dependencies
+```bash
+pnpm install
+# or
+pnpm i
+```
+
+### Add a dependency
+```bash
+# Production dependency
+pnpm add <pkg>
+
+# Dev dependency
+pnpm add -D <pkg>
+pnpm add --save-dev <pkg>
+
+# Optional dependency
+pnpm add -O <pkg>
+
+# Global package
+pnpm add -g <pkg>
+
+# Specific version
+pnpm add <pkg>@<version>
+pnpm add <pkg>@next
+pnpm add <pkg>@^1.0.0
+```
+
+### Remove a dependency
+```bash
+pnpm remove <pkg>
+pnpm rm <pkg>
+pnpm uninstall <pkg>
+pnpm un <pkg>
+```
+
+### Update dependencies
+```bash
+# Update all
+pnpm update
+pnpm up
+
+# Update specific package
+pnpm update <pkg>
+
+# Update to latest (ignore semver)
+pnpm update --latest
+pnpm up -L
+
+# Interactive update
+pnpm update --interactive
+pnpm up -i
+```
+
+## Script Commands
+
+### Run scripts
+```bash
+pnpm run <script>
+# or shorthand
+pnpm <script>
+
+# Pass arguments to script
+pnpm run build -- --watch
+
+# Run script if exists (no error if missing)
+pnpm run --if-present build
+```
+
+### Execute binaries
+```bash
+# Run local binary
+pnpm exec <command>
+
+# Example
+pnpm exec eslint .
+```
+
+### dlx - Run without installing
+```bash
+# Like npx but for pnpm
+pnpm dlx <pkg>
+
+# Examples
+pnpm dlx create-vite my-app
+pnpm dlx degit user/repo my-project
+```
+
+## Workspace Commands
+
+### Run in all packages
+```bash
+# Run script in all workspace packages
+pnpm -r run <script>
+pnpm --recursive run <script>
+
+# Run in specific packages
+pnpm --filter <pattern> run <script>
+
+# Examples
+pnpm --filter "./packages/**" run build
+pnpm --filter "!./packages/internal/**" run test
+pnpm --filter "@myorg/*" run lint
+```
+
+### Filter patterns
+```bash
+# By package name
+pnpm --filter <pkg-name> <command>
+pnpm --filter "@scope/pkg" build
+
+# By directory
+pnpm --filter "./packages/core" test
+
+# Dependencies of a package
+pnpm --filter "...@scope/app" build
+
+# Dependents of a package
+pnpm --filter "@scope/core..." test
+
+# Changed packages since commit/branch
+pnpm --filter "...[origin/main]" build
+```
+
+## Other Useful Commands
+
+### Link packages
+```bash
+# Link global package
+pnpm link --global
+pnpm link -g
+
+# Use linked package
+pnpm link --global <pkg>
+```
+
+### Patch packages
+```bash
+# Create patch for a package
+pnpm patch <pkg>@<version>
+
+# After editing, commit the patch
+pnpm patch-commit <path>
+
+# Remove a patch
+pnpm patch-remove <pkg>
+```
+
+### Store management
+```bash
+# Show store path
+pnpm store path
+
+# Remove unreferenced packages
+pnpm store prune
+
+# Check store integrity
+pnpm store status
+```
+
+### Other commands
+```bash
+# Clean install (like npm ci)
+pnpm install --frozen-lockfile
+
+# List installed packages
+pnpm list
+pnpm ls
+
+# Why is package installed?
+pnpm why <pkg>
+
+# Outdated packages
+pnpm outdated
+
+# Audit for vulnerabilities
+pnpm audit
+
+# Rebuild native modules
+pnpm rebuild
+
+# Import from npm/yarn lockfile
+pnpm import
+
+# Create tarball
+pnpm pack
+
+# Publish package
+pnpm publish
+```
+
+## Useful Flags
+
+```bash
+# Ignore scripts
+pnpm install --ignore-scripts
+
+# Prefer offline (use cache)
+pnpm install --prefer-offline
+
+# Strict peer dependencies
+pnpm install --strict-peer-dependencies
+
+# Production only
+pnpm install --prod
+pnpm install -P
+
+# No optional dependencies
+pnpm install --no-optional
+```
+
+<!-- 
+Source references:
+- https://pnpm.io/cli/install
+- https://pnpm.io/cli/add
+- https://pnpm.io/cli/run
+- https://pnpm.io/filtering
+-->

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

@@ -0,0 +1,188 @@
+---
+name: pnpm-configuration
+description: Configuration options via pnpm-workspace.yaml and .npmrc settings
+---
+
+# pnpm Configuration
+
+pnpm uses two main configuration files: `pnpm-workspace.yaml` for workspace and pnpm-specific settings, and `.npmrc` for npm-compatible and pnpm-specific settings.
+
+## pnpm-workspace.yaml
+
+The recommended location for pnpm-specific configurations. Place at project root.
+
+```yaml
+# Define workspace packages
+packages:
+  - 'packages/*'
+  - 'apps/*'
+  - '!**/test/**'  # Exclude pattern
+
+# Catalog for shared dependency versions
+catalog:
+  react: ^18.2.0
+  typescript: ~5.3.0
+
+# Named catalogs for different dependency groups
+catalogs:
+  react17:
+    react: ^17.0.2
+    react-dom: ^17.0.2
+  react18:
+    react: ^18.2.0
+    react-dom: ^18.2.0
+
+# Override resolutions (preferred location)
+overrides:
+  lodash: ^4.17.21
+  'foo@^1.0.0>bar': ^2.0.0
+
+# pnpm settings (alternative to .npmrc)
+settings:
+  auto-install-peers: true
+  strict-peer-dependencies: false
+  link-workspace-packages: true
+  prefer-workspace-packages: true
+  shared-workspace-lockfile: true
+```
+
+## .npmrc Settings
+
+pnpm reads settings from `.npmrc` files. Create at project root or user home.
+
+### Common pnpm Settings
+
+```ini
+# Automatically install peer dependencies
+auto-install-peers=true
+
+# Fail on peer dependency issues
+strict-peer-dependencies=false
+
+# Hoist patterns for dependencies
+public-hoist-pattern[]=*types*
+public-hoist-pattern[]=*eslint*
+shamefully-hoist=false
+
+# Store location
+store-dir=~/.pnpm-store
+
+# Virtual store location  
+virtual-store-dir=node_modules/.pnpm
+
+# Lockfile settings
+lockfile=true
+prefer-frozen-lockfile=true
+
+# Side effects cache (speeds up rebuilds)
+side-effects-cache=true
+
+# Registry settings
+registry=https://registry.npmjs.org/
+@myorg:registry=https://npm.myorg.com/
+```
+
+### Workspace Settings
+
+```ini
+# Link workspace packages
+link-workspace-packages=true
+
+# Prefer workspace packages over registry
+prefer-workspace-packages=true
+
+# Single lockfile for all packages
+shared-workspace-lockfile=true
+
+# Save prefix for workspace dependencies
+save-workspace-protocol=rolling
+```
+
+### Node.js Settings
+
+```ini
+# Use specific Node.js version
+use-node-version=20.10.0
+
+# Node.js version file
+node-version-file=.nvmrc
+
+# Manage Node.js versions
+manage-package-manager-versions=true
+```
+
+### Security Settings
+
+```ini
+# Ignore specific scripts
+ignore-scripts=false
+
+# Allow specific build scripts
+onlyBuiltDependencies[]=esbuild
+onlyBuiltDependencies[]=sharp
+
+# Package extensions for missing peer deps
+package-extensions[foo@1].peerDependencies.bar=*
+```
+
+## Configuration Hierarchy
+
+Settings are read in order (later overrides earlier):
+
+1. `/etc/npmrc` - Global config
+2. `~/.npmrc` - User config  
+3. `<project>/.npmrc` - Project config
+4. Environment variables: `npm_config_<key>=<value>`
+5. `pnpm-workspace.yaml` settings field
+
+## Environment Variables
+
+```bash
+# Set config via env
+npm_config_registry=https://registry.npmjs.org/
+
+# pnpm-specific env vars
+PNPM_HOME=~/.local/share/pnpm
+```
+
+## Package.json Fields
+
+pnpm reads specific fields from `package.json`:
+
+```json
+{
+  "pnpm": {
+    "overrides": {
+      "lodash": "^4.17.21"
+    },
+    "peerDependencyRules": {
+      "ignoreMissing": ["@babel/*"],
+      "allowedVersions": {
+        "react": "17 || 18"
+      }
+    },
+    "neverBuiltDependencies": ["fsevents"],
+    "onlyBuiltDependencies": ["esbuild"],
+    "allowedDeprecatedVersions": {
+      "request": "*"
+    },
+    "patchedDependencies": {
+      "express@4.18.2": "patches/express@4.18.2.patch"
+    }
+  }
+}
+```
+
+## Key Differences from npm/yarn
+
+1. **Strict by default**: No phantom dependencies
+2. **Workspace protocol**: `workspace:*` for local packages
+3. **Catalogs**: Centralized version management
+4. **Content-addressable store**: Shared across projects
+
+<!-- 
+Source references:
+- https://pnpm.io/pnpm-workspace_yaml
+- https://pnpm.io/npmrc
+- https://pnpm.io/package_json
+-->

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

@@ -0,0 +1,179 @@
+---
+name: pnpm-store
+description: Content-addressable storage system that makes pnpm fast and disk-efficient
+---
+
+# pnpm Store
+
+pnpm uses a content-addressable store to save disk space and speed up installations. All packages are stored once globally and hard-linked to project `node_modules`.
+
+## How It Works
+
+1. **Global Store**: Packages are downloaded once to a central store
+2. **Hard Links**: Projects link to store instead of copying files
+3. **Content-Addressable**: Files are stored by content hash, deduplicating identical files
+
+### Storage Layout
+
+```
+~/.pnpm-store/              # Global store (default location)
+└── v3/
+    └── files/
+        └── <hash>/         # Files stored by content hash
+
+project/
+└── node_modules/
+    ├── .pnpm/              # Virtual store (hard links to global store)
+    │   ├── lodash@4.17.21/
+    │   │   └── node_modules/
+    │   │       └── lodash/
+    │   └── express@4.18.2/
+    │       └── node_modules/
+    │           ├── express/
+    │           └── <deps>/  # Flat structure for dependencies
+    ├── lodash -> .pnpm/lodash@4.17.21/node_modules/lodash
+    └── express -> .pnpm/express@4.18.2/node_modules/express
+```
+
+## Store Commands
+
+```bash
+# Show store location
+pnpm store path
+
+# Remove unreferenced packages
+pnpm store prune
+
+# Check store integrity
+pnpm store status
+
+# Add package to store without installing
+pnpm store add <pkg>
+```
+
+## Configuration
+
+### Store Location
+
+```ini
+# .npmrc
+store-dir=~/.pnpm-store
+
+# Or use environment variable
+PNPM_HOME=~/.local/share/pnpm
+```
+
+### Virtual Store
+
+The virtual store (`.pnpm` in `node_modules`) contains symlinks to the global store:
+
+```ini
+# Customize virtual store location
+virtual-store-dir=node_modules/.pnpm
+
+# Alternative flat layout
+node-linker=hoisted
+```
+
+## Disk Space Benefits
+
+pnpm saves significant disk space:
+
+- **Deduplication**: Same package version stored once across all projects
+- **Content deduplication**: Identical files across different packages stored once
+- **Hard links**: No copying, just linking
+
+### Check disk usage
+
+```bash
+# Compare actual vs apparent size
+du -sh node_modules        # Apparent size
+du -sh --apparent-size node_modules  # With hard links counted
+```
+
+## Node Linker Modes
+
+Configure how `node_modules` is structured:
+
+```ini
+# Default: Symlinked structure (recommended)
+node-linker=isolated
+
+# Flat node_modules (npm-like, for compatibility)
+node-linker=hoisted
+
+# PnP mode (experimental, like Yarn PnP)
+node-linker=pnp
+```
+
+### Isolated Mode (Default)
+
+- Strict dependency resolution
+- No phantom dependencies
+- Packages can only access declared dependencies
+
+### Hoisted Mode
+
+- Flat `node_modules` like npm
+- For compatibility with tools that don't support symlinks
+- Loses strictness benefits
+
+## Side Effects Cache
+
+Cache build outputs for native modules:
+
+```ini
+# Enable side effects caching
+side-effects-cache=true
+
+# Store side effects in project (instead of global store)
+side-effects-cache-readonly=true
+```
+
+## Shared Store Across Machines
+
+For CI/CD, you can share the store:
+
+```yaml
+# GitHub Actions example
+- uses: pnpm/action-setup@v4
+  with:
+    run_install: false
+
+- name: Get pnpm store directory
+  shell: bash
+  run: echo "STORE_PATH=$(pnpm store path --silent)" >> $GITHUB_ENV
+
+- uses: actions/cache@v4
+  with:
+    path: ${{ env.STORE_PATH }}
+    key: ${{ runner.os }}-pnpm-store-${{ hashFiles('**/pnpm-lock.yaml') }}
+```
+
+## Troubleshooting
+
+### Store corruption
+```bash
+# Verify and fix store
+pnpm store status
+pnpm store prune
+```
+
+### Hard link issues (network drives, Docker)
+```ini
+# Use copying instead of hard links
+package-import-method=copy
+```
+
+### Permission issues
+```bash
+# Fix store permissions
+chmod -R u+w ~/.pnpm-store
+```
+
+<!-- 
+Source references:
+- https://pnpm.io/symlinked-node-modules-structure
+- https://pnpm.io/cli/store
+- https://pnpm.io/npmrc#store-dir
+-->