@xylabs/ts-scripts-yarn3 7.5.10 → 7.5.12

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xylabs/ts-scripts-yarn3",
-  "version": "7.5.10",
+  "version": "7.5.12",
   "description": "TypeScript project scripts",
   "keywords": [
     "xylabs",
@@ -49,16 +49,18 @@
     "yargs": "~18.0.0"
   },
   "devDependencies": {
+    "@types/node": "^25.5.0",
     "@types/yargs": "~17.0.35",
-    "@xylabs/ts-scripts-common": "~7.5.10",
-    "@xylabs/tsconfig": "~7.5.10",
+    "@xylabs/ts-scripts-common": "~7.5.12",
+    "@xylabs/tsconfig": "~7.5.12",
     "publint": "~0.3.18",
     "tsup": "~8.5.1",
     "typescript": "^5.9.3",
-    "vitest": "^4.1.1"
+    "vite": "^8.0.3",
+    "vitest": "^4.1.2"
   },
   "peerDependencies": {
-    "@xylabs/ts-scripts-common": "~7.5.10",
+    "@xylabs/ts-scripts-common": "~7.5.12",
     "typescript": "~5"
   },
   "engines": {

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

@@ -0,0 +1,258 @@
+---
+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. **Workspace package** (highest priority) — check the `WORKSPACE:name:version` lines
+     emitted at the top of `deplint-scan.sh` output. If the dep name appears there, read
+     its version directly from that line and prefix with `~` (e.g. `5.3.7` → `~5.3.7`).
+     Never use the `workspace:` protocol — use the real semver version from the package.
+
+  2. **Lock file** — for deps not in the workspace, search `yarn.lock` or `pnpm-lock.yaml`.
+     * 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`).
+
+  3. **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.
+
+  4. **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`.

package/templates/claude/skills/xylabs-xy-deplint-fix/scripts/deplint-install.sh

@@ -0,0 +1,27 @@
+#!/usr/bin/env bash
+# deplint-install.sh
+#
+# Runs a full package install from the repo root using the detected package manager.
+# Always installs from root — never uses scoped/filtered installs (yarn workspaces focus,
+# pnpm --filter) as those strip the root xy script bindings needed for verification.
+set -euo pipefail
+
+find_repo_root() {
+  local dir="$PWD"
+  while [[ "$dir" != "/" ]]; do
+    [[ -f "$dir/yarn.lock" || -f "$dir/pnpm-lock.yaml" ]] && echo "$dir" && return
+    dir="$(dirname "$dir")"
+  done
+  echo "ERROR: repo root not found (no yarn.lock or pnpm-lock.yaml)" >&2
+  exit 1
+}
+
+REPO_ROOT="$(find_repo_root)"
+cd "$REPO_ROOT"
+
+# pnpm takes precedence over yarn — repos mid-migration may have both lock files
+if [[ -f pnpm-lock.yaml ]]; then
+  pnpm install
+else
+  yarn install
+fi

package/templates/claude/skills/xylabs-xy-deplint-fix/scripts/deplint-scan.sh

@@ -0,0 +1,75 @@
+#!/usr/bin/env bash
+# deplint-scan.sh [package-name]
+#
+# Emits:
+#   WORKSPACE:name:version   — for every non-root package in the monorepo
+#   PACKAGE:name             — for each package with deplint errors
+#   ERROR:description:dep    — for each error within that package
+#   PATH:path/to/package.json
+#   STATUS:clean|errors
+#
+# Usage:
+#   bash deplint-scan.sh                          # whole-repo scan
+#   bash deplint-scan.sh @scope/package-name      # single-package scan
+set -euo pipefail
+
+find_repo_root() {
+  local dir="$PWD"
+  while [[ "$dir" != "/" ]]; do
+    [[ -f "$dir/yarn.lock" || -f "$dir/pnpm-lock.yaml" ]] && echo "$dir" && return
+    dir="$(dirname "$dir")"
+  done
+  echo "ERROR: repo root not found (no yarn.lock or pnpm-lock.yaml)" >&2
+  exit 1
+}
+
+REPO_ROOT="$(find_repo_root)"
+cd "$REPO_ROOT"
+
+# pnpm takes precedence over yarn — repos mid-migration may have both lock files
+if [[ -f pnpm-lock.yaml ]]; then PM=pnpm; else PM=yarn; fi
+
+# Emit WORKSPACE:name:version for every non-root package in the monorepo.
+# Used by Step 3 to resolve versions for workspace-local deps without using
+# the workspace: protocol (which npm publish does not rewrite).
+find "$REPO_ROOT" -name "package.json" \
+  -not -path "*/node_modules/*" \
+  -not -path "$REPO_ROOT/package.json" | sort | \
+node -e "
+  const fs = require('fs');
+  const rl = require('readline').createInterface({ input: process.stdin });
+  rl.on('line', f => {
+    try {
+      const p = JSON.parse(fs.readFileSync(f.trim(), 'utf8'));
+      if (p.name && p.version) process.stdout.write('WORKSPACE:' + p.name + ':' + p.version + '\n');
+    } catch(e) {}
+  });
+" || true
+
+# Run deplint — exits non-zero when errors are found, so capture output regardless
+if [[ -n "${1:-}" ]]; then
+  deplint_out="$($PM xy deplint "$1" 2>&1)" || true
+else
+  deplint_out="$($PM xy deplint 2>&1)" || true
+fi
+
+# Parse deplint output into structured lines
+current_pkg=""
+while IFS= read -r line; do
+  if [[ "$line" =~ ^\[([^]]+)\]\ (.+):\ (.+)$ ]]; then
+    pkg="${BASH_REMATCH[1]}"
+    if [[ "$pkg" != "$current_pkg" ]]; then
+      current_pkg="$pkg"
+      echo "PACKAGE:$pkg"
+    fi
+    echo "ERROR:${BASH_REMATCH[2]}:${BASH_REMATCH[3]}"
+  elif [[ "$line" =~ ^[[:space:]]+(.+package\.json)$ ]]; then
+    echo "PATH:${BASH_REMATCH[1]}"
+  fi
+done <<< "$deplint_out"
+
+if echo "$deplint_out" | grep -q "Found no dependency problems"; then
+  echo "STATUS:clean"
+else
+  echo "STATUS:errors"
+fi

package/templates/claude/skills/xylabs-xy-deplint-fix/scripts/deplint-verify.sh

@@ -0,0 +1,46 @@
+#!/usr/bin/env bash
+# deplint-verify.sh <package-name> [package-name ...]
+#
+# Verifies one or more packages pass deplint in a single approved call.
+# Emits:
+#   PASS:name   — package has no deplint errors
+#   FAIL:name   — package still has deplint errors (details follow indented)
+#
+# Exits 0 only if every package passes.
+set -euo pipefail
+
+if [[ $# -eq 0 ]]; then
+  echo "Usage: deplint-verify.sh <package-name> [package-name ...]" >&2
+  exit 1
+fi
+
+find_repo_root() {
+  local dir="$PWD"
+  while [[ "$dir" != "/" ]]; do
+    [[ -f "$dir/yarn.lock" || -f "$dir/pnpm-lock.yaml" ]] && echo "$dir" && return
+    dir="$(dirname "$dir")"
+  done
+  echo "ERROR: repo root not found (no yarn.lock or pnpm-lock.yaml)" >&2
+  exit 1
+}
+
+REPO_ROOT="$(find_repo_root)"
+cd "$REPO_ROOT"
+
+# pnpm takes precedence over yarn — repos mid-migration may have both lock files
+if [[ -f pnpm-lock.yaml ]]; then PM=pnpm; else PM=yarn; fi
+
+all_passed=true
+
+for pkg in "$@"; do
+  output="$($PM xy deplint "$pkg" 2>&1)" || true
+  if echo "$output" | grep -q "Found no dependency problems"; then
+    echo "PASS:$pkg"
+  else
+    echo "FAIL:$pkg"
+    echo "$output" | grep -E "^\[|^[[:space:]]" | sed 's/^/  /' || true
+    all_passed=false
+  fi
+done
+
+$all_passed || exit 1