Vibe Coding Class Doctor

A dependency-free readiness check for Drew's Intro to Vibe Coding class. Run it in your VibeCoding class folder. It performs small, real tasks and leaves a readable report for your instructor.

Run

Install Node 24 LTS, including npm, first. An existing Node 22 LTS installation is accepted for this class. Then open a fresh terminal in your class folder:

npx --yes [email protected]

This downloads and executes version 1.0.1 from npm. Git and GitHub sign-in are not required to download it. On Windows, if PowerShell blocks npx.ps1, use npx.cmd in the same command; do not weaken your execution policy.

Use npx vibecode-class-doctor for the latest published release. The versioned command above keeps the classroom on a consistent release.

For setup assistance, copy the student prompt into Codex or Claude Code. The diagnostic itself does not install or repair tools.

What it checks

| Check | What actually happens | | --- | --- | | Node, npm, npx, Git, GitHub CLI | Executes each tool's version command from the current environment | | Class folder | Writes and reads a temporary file | | Running code | Executes a tiny Node program through an npm script | | Local Git | Initializes a temporary repository, stages a file, and verifies staging; no commit | | npm packaging | Packages a tiny project using an isolated temporary cache, with lifecycle scripts disabled | | Local web server | Starts an HTTP server on 127.0.0.1 and requests its page | | Network | Probes the public npm registry, GitHub and Node website over HTTPS; also runs npm ping | | Resources | Reports memory and free disk space; suggests 4 GiB RAM and 2 GiB free disk |

Node 22/24, npm/npx 10+, Git 2+, and GitHub CLI 2+ are the class baseline. Newer non-baseline Node versions receive REVIEW. These are class compatibility checks, not a software security audit.

Manual checks remain: the editor can save/reopen a file; the coding agent can read that file and execute a local command; the browser works; the student has a charger and access to the laptop at home. The doctor does not verify account eligibility, subscriptions, editor extensions, or future course frameworks. GitHub authentication and Git author identity are deferred.

Read the result

| Result | Meaning | Student action | | --- | --- | --- | | TOOLS READY | Automated checks passed or only informational findings remain | Leave report open and work on worksheet; Drew still checks editor/agent/browser | | REVIEW | A warning or skipped check needs interpretation | Raise hand, leave report open, begin worksheet | | NEEDS HELP | A required check failed | Raise hand, leave report open, begin worksheet |

Do not change a report to make it pass. Network probes can fail because of a proxy, school filter, sandbox, outage, or certificate configuration. Check the specific finding with Drew; never disable TLS verification or the firewall. Run from the same environment used for class: Windows and WSL are separate setups.

Each run saves uniquely named vibecode-report-*.txt and .json files in the current folder. The JSON has schemaVersion, doctorVersion, createdAt, summary, checks, and manualChecks. The text report is for the instructor; the JSON supports later tooling. No report is uploaded. The program does not read source code, account tokens, or GitHub authentication state. Ordinary HTTPS requests and npm operations still contact the named services and may use existing npm proxy/registry configuration.

It creates and deletes only its own .vibecode-doctor-* temporary folder. It does not alter an existing repository or Git configuration. npm/npx may populate their normal download cache/logs; the packaging smoke test uses its own temporary cache. A failed cleanup is reported. CLI version strings, OS/architecture, available resources, and check results are included; student names and home paths are not added by the doctor.

Instructor: fit this into 90 minutes

Open with the presentation (0–25 minutes). Launch setup during minutes 25–35, then let installations and diagnostics continue while students complete the assessment (35–80). Visit all 13 students, roughly three minutes each. Prioritize NEEDS HELP, then REVIEW, then manual verification for TOOLS READY. If an installer needs an administrator or a repair takes more than a few minutes, record the blocker and move on. Collect assessments at 80–83 and preview next week at 83–90.

For each student, record: automated result, editor checked, agent checked, browser checked, and one remaining action. A warning is information, not a grade. Do not promise a complete installation within a three-minute visit.

Options and exit codes

Append options after the package name:

npx --yes [email protected] --no-save

• --offline: skips network checks and yields REVIEW unless another check fails; initial npx download still needs connectivity.
• --no-save: prints the report without saving it.
• --help / --version: prints usage/version.
• Exit 0: TOOLS READY; 1: NEEDS HELP; 2: REVIEW; 3: command/report error. A nonzero exit with a report is an assessment result, not necessarily a crashed program.

Development and releases

npm test
npm run check
npm pack --dry-run

Tests exercise real temporary npm/Git projects, loopback HTTP, cleanup, existing-file preservation, missing tools, network failures, inherited Git environment isolation, and Windows shim argument handling. CI runs on macOS, Windows, and Linux with Node 22 and 24; automated network probes are stubbed in the tests for reproducibility. Classroom Wi-Fi and agent/editor behavior must be checked on site.

To release: update package and diagnostic versions together, run checks and CI, create a new version tag, and update the student command. Never move a published version tag. Publish new versions with npm publish --access public using an authorized npm account. This repository does not publish to npm automatically. The original v1.0.0 GitHub tag remains the tested source snapshot; npm 1.0.0 adds updated distribution instructions without changing the diagnostic code.

Official installation sources: Node.js, Git, GitHub CLI. npm exec/npx documentation.

Version 1.0.1

Reports start with an instructor summary. A failed Node download-site probe is INFO, rather than WARN, only when the running Node and Node on PATH meet the class baseline and the npm code-execution test passes. INFO does not change readiness; other failures and warnings still do. Network probes distinguish timeout, DNS, certificate, refused/interrupted connection, HTTP status, and unidentified errors without printing raw error messages. The doctor remains reporting-only.