swpm-manage-commands-args

name	swpm-manage-commands-args
id	swpm-manage-commands-args
version	1.0.0
tags	["swpm","package-manager","command-mapping","args-mapping","cli","typescript"]
description	Manage cmds and args props in SWPM package manager configs (src/packages/managers/*.ts), including adding, modifying or removing command and argument mappings across npm, yarn, pnpm, bun, deno. Includes internal templates and real-world examples.

Manage SWPM Commands and Args

Use this skill when creating or modifying cmds and/or args props in package manager configuration files under src/packages/managers/*.ts. Handles adding new mappings, updating existing ones, and ensuring consistency across all supported package managers.

When to Use

• User requests to add/modify/remove a command or argument mapping
• Changes to cmds or args props in src/packages/managers/*.ts files
• Ensuring consistent command/argument support across npm, yarn, pnpm, bun, deno
• Do not use for changes outside manager config files, or for commands/args identical across all package managers

Instructions

1. Modify/Add cmds or args in package manager configs

   • Edit target files in src/packages/managers/*.ts (npm.ts, yarn.ts, pnpm.ts, bun.ts, deno.ts)
   • For cmds prop: follow templates in templates/commands.md (Replace, Replace+Flag, Not Available, Positional)
   • For args prop: follow templates in templates/args.md (Replace, Replace with Command, Convert to Commands, Remove, Package Decoration, Not Available)
   • Ensure consistency: update all relevant manager files for the same command/argument

2. Handle command files (only for new/modified commands)

   • New command: Create src/cli/swpm/commands/<command-name>.ts with @yargs v18 API
   • Modified command: Edit existing command file if behavior changes
   • Command file MUST exist for the command to work

3. Update CLI registration (only for new commands)

   • Edit src/cli/swpm/cli.ts to register new commands
   • Verify existing registration is valid for modified commands

4. Update documentation

   • Update CHEATSHEET.md with [x]/[ ] markers for command support
   • Update README.md if support status changed (remove/add availability warnings)

5. Verify

   • Run npm run build to compile TypeScript
   • Run npm run test to check regressions
   • Test changes with target package managers

Constraints

• New commands require all three: manager config + command file + cli.ts registration
• Args-only changes only require manager config updates
• Only map cmds/args that differ across package managers
• Identical commands/args across all managers do NOT need mapping
• SWPM passes through unknown commands/args as-is to detected package manager
• ESM only, Node.js >= 20, TypeScript strict mode
• @yargs v18 API (not v17 or earlier)

Examples

Example 1: Replace command (remove → uninstall)

User request: "Map remove command to uninstall for npm"

Context: npm uses uninstall while other package managers use remove

Action:

1. Edit src/packages/managers/npm.ts cmds prop following templates/commands.md:

cmds: {
  remove: 'uninstall',
  r: 'uninstall',
}

Result: swpm remove express → npm uninstall express

---

Example 2: Replace+Flag command (upgrade → install --latest)

User request: "Make upgrade command use install --latest in npm"

Context: npm uses install --latest to upgrade packages, while pnpm uses update

Action:

Edit src/packages/managers/npm.ts cmds prop:

cmds: {
  upgrade: ['install', '--latest'],
  ug: ['install', '--latest'],
}

Result: swpm upgrade express → npm install express --latest

---

Example 3: Not Available command

User request: "Mark why command as not available for npm"

Context: npm doesn't have a why command, but pnpm and yarn do

Action:

Edit src/packages/managers/npm.ts cmds prop:

cmds: {
  why: ['', -1],
}

Result: swpm why express → Not executed in npm (shows error/warning)

---

Example 4: Positional command (run with -- separator)

User request: "Add support for passing args after -- in run command"

Context: Need to pass additional args to the script being run

Action:

Edit all manager config files:

cmds: {
  run: { '--': '--' },
}

Result: swpm run test -- --watch → npm run test -- --watch

---

Example 5: Package Decoration arg (--latest → @latest)

User request: "Make --latest flag add @latest to package name"

Context: Install package with latest tag

Action:

Edit src/packages/managers/npm.ts args prop following templates/args.md:

args: {
  '--latest': ['<package>@latest', 1],
  '-L': ['<package>@latest', 1],
}

Result: swpm add express --latest → npm install express@latest

---

Example 6: Replace with Command arg (--global → global command)

User request: "Convert --global flag to global command for npm"

Context: npm uses --global flag, pnpm uses global subcommand

Action:

Edit src/packages/managers/pnpm.ts args prop:

args: {
  '--global': ['global', 1],
  '-g': ['global', 1],
}

Result: swpm add express --global → pnpm global add express

---

Example 7: Convert to Commands arg (--frozen → ci)

User request: "Make --frozen flag convert install to ci command"

Context: pnpm uses ci for frozen installs

Action:

Edit src/packages/managers/pnpm.ts args prop:

args: {
  '--frozen': {
    install: 'ci',
    i: 'ci',
  },
}

Result: swpm install --frozen → pnpm ci

---

Observations

Before acting, observe:

• Review existing cmds and args patterns in manager files at src/packages/managers/*.ts
• Verify CHEATSHEET.md for current implementation status
• Check src/cli/swpm/commands/ for existing command files
• Reference templates/commands.md and templates/args.md for configuration patterns