Scotty Laravel Package

Product Decisions This Supports

• Build vs. buy vs. adopt — deployment tasking layer. Scotty is the cheapest credible answer to "who owns our deploy runbook?" It replaces a hand-rolled deploy.sh + ssh wrapper (maintenance burden, tribal knowledge, no dry-run, no output discipline) without buying a deployment platform. The decision it unblocks is narrow and real: do we keep paying engineering time to maintain bespoke SSH glue, or adopt a 1-file tool that does the same job with --pretend, --continue, --summary, and readable output?
• Laravel Envoy migration/retirement. The stated drop-in compatibility is a roadmap item in disguise: it lets you schedule "remove Envoy from the toolchain" as a low-risk, reversible line item rather than a platform migration. That's a deprecation decision a PM can actually get prioritized, because the overlap window is two tools running against the same staging host — not a cutover.
• Scope boundary: deploy tasking vs. deploy orchestration. The most valuable decision this package forces is a scoping one. Scotty runs commands in place; it does not manage release directories, symlink switching, atomic rollback, or config drift. Deciding explicitly that those stay out of scope (owned by a real CI/CD stage or a release tool) prevents the classic failure where "we adopted a deploy tool" becomes a six-month expectation gap. Use this assessment to close that question in writing.
• Incident-response and runbook tooling on the roadmap. --pretend for review-before-execution, --continue and timestamped completion/failure messages, and scotty doctor for pre-flight connectivity/macro validation map directly to on-call needs. This is a candidate for a "reduce incident MTTR / reduce fat-finger risk" initiative with a measurable claim: dry-run output becomes the review artifact, and connectivity failures surface before the incident rather than during it.
• CI/CD output-mode decisions. --summary exists precisely because CI wants pass/fail, humans want verbose. That's a per-environment default decision (verbose locally, summary in CI) worth capturing once instead of re-litigating per pipeline.
• Tooling investment triage for small fleets. For roughly 1–10 Laravel/PHP servers deployed over SSH by a team that already reads bash, this is a "do it this sprint" item, not a roadmap quarter. The decision it supports is allocation: reclaim the maintenance hours without opening a platform budget line.

When to Consider This Package

Adopt when all of these hold:

• Laravel/PHP monolith (or a small set of them) on a small fleet — call it 1–10 hosts — deployed over SSH.
• The team already holds SSH credentials to those hosts and is comfortable reading bash. Scotty makes existing access more disciplined, not more restricted; it does not solve secrets distribution, key rotation, or least-privilege.
• You already have, or are willing to write, an Envoy.blade.php or Scotty.sh — i.e. the workflow exists and is being maintained by hand.
• You want the deploy tasking layer solved, and have a separate answer (or an accepted gap) for release directories, atomic rollback, and drift.
• You need a dry-run and pre-flight story (--pretend, doctor) more than you need approvals, audit trails, or artifact promotion.

Look elsewhere when:

• The requirement is a managed CI/CD stage with approvals, centralized secrets, artifact promotion, and audit trails. Scotty is structurally the wrong shape — it's a client-side runner, not a control plane. Buying/adopting a platform is the correct call and this package shouldn't delay it.
• The real audit finding is long-lived SSH from laptops. Scotty improves discipline; it doesn't remediate the finding. Address access architecture first.
• Windows-first, bash-averse, or declarative-config-oriented teams. Bash literacy is a hard prerequisite, and the alternative Blade format is not at parity — @option is unavailable there per the docs. Two formats with different feature sets is an adoption wrinkle to price in, not a footnote.
• You need zero-downtime releases, idempotency, or configuration management. That's a different category of tool.
• Support-scaling is a hard constraint. Single primary maintainer, 292 stars, steady but low-volume 1.x cadence. Spatie's reputation and docs are strong, and zero dependents is a library-shaped metric that should not veto a CLI-shaped decision — but if you require a vendor SLA or multi-contributor bus factor, this fails that test.
• Pin to 1.4.x or later if you need nested macros (1.3.0), custom SSH ports via host:port (1.4.0), or working Blade hooks — 1.4.4 fixed @before/@after/@error/@success/@finished hooks that previously failed silently. That silent-failure history is the single highest-risk unknown; verify hook behavior explicitly in pilot rather than trusting the compatibility claim.

How to Pitch It (Stakeholders)

To executives — one paragraph: We spend engineering hours maintaining a hand-rolled SSH deploy script that has no dry-run, no pre-flight validation, and inconsistent output. Scotty is a single-file, MIT-licensed CLI from Spatie (a well-known PHP vendor) that does that job properly — written bash task definitions, one-command execution across our servers, a dry-run mode we can review before touching production, and pre-flight connectivity checks. Adoption cost is one binary and one script in the repo; no agent, no daemon, no database, no contract. It's a reversible experiment, not a platform migration, and it lets us retire Laravel Envoy as a follow-on. What it is not: it does not give us zero-downtime releases, rollback, or centralized secrets — we are explicitly not buying that with this, and if we need it, it's a separate decision.

To engineering — the substance: Install is trivial (phar into the repo, phar on $PATH, or composer global require spatie/scotty). Tasks are plain bash with annotation comments (@servers, @task, @macro, @option) — no DSL, and editors highlight it for free. Self-contained phar means no PHP extension or runtime negotiation. Sequence: pilot in one repo → scotty doctor before anything real → --pretend on the full deploy macro as the review artifact → port the Envoy.blade.php and run both against staging, diffing observed effects rather than trusting the drop-in claim → move to CI with --summary → deprecate Envoy after one full cycle. Keep routine deploy adoption ahead of incident-runbook adoption; don't try to land both at once. Pick one canonical format (Scotty.sh or Envoy.blade.php) up front to avoid the @option parity surprise.

The one sentence to get a decision: This is a one-file, reversible pilot that removes a maintenance burden and gives us a reviewable dry-run — approve it for one repo, and we'll bring back staging parity results before it touches production.