Storm Laravel Package

Product Decisions This Supports

• Build vs. buy on filesystem safety. The highest-value asset is PathResolver (resolve(), within(), join(), standardize()) — an open_basedir-respecting realpath plus a separator-boundary-safe containment check that already carries a CVE-class fix (GHSA-58fp prefix-collision). The decision: never let a team hand-roll realpath() + str_starts_with() for user-supplied paths. Depend on this, vendor the class, or budget explicit review time for a homegrown equivalent.
• Platform vs. app architecture. Storm is the substrate for a plugin/theme platform (Winter CMS). It decides whether you are building an extensible system where third-party code touches your filesystem, or a single-tenant app where Laravel and Symfony already cover ~90% of the need.
• Roadmap scoping for "standard library" work. The AGENTS.md search order (Storm → Laravel → Symfony) is a reusable engineering policy, not just documentation. It supports a roadmap item like "consolidate duplicated helper logic and reduce security-relevant drift" without buying a product.
• AI/agent tooling decisions. If the org is rolling out coding agents, this repo is a concrete template for a canonical-helper guide: a substitution table, grep-first instructions, layering boundaries, and adversarial test requirements. A cheap, high-leverage artifact to copy into your own repos regardless of whether you adopt the code.
• Adoption shape: whole package vs. surgical extraction. With 51 stars and 0 recorded dependents, the decision is almost never "add winter/storm to composer and build on it." It is "vendor PathResolver + Filesystem with tests and MIT attribution," or "use it because Winter CMS is already the platform."
• Ecosystem risk register. Low stars, zero recorded dependents, score ~3.0 — treat as first-party Winter internals with a bus factor near one, not a community library with a support contract. Any dependency decision should come with a pin-and-monitor plan.

When to Consider This Package

Adopt or borrow when:

• You are already on Winter CMS. Storm is in the dependency tree; the correct move is to use its helpers rather than fight or duplicate them.
• You accept user-controlled paths. File managers, theme/template editors, plugin uploads, asset pipelines, media libraries — anywhere a path crosses a trust boundary. PathResolver::within() and resolve() are worth reading even if you never install them.
• You are building an extension platform. Plugin/module systems where foreign code runs against your filesystem, and you need containment, open_basedir respect, and symlink-escape handling as defaults.
• You need Winter-shaped primitives. Halcyon-style file-backed models, YAML/INI/env parsing with Winter semantics, or module-specific helpers (Argon, Flash, Parse/Assetic wrappers) unavailable from Laravel.
• You want the policy, not the code. The agent guide is adoptable on its own as an internal "search before you write" standard.

Look elsewhere when:

• Greenfield Laravel SaaS. Illuminate\Support\Str/Arr/Collection, Illuminate\Filesystem, and Symfony\Component\Finder/Filesystem/Process cover the same table with mainstream documentation, Stack Overflow coverage, and Laravel's release cadence. Storm adds coupling for marginal gain.
• You need exactly one function. Copy the single class with its tests and MIT notice rather than dragging in a CMS-derived dependency graph.
• You need support guarantees. 51 stars and no standalone consumer base means no external bug-finder pool, no semver promise you can lean on in a contract, and security advisories only if Winter's maintainers file them.
• Your team doesn't know Winter's layering rules. The package explicitly forbids depending on Winter modules or plugin code; using it without that discipline inverts its architecture.
• You need modern HTTP/async. Laravel's Http facade (Guzzle) is the answer; Storm's Network module is not a reason to adopt.

How to Pitch It (Stakeholders)

To executives (one paragraph): Winter Storm is a small MIT-licensed utility library extracted from Winter CMS. Its real value isn't breadth — it's that it contains security-hardened filesystem path handling (traversal, prefix-collision, symlink-escape, open_basedir) plus a written policy that stops engineers and AI coding agents from rewriting those primitives badly. Cost of adoption is low and risk is bounded if we scope it surgically: we vendor the two or three classes we actually need rather than taking a hard dependency on the whole CMS substrate. It is not a strategic platform bet — 51 stars and no standalone downstream consumers means we should assume no external support and pin whatever we take.

To engineering: Use PathResolver::within() for every containment check on a user-supplied path; use resolve() instead of realpath() plus null-checks; use the substitution table (Str/Arr/Collection, Symfony Finder/Process/Filesystem) before writing any regex one-liner, loop, or shell_exec. Respect the layering rule — shared helpers live in the shared layer, not the app and not a feature module. If you add a helper, write the adversarial tests first: ../../etc/passwd, /var/www/secret_other against allowed /var/www/secret, symlink escape, Windows separators. Run the full suite before claiming a change is clean.

Framing to avoid: don't position this as "we should adopt Winter CMS." The pitch is "we should not be writing our own path sanitizers or our own helper utilities in 2025 — here's a hardened reference and a policy for where logic belongs." The code is a citation; the policy is the deliverable. Budget roughly one engineer-week for a spike plus narrow adoption (path/FS helpers only, gated by an upgrade-blocking contract test suite), and require a written justification before going any deeper into Halcyon/Argon or the CMS framework itself.