Cacti Package Removal Skill

Safe, complete procedure for removing one or more packages from the Hyperledger Cacti Yarn 4 monorepo without leaving stale imports, dangling CI jobs, or broken tsconfig.json references.

Repo Facts

• Yarn 4 monorepo, nodeLinker: pnpm — no root node_modules/.bin/; use yarn <binary> in husky hooks, never npx.
• lerna.json autodiscovers packages via globs (packages/cactus-*) — no edits needed when removing packages.
• Root tsconfig.json has explicit project references — always remove entries for deleted packages.
• macOS grep fails with "maximum repetition exceeds 255" on long |-alternation patterns — run one package name per grep call.

Input

You will receive:

• Package name(s): one or more packages/<pkg-name> directories to remove
• Context (optional): issue number, cleanup tracking doc path, branch name

Procedure

Step 1 — Inventory

List every directory targeted for removal and confirm current state:

find packages/ -maxdepth 1 -name "<pattern>" -type d | sort
ls packages/<pkg-name>/

A prior partial cleanup may have removed source files but left dist/ and node_modules/; that is fine — rm -rf in Step 7 handles it.

Step 2 — Cross-package package.json dependency check

For each removed package name, run separately (one term per call):

find packages/ examples/ extensions/ -name "package.json" \
  -not -path "*/node_modules/*" \
  -exec grep -l "<pkg-name>" {} \;

Any hit outside the package's own directory is a blocker — remove that dependency declaration before proceeding.

Step 3 — TypeScript import check

Run once per package name, separately:

grep -r "<pkg-name>" packages/ --include="*.ts" --exclude-dir=node_modules
grep -r "<pkg-name>" examples/ --include="*.ts" --exclude-dir=node_modules
grep -r "<pkg-name>" extensions/ --include="*.ts" --exclude-dir=node_modules

Any import/require in a surviving package is a blocker — resolve it first.

Step 4 — CI workflow audit

grep -rl "<pkg-name>" .github/

Run once per package name. For each match:

Step 5 — Root tsconfig.json project references

grep "<pkg-name>" tsconfig.json

If found, remove the corresponding { "path": "./packages/<pkg-name>/tsconfig.json" } entry.

Step 6 — cactus-test-tooling helpers

Check whether packages/cactus-test-tooling/src/main/typescript/ contains a package-specific Docker/container helper, then verify surviving consumers:

grep -r "<HelperClassName>" packages/ --include="*.ts" --exclude-dir=node_modules \
  | grep -v "cactus-test-tooling\|<removed-pkg>"

Example: CactusKeychainVaultServer had no surviving consumer → removed. VaultTestServer was used by cactus-plugin-ledger-connector-fabric → kept.

Step 7 — Delete package directories

rm -rf packages/<pkg-name>

This removes everything including leftover dist/, node_modules/, and .tgz pack artifacts.

Step 8 — Regenerate yarn.lock

yarn install --mode=update-lockfile

Removes stale workspace: entries for deleted packages from yarn.lock without re-linking all dependencies.

Step 9 — Update docs/docs/cleanup-4025.md

1. Add removed packages to the "Packages Approved for Removal" table with today's date.
2. In the Review Tables, flip each removed package's keep? cell from − → ❌ and set action columns to N/A.
3. Update Decision Summary counts: Remove/Archive +N, No Vote −N.
4. Append a completion line to the footer:

   **<Label> Completed:** YYYY-MM-DD — `<branch-name>`

Step 10 — Verification pass

All checks must return empty/clean output before the task is complete:

# No live TypeScript imports
grep -r "<pkg-name>" packages/ --include="*.ts" --exclude-dir=node_modules

# No package.json dependency declarations
find packages/ examples/ extensions/ -name "package.json" \
  -not -path "*/node_modules/*" -exec grep -l "<pkg-name>" {} \;

# No CI workflow references
grep -rl "<pkg-name>" .github/

# No yarn.lock workspace entries
grep "<pkg-name>" yarn.lock

Acceptable remaining hits: CHANGELOG.md files (auto-generated git history), docs/ tracking documents, and dist/ build artifacts (stale until next yarn tsc).

Step 11 - Extra verifications

Verify references to package being removed, for instance in the docs, CONTRIBUTING.md, tools/custom-checks/check-dependency-version-consistency, jest.config.js, openapi-generator-ignore, package.json. Notably, the reference to the package being removed should be removed from the root tsconfig.ts as well as from the tsconfig from packages depending on it. Do not remove references from the changelog.

Output Format

After completing all steps, provide:

• Summary: which packages were removed and any blockers resolved
• Verification: results of the Step 10 checks
• Residual risk: anything deferred or not verified (e.g. integration tests not run locally)

Constraints

• Run grep with one package name per call — never combine multiple names in a |-alternation pattern on macOS.
• Never edit files under generated/ directly.
• Do not remove cactus-test-tooling helpers that have surviving consumers.
• Treat any Step 2 or Step 3 blocker as a hard stop — resolve it before deleting the package directory.
• Do not git commit or git push — report what changed and let the user review, stage, and commit.
• After completing, hand off to the code-reviewer agent to audit: no stale imports, no stale package.json deps, CI jobs removed, tsconfig.json references cleaned, yarn.lock updated, tracking doc updated.