Skip to content

TASKS-JSON-REFERENCE.md

Latest commit

 

History

History
388 lines (314 loc) · 11 KB

TASKS-JSON-REFERENCE.md

File metadata and controls

388 lines (314 loc) · 11 KB

tasks.json Field Reference

This document describes all available fields in tasks.json for defining npm learning tasks.

Core Fields

description (required)

  • Type: string
  • Description: Brief description of what the user should accomplish in this task
  • Example: "Install the lodash package into your project."
  • Usage: Displayed to the user as the task prompt

expectedCommand (required)

  • Type: string
  • Description: The exact npm command the user should enter to complete the task
  • Example: "npm install lodash"
  • Usage: Used to validate user input and provide hints

explanation (required)

  • Type: string
  • Description: Detailed explanation of what the command does and why it's useful
  • Example: "Installs the lodash package and adds it to your dependencies in package.json."
  • Usage: Displayed when user types explain command

Validation Fields

checkCommand

  • Type: string
  • Description: Shell command to verify the task was completed successfully (Unix/Linux/Mac)
  • Example: "test -f package.json"
  • Usage: Runs after the main command to confirm it worked
  • Platform: Unix-based systems (Mac, Linux)

windowsCheckCommand

  • Type: string
  • Description: Shell command to verify the task was completed successfully (Windows)
  • Example: "if exist package.json (exit 0) else (exit 1)"
  • Usage: Alternative to checkCommand for Windows systems
  • Platform: Windows only

preCheckCommand

  • Type: string
  • Description: Shell command to verify prerequisites before running the main command
  • Example: "test -f package-lock.json"
  • Usage: Runs before the main command; task is skipped if it fails
  • Note: Useful for tasks that depend on previous task results

outputIncludes

  • Type: string
  • Description: String that must appear in the command's stdout/stderr output
  • Example: "added"
  • Usage: Validates that the command produced expected output
  • Note: Case-sensitive substring match

Setup and Cleanup Fields

beforeCommand

  • Type: string
  • Description: Shell command to run before the main command (setup)
  • Example: "rm -rf node_modules"
  • Usage: Prepares the environment for the task
  • Execution: Runs before preCheckCommand and expectedCommand

beforeRequiresSudo

  • Type: boolean
  • Description: Whether beforeCommand needs sudo on Linux
  • Example: true
  • Usage: Automatically prepends sudo to beforeCommand on Linux
  • Platform: Linux only (ignored on Mac/Windows)
  • Default: false

afterCommand

  • Type: string
  • Description: Shell command to run after the main command (cleanup)
  • Example: "rm my-npm-project-*.tgz"
  • Usage: Cleans up side effects or temporary files
  • Execution: Runs after expectedCommand and checkCommand

Permission and Platform Fields

requireSudo

  • Type: boolean
  • Description: Whether the main command needs sudo on Linux
  • Example: true
  • Usage: Automatically prepends sudo to expectedCommand on Linux
  • Platform: Linux only (ignored on Mac/Windows)
  • Default: false
  • Common Use Cases: Global npm installs, linking packages

Behavior Control Fields

strictCommandMatch

  • Type: boolean
  • Description: Requires exact match of the command (no partial matches)
  • Example: true
  • Usage: For commands with specific flags or arguments
  • Default: false (allows fuzzy matching)

nonZeroOkay

  • Type: boolean
  • Description: Command is allowed to exit with non-zero status
  • Example: true
  • Usage: For commands that intentionally fail or return error codes
  • Default: false
  • Common Use Cases: npm outdated, npm audit

isBrowserCommand

  • Type: boolean
  • Description: Command opens a browser instead of producing terminal output
  • Example: true
  • Usage: Skips output validation for browser commands
  • Default: false
  • Common Use Cases: npm docs, npm bugs, npm repo

Test Control Fields

skipTest

  • Type: boolean
  • Description: Skip this task in automated test runs
  • Example: true
  • Usage: For tasks requiring user interaction or authentication
  • Default: false
  • Common Use Cases: npm login, npm adduser, npm publish

requiresUserInput

  • Type: boolean
  • Description: Task requires interactive user input
  • Example: true
  • Usage: Displays warning in go command; handled specially in tests
  • Default: false
  • Note: Usually paired with skipTest: true

doesntWork

  • Type: boolean
  • Description: Command is known to be broken in current npm version (all platforms)
  • Example: true
  • Usage: Task still shows in CLI (user can try it), but skipped in automated tests
  • Default: false
  • Common Use Cases: Deprecated or buggy npm commands (e.g., npm stars)

doesntWorkOnWindows

  • Type: boolean
  • Description: Command doesn't work on Windows but works on Linux/Mac
  • Example: true
  • Usage: Task shows normally in CLI on all platforms (user can try), but skipped in test suite on Windows only
  • Default: false
  • Common Use Cases: Unix-specific commands, Windows compatibility issues (e.g., npm edit)
  • Note: Paired with nonZeroOkay: true since command will fail on Windows

Field Combinations and Best Practices

Minimal Task

{
  "description": "List installed packages.",
  "expectedCommand": "npm ls",
  "explanation": "Displays a tree of all installed packages."
}

Task with Validation

{
  "description": "Install lodash package.",
  "expectedCommand": "npm install lodash",
  "checkCommand": "test -d node_modules/lodash",
  "outputIncludes": "added",
  "explanation": "Installs lodash and adds it to dependencies."
}

Task with Setup and Cleanup

{
  "description": "Reinstall dependencies cleanly.",
  "expectedCommand": "npm ci",
  "beforeCommand": "rm -rf node_modules",
  "preCheckCommand": "test -f package-lock.json",
  "checkCommand": "test -d node_modules",
  "afterCommand": "echo 'Cleanup complete'",
  "explanation": "Clean install from lockfile."
}

Task Requiring Sudo (Linux)

{
  "description": "Link package globally.",
  "expectedCommand": "npm link",
  "requireSudo": true,
  "checkCommand": "npm ls -g | grep -q 'my-package'",
  "explanation": "Creates global symlink to your package."
}

Task with Setup Requiring Sudo (Linux)

{
  "description": "Diagnose npm environment.",
  "expectedCommand": "npm doctor",
  "beforeCommand": "npm install -g npm@11.6.1",
  "beforeRequiresSudo": true,
  "preCheckCommand": "npm -v | grep -q '^11\\.6\\.1$'",
  "explanation": "Runs environment diagnostics."
}

Cross-Platform Task

{
  "description": "Initialize npm project.",
  "expectedCommand": "npm init -y",
  "checkCommand": "test -f package.json",
  "windowsCheckCommand": "if exist package.json (exit 0) else (exit 1)",
  "explanation": "Creates package.json with defaults."
}

Authentication Task (Skipped in Tests)

{
  "description": "Log in to npm.",
  "expectedCommand": "npm login",
  "requiresUserInput": true,
  "skipTest": true,
  "outputIncludes": "Logged in",
  "explanation": "Authenticates your npm account."
}

Browser Command

{
  "description": "View axios repository.",
  "expectedCommand": "npm repo axios",
  "strictCommandMatch": true,
  "isBrowserCommand": true,
  "explanation": "Opens the source code repository."
}

Execution Order

When a task is executed, the following order is followed:

  1. beforeCommand (with sudo if beforeRequiresSudo: true on Linux)
  2. preCheckCommand (validation - task skipped if fails)
  3. expectedCommand (with sudo if requireSudo: true on Linux)
  4. outputIncludes (validation - checks command output)
  5. checkCommand or windowsCheckCommand (validation)
  6. afterCommand (cleanup - always runs)

Platform-Specific Behavior

Linux

  • Uses checkCommand for validation
  • Prepends sudo when requireSudo: true
  • Prepends sudo to beforeCommand when beforeRequiresSudo: true
  • Some tasks may be skipped (e.g., sqlite3 due to SSL issues)

macOS

  • Uses checkCommand for validation
  • No sudo prepending (user typically has permissions)
  • All tasks should work natively

Windows

  • Uses windowsCheckCommand for validation (falls back to checkCommand)
  • No sudo support
  • May require admin privileges for global installs
  • Path separators differ (backslash vs forward slash)

Common Patterns

Global Install Pattern

{
  "description": "Install package globally.",
  "expectedCommand": "npm install -g <package>",
  "requireSudo": true,
  "checkCommand": "command -v <package>",
  "explanation": "Installs package globally for CLI usage."
}

Registry Switch Pattern

{
  "description": "Switch to local registry.",
  "expectedCommand": "npm set registry http://localhost:4873",
  "checkCommand": "npm config get registry | grep -q 'localhost:4873'",
  "explanation": "Points npm to local Verdaccio registry."
}

Cleanup Pattern

{
  "description": "Create temporary file.",
  "expectedCommand": "npm pack",
  "checkCommand": "ls *.tgz | grep -q '.tgz'",
  "afterCommand": "rm *.tgz",
  "explanation": "Creates tarball and cleans up after."
}

Validation Tips

Writing Good Check Commands

✅ Good: Specific and reliable

"checkCommand": "npm list lodash | grep -q 'lodash@4.17.21'"

❌ Bad: Too generic or fragile

"checkCommand": "ls node_modules"

Using outputIncludes

✅ Good: Unique substring

"outputIncludes": "added 1 package"

❌ Bad: Common word that might appear elsewhere

"outputIncludes": "npm"

Debugging Tasks

If a task isn't working as expected, check:

  1. ✅ Is requireSudo or beforeRequiresSudo set correctly for Linux?
  2. ✅ Does checkCommand work independently?
  3. ✅ Is windowsCheckCommand provided for cross-platform tasks?
  4. ✅ Does outputIncludes match actual command output?
  5. ✅ Are beforeCommand/afterCommand idempotent (safe to run multiple times)?
  6. ✅ Should the task be marked skipTest: true?

Adding New Tasks

When adding a new task to tasks.json:

  1. Start with minimal fields (description, expectedCommand, explanation)
  2. Add checkCommand to verify completion
  3. Add windowsCheckCommand if task should work on Windows
  4. Add beforeCommand if setup is needed
  5. Set requireSudo or beforeRequiresSudo if it needs elevated permissions on Linux
  6. Set skipTest if it requires authentication or user input
  7. Test on all platforms if possible

Version History

  • v1.0: Initial field definitions
  • v1.1: Added requireSudo for Linux global installs
  • v1.2: Added beforeRequiresSudo for setup commands requiring sudo
  • v1.3: Added windowsCheckCommand for cross-platform support