soia-env-node-install

Prefer the official Node.js LTS installation path, and diagnose "not installed, installed but not found in PATH, npm registry/permission issues, project version mismatch" separately. Do not mix multiple version managers on the same machine without a plan.

Customer-readable description

What this skill can do

Customer wants	Skill will do	Customer can see
Install Node.js	Identify system/architecture, choose official LTS, install and verify	Node/npm version and path status
Check for Node.js updates	Identify installation source, compare project constraints with the latest Active LTS, do not auto-update	Current version, latest version, and source
Update Node.js to latest	After the customer explicitly requests the latest version, update along the original source	Intermediate state, version changes, and rollback boundaries
npm unavailable	Check PATH, npm prefix, and permissions	Blocking cause and safe fix options
Prepare environment for Codex	Verify Node/npm first, then hand off to the Codex skill	Readiness status that can continue execution

How the customer uses it

Other recognizable phrasings include "update Node to latest", "install npm", "npm timeout"; pure network failures are prioritized to soia-env-network-diagnose。

State the target project, operating system, and whether a specific Node major version is needed; when unsure, default to the latest official Active LTS, and do not hardcode a permanent version number.
Agent first checks existing node、npm and project configuration, and does not automatically uninstall old versions.
When a new version is found, only report it; when only "update Node" is said, first ask whether to update to the latest, and execute only after the customer explicitly chooses the latest version.
Show installation source, version, and PATH impact; confirm separately when administrator privileges are needed.
During installation or explicitly authorized updates, continuously display and record checks, plan, execution, verification, and final state.

Dependencies and installation

No required external skill. For network issues, first call soia-env-network-diagnose; when Codex needs Node/npm, soia-env-codex-install consumes the result of this skill. Official sources are at official-sources.md。

Default version policy

The default target is the latest official Active LTS of Node.js; production or long-term maintenance projects do not choose the Current version by default.
First read .nvmrc、package.json of engines, CI configuration, and project documentation; project constraints take precedence over global defaults.
The currently installed Current version does not equal an error. If the project is compatible and the customer has not requested a switch, do not automatically downgrade; clearly state in the receipt that it is "installed but not the default LTS".
For the current version, LTS status, and download entry point, refer to Node.js Releases .

Installed status and updates

Determine the source first, then update; do not mix different installation methods together:

node --version
npm --version
command -v node
brew list --versions node 2>/dev/null || true
command -v nvm 2>/dev/null || true

Installed and satisfies project constraints: prompt "Node.js is already installed, no need to reinstall", and continue verifying npm, PATH, and project version.
Installed but is Current: prompt "already installed, currently not the default Active LTS"; whether to switch is decided by the customer or project constraints, and do not automatically downgrade.
Homebrew management: only after the customer explicitly requests updating to the latest Active LTS, execute brew update && brew upgrade node。
nvm management: only after the customer explicitly requests updating to the latest Active LTS, execute nvm install --lts && nvm alias default 'lts/*' && nvm use --lts; do not additionally introduce Homebrew or the official installer at the same time.
Official installer management: obtain the target LTS installer from the official Node.js download page for an overwrite update; before installation, record the existing version and PATH state.

A vague "update Node" only performs a version comparison and returns "waiting to confirm whether to update to the latest"; the above commands must not be run. Explicitly installing a missing Node.js may install the recommended Active LTS and is not considered updating an existing tool.

After updating, reload the shell, then verify node --version、npm --version、npm config get prefix and the project version constraints. On failure, keep the old version; do not automatically uninstall or clean up.

Standard procedure

Read-only check of OS, architecture, existing version, whether PATH contains the executable, and the project's .nvmrc/package.json version requirements; do not print full environment variables.
Choose the official LTS installer or an officially recognized version management method; choose only one method at a time and record it.
When already installed, by default stop at the version report; only enter the update plan when the latest version is explicitly requested.
Before installation, confirm the download source and permissions; unknown mirrors, modifying TLS verification, or curl | bash。
After installation, re-resolve PATH; if the shell profile needs changing, first show the target file and the content to be appended and confirm.
Verify node --version、npm --version、npm config get prefix, and use npm --version as the minimal npm health check.
Output ready|missing|update_available|blocked and version, and hand off to the upper-level environment orchestration or Codex skill.
Report to the customer using the fixed list below; show only the target tools requested by the customer.

Customer status list (mandatory)

Skill	Current status	Current version	Latest version	Running status	Update time	Handling result
Node.js	<installed/not installed/blocked>	<version or not obtained>	<version or not obtained>	<normal/abnormal/unverified>		<no reinstall needed/updatable, not executed/waiting to confirm whether to update to the latest/updated/waiting to confirm before installation/blocked: reason>

When the user only asks about Node.js, output only the Node.js row, and do not additionally output npm; only add the npm row when the user explicitly asks about npm.
更新时间 Record the time when version, PATH, and harmless run verification are all completed.
The latest version is determined by the project constraints and the official Active LTS; when it cannot be obtained, write "not obtained"; do not guess.
After the table, keep only the necessary permission confirmation, PATH impact, or blocking explanation; do not show internal probing logs.

Intermediate states of installation and update

When actually performing installation or an update authorized for the latest version, use random run_id at the moment each stage actually occurs, immediately call scripts/record_install_progress.py: record once each before checking, after the plan is formed, before invoking the installer/updater, before verification, and at the final state; when extra permissions, source switching, or PATH modification are needed, record additionally waiting_confirmation. Do not write entries afterward; timestamps are generated by the recorder. Read-only checks do not call it. Only when the customer's exact words explicitly request the latest version does the update execution stage carry --customer-requested-latest。

python3 scripts/record_install_progress.py --run-id <run-id> --action <install|update> --stage checking --status in_progress --result-code checking_started
python3 scripts/record_install_progress.py --run-id <run-id> --action update --stage updating --status in_progress --result-code update_started --customer-requested-latest

Also continuously display the fixed stage table; append the terminal state on success, failure, cancellation, or while waiting for permission:

Stage	Current Status	Update Time	Processing Result
<Check/Plan/Wait for Confirmation/Install or Update/Verify/Complete or Fail>	<In Progress/Waiting/Completed/Failed/Blocked>		<Redacted Result>

Permissions and Rollback

Default to user-level installation; do not proactively use sudo or administrator privileges.
Do not delete the old Node, do not modify project lock files, and do not install business dependencies globally.
On version conflicts, keep the current state and request a choice; on failure, provide official uninstall/repair paths instead of automatic cleanup.

Private Information and Intermediate Data

npm login credentials use the official npm login state and system-supported credential mechanisms; SOIA configuration only stores non-secret preferences, version policies, and paths.
During the install or update stage, use a progress recorder to append redacted actions, stages, results, and times; read-only checks are not written to disk by default.
Package metadata may be placed in the cache; the installer and extracted contents are placed in a separate system temporary directory for each run and cleaned up after success or failure.
Do not record registry tokens, full private registry URLs, usernames, or customer private absolute paths.

Logs and Completion Receipts

| 技能 | 当前状态 | 当前版本 | 最新版本 | 运行状态 | 更新时间 | 处理结果 |
|---|---|---|---|---|---|---|
| Node.js | <状态> | <当前版本> | <最新版本> | <运行状态> | <RFC3339-with-timezone> | <处理结果> |

Forward Testing

Use fixtures to cover Node already present, Node missing, PATH inconsistency, and project requirement conflicts; real acceptance must separately execute Node and npm version checks.

Install the entire domain (Claude Code and Codex share the same domain plugin):

claude plugin marketplace add soia-team/soia-open-skills
claude plugin install soia-env@soia

Install only this one skill:

npx skills add soia-team/soia-open-env-skills -g -a '*' -s soia-env-node-install -y

WorkBuddy 's loading unit is role-based experts rather than plugins,npx skills add -a '*' cannot cover it and requires separate installation, see docs/install/workbuddy.md。