ads-fe 0.0.1

package/skills/pnpm/references/features-hooks.md

@@ -0,0 +1,233 @@
+---
+name: pnpm-hooks
+description: Customize package resolution and dependency behavior with pnpmfile hooks
+---
+
+# pnpm Hooks
+
+pnpm provides hooks via `.pnpmfile.cjs` to customize how packages are resolved and their metadata is processed.
+
+## Setup
+
+Create `.pnpmfile.cjs` at workspace root:
+
+```js
+// .pnpmfile.cjs
+function readPackage(pkg, context) {
+  // Modify package metadata
+  return pkg
+}
+
+function afterAllResolved(lockfile, context) {
+  // Modify lockfile
+  return lockfile
+}
+
+module.exports = {
+  hooks: {
+    readPackage,
+    afterAllResolved
+  }
+}
+```
+
+## readPackage Hook
+
+Called for every package before resolution. Use to modify dependencies, add missing peer deps, or fix broken packages.
+
+### Add Missing Peer Dependency
+
+```js
+function readPackage(pkg, context) {
+  if (pkg.name === 'some-broken-package') {
+    pkg.peerDependencies = {
+      ...pkg.peerDependencies,
+      react: '*'
+    }
+    context.log(`Added react peer dep to ${pkg.name}`)
+  }
+  return pkg
+}
+```
+
+### Override Dependency Version
+
+```js
+function readPackage(pkg, context) {
+  // Fix all lodash versions
+  if (pkg.dependencies?.lodash) {
+    pkg.dependencies.lodash = '^4.17.21'
+  }
+  if (pkg.devDependencies?.lodash) {
+    pkg.devDependencies.lodash = '^4.17.21'
+  }
+  return pkg
+}
+```
+
+### Remove Unwanted Dependency
+
+```js
+function readPackage(pkg, context) {
+  // Remove optional dependency that causes issues
+  if (pkg.optionalDependencies?.fsevents) {
+    delete pkg.optionalDependencies.fsevents
+  }
+  return pkg
+}
+```
+
+### Replace Package
+
+```js
+function readPackage(pkg, context) {
+  // Replace deprecated package
+  if (pkg.dependencies?.['old-package']) {
+    pkg.dependencies['new-package'] = pkg.dependencies['old-package']
+    delete pkg.dependencies['old-package']
+  }
+  return pkg
+}
+```
+
+### Fix Broken Package
+
+```js
+function readPackage(pkg, context) {
+  // Fix incorrect exports field
+  if (pkg.name === 'broken-esm-package') {
+    pkg.exports = {
+      '.': {
+        import: './dist/index.mjs',
+        require: './dist/index.cjs'
+      }
+    }
+  }
+  return pkg
+}
+```
+
+## afterAllResolved Hook
+
+Called after the lockfile is generated. Use for post-resolution modifications.
+
+```js
+function afterAllResolved(lockfile, context) {
+  // Log all resolved packages
+  context.log(`Resolved ${Object.keys(lockfile.packages || {}).length} packages`)
+  
+  // Modify lockfile if needed
+  return lockfile
+}
+```
+
+## Context Object
+
+The `context` object provides utilities:
+
+```js
+function readPackage(pkg, context) {
+  // Log messages
+  context.log('Processing package...')
+  
+  return pkg
+}
+```
+
+## Use with TypeScript
+
+For type hints, use JSDoc:
+
+```js
+// .pnpmfile.cjs
+
+/**
+ * @param {import('type-fest').PackageJson} pkg
+ * @param {{ log: (msg: string) => void }} context
+ * @returns {import('type-fest').PackageJson}
+ */
+function readPackage(pkg, context) {
+  return pkg
+}
+
+module.exports = {
+  hooks: {
+    readPackage
+  }
+}
+```
+
+## Common Patterns
+
+### Conditional by Package Name
+
+```js
+function readPackage(pkg, context) {
+  switch (pkg.name) {
+    case 'package-a':
+      pkg.dependencies.foo = '^2.0.0'
+      break
+    case 'package-b':
+      delete pkg.optionalDependencies.bar
+      break
+  }
+  return pkg
+}
+```
+
+### Apply to All Packages
+
+```js
+function readPackage(pkg, context) {
+  // Remove all optional fsevents
+  if (pkg.optionalDependencies) {
+    delete pkg.optionalDependencies.fsevents
+  }
+  return pkg
+}
+```
+
+### Debug Resolution
+
+```js
+function readPackage(pkg, context) {
+  if (process.env.DEBUG_PNPM) {
+    context.log(`${pkg.name}@${pkg.version}`)
+    context.log(`  deps: ${Object.keys(pkg.dependencies || {}).join(', ')}`)
+  }
+  return pkg
+}
+```
+
+## Hooks vs Overrides
+
+| Feature | Hooks (.pnpmfile.cjs) | Overrides |
+|---------|----------------------|-----------|
+| Complexity | Can use JavaScript logic | Declarative only |
+| Scope | Any package metadata | Version only |
+| Use case | Complex fixes, conditional logic | Simple version pins |
+
+**Prefer overrides** for simple version fixes. **Use hooks** when you need:
+- Conditional logic
+- Non-version modifications (exports, peer deps)
+- Logging/debugging
+
+## Troubleshooting
+
+### Hook not running
+
+1. Ensure file is named `.pnpmfile.cjs` (not `.js`)
+2. Check file is at workspace root
+3. Run `pnpm install` to trigger hooks
+
+### Debug hooks
+
+```bash
+# See hook logs
+pnpm install --reporter=append-only
+```
+
+<!-- 
+Source references:
+- https://pnpm.io/pnpmfile
+-->

package/skills/pnpm/references/features-overrides.md

@@ -0,0 +1,184 @@
+---
+name: pnpm-overrides
+description: Force specific versions of dependencies including transitive dependencies
+---
+
+# pnpm Overrides
+
+Overrides let you force specific versions of packages, including transitive dependencies. Useful for fixing security vulnerabilities or compatibility issues.
+
+## Basic Syntax
+
+Define overrides in `pnpm-workspace.yaml` (recommended) or `package.json`:
+
+### In pnpm-workspace.yaml (Recommended)
+
+```yaml
+packages:
+  - 'packages/*'
+
+overrides:
+  # Override all versions of a package
+  lodash: ^4.17.21
+  
+  # Override specific version range
+  "foo@^1.0.0": ^1.2.3
+  
+  # Override nested dependency
+  "express>cookie": ^0.6.0
+  
+  # Override to different package
+  "underscore": "npm:lodash@^4.17.21"
+```
+
+### In package.json
+
+```json
+{
+  "pnpm": {
+    "overrides": {
+      "lodash": "^4.17.21",
+      "foo@^1.0.0": "^1.2.3",
+      "bar@^2.0.0>qux": "^1.0.0"
+    }
+  }
+}
+```
+
+## Override Patterns
+
+### Override all instances
+```yaml
+overrides:
+  lodash: ^4.17.21
+```
+Forces all lodash installations to use ^4.17.21.
+
+### Override specific parent version
+```yaml
+overrides:
+  "foo@^1.0.0": ^1.2.3
+```
+Only override foo when the requested version matches ^1.0.0.
+
+### Override nested dependency
+```yaml
+overrides:
+  "express>cookie": ^0.6.0
+  "foo@1.x>bar@^2.0.0>qux": ^1.0.0
+```
+Override cookie only when it's a dependency of express.
+
+### Replace with different package
+```yaml
+overrides:
+  # Replace underscore with lodash
+  "underscore": "npm:lodash@^4.17.21"
+  
+  # Use local file
+  "some-pkg": "file:./local-pkg"
+  
+  # Use git
+  "some-pkg": "github:user/repo#commit"
+```
+
+### Remove a dependency
+```yaml
+overrides:
+  "unwanted-pkg": "-"
+```
+The `-` removes the package entirely.
+
+## Common Use Cases
+
+### Security Fix
+
+Force patched version of vulnerable package:
+
+```yaml
+overrides:
+  # Fix CVE in transitive dependency
+  "minimist": "^1.2.6"
+  "json5": "^2.2.3"
+```
+
+### Deduplicate Dependencies
+
+Force single version when multiple are installed:
+
+```yaml
+overrides:
+  "react": "^18.2.0"
+  "react-dom": "^18.2.0"
+```
+
+### Fix Peer Dependency Issues
+
+```yaml
+overrides:
+  "@types/react": "^18.2.0"
+```
+
+### Replace Deprecated Package
+
+```yaml
+overrides:
+  "request": "npm:@cypress/request@^3.0.0"
+```
+
+## Hooks Alternative
+
+For more complex scenarios, use `.pnpmfile.cjs`:
+
+```js
+// .pnpmfile.cjs
+function readPackage(pkg, context) {
+  // Override dependency version
+  if (pkg.dependencies?.lodash) {
+    pkg.dependencies.lodash = '^4.17.21'
+  }
+  
+  // Add missing peer dependency
+  if (pkg.name === 'some-package') {
+    pkg.peerDependencies = {
+      ...pkg.peerDependencies,
+      react: '*'
+    }
+  }
+  
+  return pkg
+}
+
+module.exports = {
+  hooks: {
+    readPackage
+  }
+}
+```
+
+## Overrides vs Catalogs
+
+| Feature | Overrides | Catalogs |
+|---------|-----------|----------|
+| Affects | All dependencies (including transitive) | Direct dependencies only |
+| Usage | Automatic | Explicit `catalog:` reference |
+| Purpose | Force versions, fix issues | Version management |
+| Granularity | Can target specific parents | Package-wide only |
+
+## Debugging
+
+Check which version is resolved:
+
+```bash
+# See resolved versions
+pnpm why lodash
+
+# List all versions
+pnpm list lodash --depth=Infinity
+```
+
+<!-- 
+Source references:
+- https://pnpm.io/package_json#pnpmoverrides
+- https://pnpm.io/pnpmfile
+-->

package/skills/pnpm/references/features-patches.md

@@ -0,0 +1,201 @@
+---
+name: pnpm-patches
+description: Patch third-party packages directly with customized fixes
+---
+
+# pnpm Patches
+
+pnpm's patching feature lets you modify third-party packages directly. Useful for applying fixes before upstream releases or customizing package behavior.
+
+## Creating a Patch
+
+### Step 1: Initialize Patch
+
+```bash
+pnpm patch <pkg>@<version>
+
+# Example
+pnpm patch express@4.18.2
+```
+
+This creates a temporary directory with the package source and outputs the path:
+
+```
+You can now edit the following folder: /tmp/abc123...
+```
+
+### Step 2: Edit Files
+
+Navigate to the temporary directory and make your changes:
+
+```bash
+cd /tmp/abc123...
+# Edit files as needed
+```
+
+### Step 3: Commit Patch
+
+```bash
+pnpm patch-commit <path-from-step-1>
+
+# Example
+pnpm patch-commit /tmp/abc123...
+```
+
+This creates a `.patch` file in `patches/` and updates `package.json`:
+
+```
+patches/
+└── express@4.18.2.patch
+```
+
+```json
+{
+  "pnpm": {
+    "patchedDependencies": {
+      "express@4.18.2": "patches/express@4.18.2.patch"
+    }
+  }
+}
+```
+
+## Patch File Format
+
+Patches use standard unified diff format:
+
+```diff
+diff --git a/lib/router/index.js b/lib/router/index.js
+index abc123..def456 100644
+--- a/lib/router/index.js
++++ b/lib/router/index.js
+@@ -100,6 +100,7 @@ function createRouter() {
+   // Original code
+-  const timeout = 30000;
++  const timeout = 60000; // Extended timeout
+   return router;
+ }
+```
+
+## Managing Patches
+
+### List Patched Packages
+
+```bash
+pnpm list --depth=0
+# Shows (patched) marker for patched packages
+```
+
+### Update a Patch
+
+```bash
+# Edit existing patch
+pnpm patch express@4.18.2
+
+# After editing
+pnpm patch-commit <path>
+```
+
+### Remove a Patch
+
+```bash
+pnpm patch-remove <pkg>@<version>
+
+# Example  
+pnpm patch-remove express@4.18.2
+```
+
+Or manually:
+1. Delete the patch file from `patches/`
+2. Remove entry from `patchedDependencies` in `package.json`
+3. Run `pnpm install`
+
+## Patch Configuration
+
+### Custom Patches Directory
+
+```json
+{
+  "pnpm": {
+    "patchedDependencies": {
+      "express@4.18.2": "custom-patches/my-express-fix.patch"
+    }
+  }
+}
+```
+
+### Multiple Packages
+
+```json
+{
+  "pnpm": {
+    "patchedDependencies": {
+      "express@4.18.2": "patches/express@4.18.2.patch",
+      "lodash@4.17.21": "patches/lodash@4.17.21.patch",
+      "@types/node@20.10.0": "patches/@types__node@20.10.0.patch"
+    }
+  }
+}
+```
+
+## Workspaces
+
+Patches are shared across the workspace. Define in the root `package.json`:
+
+```json
+// Root package.json
+{
+  "pnpm": {
+    "patchedDependencies": {
+      "express@4.18.2": "patches/express@4.18.2.patch"
+    }
+  }
+}
+```
+
+All workspace packages using `express@4.18.2` will have the patch applied.
+
+## Best Practices
+
+1. **Version specificity**: Patches are tied to exact versions. Update patches when upgrading dependencies.
+
+2. **Document patches**: Add comments explaining why the patch exists:
+   ```bash
+   # In patches/README.md
+   ## express@4.18.2.patch
+   Fixes timeout issue. PR pending: https://github.com/expressjs/express/pull/1234
+   ```
+
+3. **Minimize patches**: Keep patches small and focused. Large patches are hard to maintain.
+
+4. **Track upstream**: Note upstream issues/PRs so you can remove patches when fixed.
+
+5. **Test patches**: Ensure patched code works correctly in your use case.
+
+## Troubleshooting
+
+### Patch fails to apply
+
+```
+ERR_PNPM_PATCH_FAILED  Cannot apply patch
+```
+
+The package version changed. Recreate the patch:
+```bash
+pnpm patch-remove express@4.18.2
+pnpm patch express@4.18.2
+# Reapply changes
+pnpm patch-commit <path>
+```
+
+### Patch not applied
+
+Ensure:
+1. Version in `patchedDependencies` matches installed version exactly
+2. Run `pnpm install` after adding patch configuration
+
+<!-- 
+Source references:
+- https://pnpm.io/cli/patch
+- https://pnpm.io/cli/patch-commit
+- https://pnpm.io/package_json#pnpmpatcheddependencies
+-->