@xylabs/ts-scripts-yarn3 7.5.9 → 7.5.11

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xylabs/ts-scripts-yarn3",
-  "version": "7.5.9",
+  "version": "7.5.11",
   "description": "TypeScript project scripts",
   "keywords": [
     "xylabs",
@@ -50,15 +50,15 @@
   },
   "devDependencies": {
     "@types/yargs": "~17.0.35",
-    "@xylabs/ts-scripts-common": "~7.5.9",
-    "@xylabs/tsconfig": "~7.5.9",
+    "@xylabs/ts-scripts-common": "~7.5.11",
+    "@xylabs/tsconfig": "~7.5.11",
     "publint": "~0.3.18",
     "tsup": "~8.5.1",
     "typescript": "^5.9.3",
     "vitest": "^4.1.1"
   },
   "peerDependencies": {
-    "@xylabs/ts-scripts-common": "~7.5.9",
+    "@xylabs/ts-scripts-common": "~7.5.11",
     "typescript": "~5"
   },
   "engines": {

package/templates/claude/skills/xylabs-xy-deplint-fix/SKILL.md

@@ -0,0 +1,254 @@
+---
+name: xylabs-xy-deplint-fix
+description: >
+  Fix dependency declaration errors in one or more packages using `xy deplint`.
+  Use this skill whenever the user asks to fix deplint errors, clean up package.json
+  dependencies, or resolve "dependency should be devDependency" / "missing dependency"
+  warnings in an XY Labs monorepo. If a package name is supplied as an argument, fix
+  only that package. If no argument is given, fix all packages in the repo.
+---
+
+# xylabs-xy-deplint-fix
+
+Diagnoses and fixes `package.json` dependency declaration errors reported by `xy deplint`
+in an XY Labs Yarn-workspaces monorepo.
+
+---
+
+## Bundled Scripts
+
+Three shell scripts live alongside this skill in `scripts/`. They collapse multiple
+bash operations into single approved calls, minimising permission prompts:
+
+| Script | Purpose | Prompts saved |
+|--------|---------|---------------|
+| `scripts/deplint-scan.sh [pkg]` | Run deplint; emit structured `PACKAGE/ERROR/PATH/STATUS` lines | Replaces 1 raw deplint call with parseable output |
+| `scripts/deplint-install.sh` | Run full `yarn install` (or `pnpm install`) from repo root | Always safe to approve once; never uses `workspaces focus` |
+| `scripts/deplint-verify.sh pkg1 [pkg2 …]` | Check N packages in one call; prints `PASS/FAIL` per package | Replaces N individual verify calls with one |
+
+**How to use them in the workflow:**
+
+```
+Step 1 → bash scripts/deplint-scan.sh [pkg]     # 1 approval
+Step 3 → (LLM reads/writes package.json files)  # no prompts
+Step 4 → bash scripts/deplint-install.sh        # 1 approval
+Step 5 → bash scripts/deplint-verify.sh <pkgs…> # 1 approval
+```
+
+All three scripts auto-detect the repo root (walking up until they find `yarn.lock`
+or `pnpm-lock.yaml`), so they work correctly regardless of the current working directory.
+
+---
+
+## Package Manager Detection
+
+Check the repo root before running any command:
+
+* `yarn.lock` present → prefix commands with **yarn** (e.g. `yarn xy deplint`)
+* `pnpm-lock.yaml` present → prefix commands with **pnpm**
+
+All commands below are shown without a prefix. Prepend accordingly.
+
+---
+
+## Determine scope from arguments
+
+* **Argument provided** (e.g. `@xyo-network/advertising-payload-plugins`) → single-package
+  mode: run Steps 1–5 for that package only, then stop.
+* **No argument** → whole-repo mode: run `xy deplint` without a package name to get all
+  problems, extract the unique set of affected package names from the output, then run
+  Steps 1–5 for each affected package in turn.
+
+---
+
+## Step 1 — Run deplint
+
+Use the bundled scan script (preferred — one approval, structured output):
+
+```bash
+# Single-package
+bash .claude/skills/xylabs-xy-deplint-fix/scripts/deplint-scan.sh @scope/package-name
+
+# Whole-repo
+bash .claude/skills/xylabs-xy-deplint-fix/scripts/deplint-scan.sh
+```
+
+Output lines have the form:
+
+```
+PACKAGE:@scope/package-name
+ERROR:<problem description>:<dep>
+PATH:packages/path/to/package.json
+STATUS:errors   # or STATUS:clean
+```
+
+In whole-repo mode, collect every unique `PACKAGE:` line to build the list of packages
+to fix. Work through them one at a time.
+
+Alternatively, run deplint directly:
+
+```bash
+xy deplint [package-name]
+```
+
+Each problem line has the form:
+
+```
+[@scope/package-name] <problem description>: <dependency-name>
+  <path/to/package.json>
+```
+
+---
+
+## Step 2 — Classify each error
+
+| Error message | Meaning | Fix |
+|---|---|---|
+| `dependency should be devDependency` | Listed in `dependencies` but not needed by npm consumers at runtime — it's a build/type/test dep, or it's a peer that consumers already provide | Move from `dependencies` → `devDependencies` |
+| `Unused devDependency` | Listed in `devDependencies` but no import of it was found anywhere in the package's source | Remove from `devDependencies` |
+| `Missing dependency` | Imported in source but absent from `dependencies` | Add to `dependencies` |
+| `Missing devDependency` | Imported in source but absent from `devDependencies` | Add to `devDependencies` |
+
+> **Aggregator packages** (packages with no `src/` that only re-export workspace children)
+> typically need all of their workspace children as `devDependencies`, not `dependencies`.
+> See Edge Cases below.
+
+---
+
+## Step 3 — Edit the package.json
+
+Open the `package.json` file identified in the deplint output and apply the fix for each
+classified error:
+
+* **Move dep**: cut the entry from `dependencies`, paste into `devDependencies`.
+* **Remove dep**: delete the entry entirely from `devDependencies`.
+* **Add dep**: insert the entry with the correct version into the appropriate section.
+  Resolve the version using this priority order:
+
+  1. **Lock file** (preferred) — search `yarn.lock` or `pnpm-lock.yaml` for the
+     package name. Use the resolved version already present in the repo.
+     * In `yarn.lock`, look for a block starting with `"<pkg>@`:
+       ```
+       "@xyo-network/payload-model@npm:~5.3.5":
+         version: 5.3.7
+       ```
+       Use the declared range (e.g. `~5.3.5`), not the resolved exact version.
+     * In `pnpm-lock.yaml`, find the entry under `packages:` and use its
+       specifier (e.g. `~5.3.5`).
+
+  2. **Another package.json in the repo** — if the lock file entry is unclear,
+     grep other `package.json` files in the monorepo for the dep name and
+     copy the version string used there.
+
+  3. **Latest from the registry** — if the dep does not exist anywhere in the
+     repo yet, it is safe to use `~latest` by running:
+     ```bash
+     npm view <package-name> version
+     ```
+     Then prefix the result with `~` (e.g. `~5.4.0`).
+
+  **Version format rule:** prefer `~` ranges throughout. If the sourced version
+  already carries a range prefix (`~` or `^`), keep it as-is. If it is a bare
+  semver (e.g. `5.3.1`), add a `~` prefix (e.g. `~5.3.1`).
+* If `dependencies` becomes empty after edits, remove the `"dependencies"` key entirely
+  to keep the file clean.
+
+---
+
+## Step 4 — Reinstall dependencies
+
+After editing `package.json`, run a **full install from the repo root**. Do not use
+`yarn workspaces focus` — it strips the `xy` scripts needed for verification.
+
+Use the bundled install script (preferred — one approval, always runs from root):
+
+```bash
+bash .claude/skills/xylabs-xy-deplint-fix/scripts/deplint-install.sh
+```
+
+Or directly:
+
+```bash
+yarn install   # or: pnpm install
+```
+
+---
+
+## Step 5 — Verify
+
+Use the bundled verify script (preferred — verifies multiple packages in one approval):
+
+```bash
+bash .claude/skills/xylabs-xy-deplint-fix/scripts/deplint-verify.sh <pkg1> [pkg2 …]
+```
+
+Or directly:
+
+```bash
+xy deplint <package-name>
+```
+
+**Definition of done for a single package:** output contains `PASS: <name>` or:
+
+```
+Deplint: Found no dependency problems. ✔
+```
+
+If problems remain, return to Step 2 and repeat the loop for the same package.
+
+---
+
+## Step 6 — Advance to the next package (whole-repo mode only)
+
+In whole-repo mode, once a package passes Step 5, move to the next package in the list
+collected in Step 1 and repeat Steps 2–5 for it.
+
+**Definition of done for whole-repo mode:** every package that appeared in the original
+`xy deplint` output now passes `xy deplint <package-name>` individually. Confirm by
+running a final `xy deplint` (no arguments) and verifying:
+
+```
+Deplint: Found no dependency problems. ✔
+```
+
+---
+
+## Edge Cases
+
+### `yarn workspaces focus` breaks the `xy` command
+
+`yarn workspaces focus <package>` installs only the deps for that one package and removes
+the root-level `xy` script bindings. Always use `yarn install` (full) after editing any
+`package.json`.
+
+### Empty `dependencies` block after migration
+
+If all entries are moved out of `dependencies`, remove the key entirely. An empty
+`"dependencies": {}` is harmless but creates noise and may confuse other tools.
+
+### Formatter auto-sorts keys
+
+The repo formatter (run as part of `yarn install` hooks) may re-sort `devDependencies`
+alphabetically. This is expected — do not revert it.
+
+### Aggregator packages
+
+Aggregator packages (e.g. `packages/payload/package.json`, `packages/sdk/package.json`)
+have no `src/` and exist solely to re-export leaf packages. In these packages:
+
+* Workspace child packages belong in `devDependencies`, not `dependencies`
+* Their transitive deps (e.g. `@xyo-network/payload-model`) will also surface as
+  `Missing devDependency` because deplint walks the leaf source files from the
+  aggregator's root
+
+Fix: move all workspace children to `devDependencies`, then add any missing transitive
+deps (also as `devDependencies`).
+
+### `dependency should be devDependency` for a runtime import
+
+deplint may flag a dep as "should be devDependency" even when it is imported for a
+runtime value (not just a type). This happens when the dep is a **foundational library**
+that consumers of the package are expected to already have installed (i.e. it behaves
+like a peer). In these cases the correct fix is still to move it to `devDependencies`.
+If the dep must be guaranteed for external npm consumers, also add it to
+`peerDependencies`.