fix(cli): squad start --tunnel validates node-pty before side effects (#711)

[diberry]

Summary

Validates that node-pty is available before attempting to tunnel, preventing unexpected terminal corruption when the package is missing.

Changes

• Extracts a dedicated checkNodePty() helper in squad start --tunnel
• Validates node-pty availability BEFORE creating RemoteBridge or tunnel (prevents side effects)
• Graceful error message with npm install -g node-pty guidance
• Expanded packaging smoke test: forced-missing node-pty scenario
• Regression test verifies validation order in source (checkNodePty before RemoteBridge)
• node-pty and qrcode-terminal declared as optionalDependencies

Files Changed

• packages/squad-cli/src/cli/commands/start.ts — checkNodePty helper + early validation
• packages/squad-cli/package.json — optionalDependencies
• package-lock.json — lockfile update
• CHANGELOG.md — changelog entry
• test/cli-packaging-smoke.test.ts — refactored + node-pty smoke test
• test/cli/start.test.ts — node-pty regression tests
• .changeset/start-tunnel-node-pty.md — changeset

Closes #711

Based on PR #715 by @andikrueger (community contributor)

Co-authored-by: andikrueger
Co-authored-by: Copilot

[github-actions]

🟡 Impact Analysis — PR #860

Risk tier: 🟡 MEDIUM

📊 Summary

Metric	Count
Files changed	6
Files added	1
Files modified	5
Files deleted	0
Modules touched	3
Critical files	1

🎯 Risk Factors

• 6 files changed (6-20 → MEDIUM)
• 3 modules touched (2-4 → MEDIUM)
• Critical files touched: packages/squad-cli/package.json

📦 Modules Affected

root (2 files)

• .changeset/start-tunnel-node-pty.md
• package-lock.json

squad-cli (2 files)

• packages/squad-cli/package.json
• packages/squad-cli/src/cli/commands/start.ts

tests (2 files)

• test/cli-packaging-smoke.test.ts
• test/cli/start.test.ts

⚠️ Critical Files

• packages/squad-cli/package.json

---

This report is generated automatically for every PR. See #733 for details.

[github-actions]

🛫 PR Readiness Check

ℹ️ This comment updates on each push. Last checked: commit 7ffe525

PR Scope: 📦🔧 Mixed (product + infrastructure)

⚠️ 2 item(s) to address before review

Status	Check	Details
✅	Single commit	1 commit — clean history
✅	Not in draft	Ready for review
✅	Branch up to date	Up to date with dev
❌	Copilot review	No Copilot review yet — it may still be processing
✅	Changeset present	Changeset file found
✅	Scope clean	No .squad/ or docs/proposals/ files
✅	No merge conflicts	No merge conflicts
✅	Copilot threads resolved	0 active Copilot thread(s) resolved (1 outdated skipped)
❌	CI passing	16 check(s) still running

Files Changed (6 files, +339 −73)

File	+/−
.changeset/start-tunnel-node-pty.md	+5 −0
package-lock.json	+31 −0
packages/squad-cli/package.json	+4 −0
packages/squad-cli/src/cli/commands/start.ts	+32 −5
test/cli-packaging-smoke.test.ts	+125 −67
test/cli/start.test.ts	+142 −1

Total: +339 −73

---

This check runs automatically on every push. Fix any ❌ items and push again.
See CONTRIBUTING.md and PR Requirements for details.

[github-actions]

🔒 Security Review

🔒 Security review: 1 info.

Severity	Category	Finding	Location
ℹ️ info	new-dependency	2 new/changed dependency version(s) in packages/squad-cli/package.json. Verify these packages are trusted and necessary.	packages/squad-cli/package.json:213

---

Automated security review — informational only.

[Copilot]

Pull request overview

This PR fixes issue #711 by ensuring squad start validates the optional native dependency node-pty before starting any bridge/tunnel work, avoiding side effects (like starting a devtunnel) when node-pty is missing.

Changes:

• Added a checkNodePty() helper and moved node-pty validation to the very start of runStart().
• Declared node-pty and qrcode-terminal as optionalDependencies for @bradygaster/squad-cli.
• Expanded tests: a regression test for validation ordering + packaging smoke coverage for a forced-missing node-pty scenario.

Reviewed changes

Copilot reviewed 6 out of 7 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
packages/squad-cli/src/cli/commands/start.ts	Adds early node-pty validation to prevent tunnel/bridge side effects when the dependency is missing.
packages/squad-cli/package.json	Declares node-pty and qrcode-terminal as optionalDependencies.
package-lock.json	Updates lockfile to include the new optional dependencies.
CHANGELOG.md	Documents the fix and new behavior for squad start --tunnel.
test/cli-packaging-smoke.test.ts	Improves packaging isolation and adds a forced-missing node-pty smoke test.
test/cli/start.test.ts	Adds regression coverage to ensure node-pty validation happens before bridge/tunnel setup.
.changeset/start-tunnel-node-pty.md	Adds a changeset for the CLI patch release.

[tamirdresher]

Approved by @tamirdresher — reviewed diff, CI green, changes are clean and well-tested. cc @diberry