Paragon Laravel Package

Product Decisions This Supports

• Feature scoping: end the frontend/backend vocabulary fork. Paragon generates TypeScript enum artifacts from Laravel/PHP enums, so statuses, roles, tiers, entitlement levels and workflow states stop being re-typed by hand in the frontend. The decision it supports isn't "add a service" — it's a policy call: the backend vocabulary is the source of truth, and the frontend's copy is a build artifact. That's a one-line architecture principle you can put in an ADR and defend in review.
• Build vs. buy, priced honestly. The realistic alternative is a bespoke enum-export script that someone on the team owns forever. Paragon is a thin, MIT-licensed, build-time-only codegen step with no runtime footprint, so the exit cost is roughly an engineer-week to fork or replace. That makes this a reversible bet — the kind of thing a PM can schedule into a sprint without convening an architecture review or opening a vendor negotiation.
• Roadmap hygiene: safe to commit now. v1.2.1 is a patch with no breaking changes, no deprecations, and no new configuration surface. It hardens escaping of string values and method return values in generated enums, closing a malformed-output / injection-style risk when enum values contain quotes, backslashes, newlines or template-literal syntax. Nothing in it forces a migration, so it rides along with normal work rather than competing for roadmap space.
• Defect-class reduction you can quantify. Most enum bugs are "the UI is showing a value the backend retired" or "someone typo'd a literal somewhere." Generation retires that entire class without touching runtime architecture — which makes it an easy reliability win to argue for against an already-full roadmap, and a cheap one to attribute after the fact (count stale-value tickets before and after).
• Contract changes become reviewable diffs. Because generated files are plain text and can be committed, a change to a permission or billing-state vocabulary shows up as a diff in a pull request — not as a surprise in QA or a post-launch incident. That's a governance benefit as much as a technical one: it makes domain vocabulary changes visible to the people who should be signing off on them.
• Operational consequence to plan for, not discover. Escaping behaviour changed in this release, so the version bump must ship in the same change as a regenerated-and-reviewed artifact diff. Don't let the bump land and generated files drift until the next frontend build — that's exactly the gap where a stale artifact becomes a second source of truth.

Resolve before committing roadmap: the package blurb describes application settings as Eloquent-backed classes, while the release notes and surrounding evidence point at PHP-enum-to-TypeScript generation. This assessment assumes the codegen capability, which the release history supports. A one-hour spike against the repo should confirm which product actually ships; the settings use case would be a separate, smaller evaluation with a different value case entirely.

When to Consider This Package

Adopt when:

• You run a PHP/Laravel backend with a JS/TS consumer — SPA, Inertia app, mobile client, or shared design-system package — that duplicates enum values by hand today.
• You already have a build or CI step where generated code can be produced and diff-checked. Paragon is a generator, not a runtime dependency; it needs a pipeline home, not a deployment.
• The vocabulary changes often enough that manual sync has already produced a real defect, or the domain makes staleness expensive (permissions, billing states, workflow statuses, entitlement tiers).
• You want generated files committed and reviewable, so vocabulary changes surface as a diff a product owner can read rather than a runtime surprise.
• You're comfortable treating this as "buy small, fork on exit" — low commitment, low switching cost, no strategic dependency.

Look elsewhere when:

• There's no TS consumer, or the frontend already reads PHP enums directly. You'd be adding a build step for nothing.
• Enum values are dynamic or derived from database rows at runtime. Codegen is the wrong tool for values that change outside a deploy.
• You need a full contract toolchain — OpenAPI, typed API clients, validation generation. Paragon is narrower, and pairing it with a schema-first tool usually means two generators solving overlapping problems and a new source of disagreement.
• Your process has no codegen verification step. Generated files nobody regenerates become a second source of truth and a second source of drift — strictly worse than the status quo you're trying to fix.
• Your PHP/Laravel/Node versions fall outside the supported matrix. Verify rather than assume; this assessment rests on release notes, not a version audit.
• Vendor-risk tolerance is low in the specific domain in question. At 8 stars, 0 dependents and a single primary maintainer, this is an unproven dependency — fine for internal tooling, a harder sell as load-bearing infrastructure for security-critical vocabularies without a fork-and-vendor fallback on file.

On this specific release: v1.2.1 is an upgrade-now for existing adopters — a security-flavoured correctness fix with no migration work. Teams whose enum values are influenced by config or tenant data should prioritise it, since those are the values most likely to carry awkward characters. For non-adopters it doesn't change the build-vs-buy calculus either way.

How to Pitch It (Stakeholders)

For executives (one paragraph): Paragon is a small developer tool that makes our backend the single source of truth for fixed value lists — statuses, roles, tiers, eligibility states — and automatically generates the matching frontend definitions. It removes a recurring class of bug where the application and the interface disagree about how a value is spelled, and it lives entirely in our build step: no runtime service, no vendor contract, no new infrastructure. Adopting it is cheap and easily reversed — it's MIT-licensed and produces plain text, so if the project is ever abandoned we own the replacement in about a week. The release under review, v1.2.1, is a maintenance patch with no breaking changes and no migration cost; it slightly strengthens how generated files handle unusual characters. The one requirement is a process habit: regenerate the files in CI and review the diff before merging. That's a workflow change, not an engineering project, and it's the same discipline we already apply to other generated artifacts.

For engineering:

• Thin build-time codegen layer, zero runtime footprint. Failures surface at build time, not in production, and the blast radius of a bad release is a broken typecheck rather than a broken customer flow — which is why this is safe to trial on one domain vocabulary this sprint.
• v1.2.1 escapes string values and method outputs in generated enums. That fixes malformed TypeScript and removes a code-injection vector when enum values or method return values contain quotes, backslashes, newlines or template-literal syntax. No API or config changes.
• Action: bump to ^1.2.1 as a dev dependency, regenerate, and review the diff in the same PR. Expect changes only in enums containing special characters — anything else moving in that diff is a signal to stop and investigate.
• Add a CI gate that regenerates and fails on a non-empty diff, so drift can't accumulate silently. Run the frontend typecheck and build against the regenerated artifacts as the real acceptance criterion — "the Artisan command exited 0" is not done.
• Pilot on exactly one representative enum — ideally one with a special character — then migrate the rest in batches, one PR per domain area so reviewers can reason about each vocabulary. Enumerate source paths deliberately; broad globs will pull in enums you never intended to publish.
• Keep regression fixtures for quotes, backslashes, newlines and ${} so a future patch can't quietly undo the escaping fix.
• Open questions for the spike: supported PHP/Laravel/TS versions; complete escaping coverage; determinism of method outputs across developer machines and CI; whether a --check/dry-run mode exists for the drift gate; naming and collision policy for TypeScript reserved words and duplicate enum names; and who on our side formally owns the generated artifacts.

Recommendation: adopt for teams with a PHP/TS split and an existing codegen step; upgrade current users to v1.2.1 immediately. Confidence is moderate-plus — the release itself is clearly low-risk, but this assessment rests on release notes, the project has minimal adoption signal, and there's an unresolved discrepancy about which capability the package actually delivers. A short spike (one representative enum, one CI diff check) should precede the roadmap commitment.