@bovinphang/frontend-craft 2.8.0 → 3.0.0

package/skills/fec-refactoring-catalog/references/composition-guide.md

@@ -0,0 +1,49 @@
+# Refactoring Composition Guide
+
+Relationships here are conditional. Apply an edge only when its enabling condition exists and verify every intermediate state.
+
+## Inverse / Trade-off Pairs
+- `RF-EXTRACT-FUNCTION` ↔ `RF-INLINE-FUNCTION`: introduce a meaningful boundary or remove an indirection that no longer pays for itself.
+- `RF-EXTRACT-VARIABLE` ↔ `RF-INLINE-VARIABLE`: name an important expression or remove a name that obscures rather than clarifies.
+- `RF-PULL-UP-METHOD` ↔ `RF-PUSH-DOWN-METHOD`: move behavior toward the level where it is truly shared or specialized.
+- `RF-PULL-UP-FIELD` ↔ `RF-PUSH-DOWN-FIELD`: place data at the narrowest hierarchy level that accurately owns it.
+- `RF-HIDE-DELEGATE` ↔ `RF-REMOVE-MIDDLE-MAN`: trade client coupling against excessive pass-through indirection.
+
+## Common Conditional Sequences
+### Extraction enables ownership movement
+`RF-EXTRACT-FUNCTION` → `RF-MOVE-FUNCTION`
+
+Use when only part of a larger function is dominated by another module’s data. Extract a coherent unit first, then move that unit to the better owner.
+
+### Query extraction enables function extraction
+`RF-REPLACE-TEMP-WITH-QUERY` → `RF-EXTRACT-FUNCTION`
+
+Use when local temporaries make the desired function boundary carry awkward state. Confirm the query is safe to recompute or cache appropriately.
+
+### Type separation enables variant dispatch
+`RF-REPLACE-TYPE-CODE-WITH-SUBCLASSES` → `RF-REPLACE-CONDITIONAL-WITH-POLYMORPHISM`
+
+Use in genuine OO/domain hierarchies. In frontend code, a discriminated union plus strategy/component map may express the same intent without subclasses.
+
+### Regroup then re-extract
+`RF-INLINE-FUNCTION` / `RF-INLINE-CLASS` → regroup scattered logic → `RF-EXTRACT-FUNCTION` / `RF-EXTRACT-CLASS`
+
+Use for Shotgun Surgery caused by poorly placed tiny abstractions. The larger intermediate unit must remain verified.
+
+### Split a process, then place responsibilities
+`RF-SPLIT-PHASE` → `RF-EXTRACT-FUNCTION` → `RF-MOVE-FUNCTION`
+
+Use when a process has separable stages and a stage has a clearer owner after extraction.
+
+### Control a global before changing its representation
+`RF-ENCAPSULATE-VARIABLE` → `RF-RENAME-VARIABLE` / `RF-MOVE-FUNCTION`
+
+Use when a shared variable needs an access seam before changing naming or ownership.
+
+### Encapsulate structured data before its collections
+`RF-ENCAPSULATE-RECORD` → `RF-ENCAPSULATE-COLLECTION`
+
+Use when callers currently manipulate raw record fields and raw collection mutation at the same boundary.
+
+## Stop Conditions
+Do not continue a sequence when the current step fails verification, exceeds its diff budget, changes a public contract unexpectedly, or removes the precondition for the next edge.

package/skills/fec-refactoring-catalog/references/selection-guide.md

@@ -0,0 +1,47 @@
+# Refactoring Selection Guide
+
+Choose by observed cause. The same smell can require different transformations.
+
+## Long Function
+- **Mixed named intentions** → `RF-EXTRACT-FUNCTION`; require a coherent slice and stable inputs/outputs.
+- **Temporaries obstruct extraction** → `RF-REPLACE-TEMP-WITH-QUERY`; avoid when repeated computation is materially expensive or effectful.
+- **Several inputs travel as one concept** → `RF-INTRODUCE-PARAMETER-OBJECT` or `RF-PRESERVE-WHOLE-OBJECT`.
+- **Large conditional varies by type/variant** → first consider `RF-DECOMPOSE-CONDITIONAL`; use `RF-REPLACE-CONDITIONAL-WITH-POLYMORPHISM` only when repeated variant behavior warrants dispatch.
+- **One loop performs unrelated jobs** → `RF-SPLIT-LOOP` when separate passes preserve ordering/performance constraints.
+- **Risk/verification:** preserve exceptions, side effects, event order, hook dependencies, state transitions, and async sequencing.
+
+## Long Parameter List
+- **A value can be derived from another parameter or stable receiver** → `RF-REPLACE-PARAMETER-WITH-QUERY`.
+- **Callers unpack one existing object** → `RF-PRESERVE-WHOLE-OBJECT`.
+- **Values repeatedly travel together as a concept** → `RF-INTRODUCE-PARAMETER-OBJECT`.
+- **A boolean/enum selects behavior** → `RF-REMOVE-FLAG-ARGUMENT`; not for ordinary domain data.
+- **Several functions share the same data context** → `RF-COMBINE-FUNCTIONS-INTO-CLASS`, interpreted as class/module/hook/composable/service according to the codebase.
+- **Risk/verification:** public signatures and callback/component contracts raise compatibility risk.
+
+## Mutable Data
+- **Uncontrolled shared write access** → `RF-ENCAPSULATE-VARIABLE`.
+- **One variable serves multiple meanings** → `RF-SPLIT-VARIABLE`.
+- **A read operation also mutates** → `RF-SEPARATE-QUERY-FROM-MODIFIER`.
+- **Stored derived data drifts** → `RF-REPLACE-DERIVED-VARIABLE-WITH-QUERY`; evaluate recomputation cost and memoization semantics.
+- **Identity is unnecessary and mutation leaks** → consider `RF-CHANGE-REFERENCE-TO-VALUE`.
+- **Risk/verification:** React/Vue identity, reactivity, memoization, subscriptions, and persistence are part of behavior.
+
+## Divergent Change
+- **One function has sequential concerns** → `RF-SPLIT-PHASE` or `RF-EXTRACT-FUNCTION`.
+- **Behavior primarily belongs with another data owner** → `RF-MOVE-FUNCTION`.
+- **A responsibility cluster has its own state and rules** → `RF-EXTRACT-CLASS`, including a frontend module/service/hook/composable equivalent.
+- **Risk/verification:** do not split merely by technical layer if the business responsibility is cohesive.
+
+## Shotgun Surgery
+- **Behavior/data belonging together is scattered** → `RF-MOVE-FUNCTION` / `RF-MOVE-FIELD`.
+- **Many functions share one context** → `RF-COMBINE-FUNCTIONS-INTO-CLASS` or `RF-COMBINE-FUNCTIONS-INTO-TRANSFORM`.
+- **A pipeline has separable stages** → `RF-SPLIT-PHASE`.
+- **Premature tiny abstractions caused scattering** → `RF-INLINE-FUNCTION` / `RF-INLINE-CLASS` may first regroup logic, followed by a better extraction.
+- **Risk/verification:** keep each regrouping step independently behavior-preserving; temporary larger units are acceptable if verified.
+
+## Primitive Obsession
+- **A primitive carries invariants/formatting/domain behavior** → `RF-REPLACE-PRIMITIVE-WITH-OBJECT`; a TypeScript alias alone does not encapsulate runtime behavior.
+- **A type code drives repeated variant behavior** → consider `RF-REPLACE-TYPE-CODE-WITH-SUBCLASSES` or a discriminated-union/strategy equivalent.
+- **Repeated conditional variation is the real problem** → `RF-REPLACE-CONDITIONAL-WITH-POLYMORPHISM` using the most idiomatic dispatch form.
+- **Several primitives form one concept** → `RF-EXTRACT-CLASS` or `RF-INTRODUCE-PARAMETER-OBJECT`.
+- **Risk/verification:** serialized DTOs, URL values, storage, validation, and API payload shape may be public contracts.

package/skills/fec-refactoring-control/SKILL.md

@@ -0,0 +1,25 @@
+---
+name: fec-refactoring-control
+description: Use when behavior-preserving frontend refactoring focuses on conditional complexity, repeated branches, guards, special cases, or internal invariants, and the selected technique needs family-specific mechanics, risks, and JavaScript/TypeScript/React/Vue adaptation.
+---
+
+# Conditional Logic Refactorings
+
+## Overview
+Use this family after evidence identifies a fitting structural transformation. Apply one primary technique at a time and verify immediately.
+
+## Procedure
+1. Confirm the selected technique and its preconditions in [Conditional Logic Refactorings](references/conditional-refactorings.md).
+2. Record affected behavior and a diff budget.
+3. Apply only the selected technique's smallest viable step.
+4. Verify the step before composing another transformation.
+5. Stop and reassess when public contracts, lifecycle, state identity, or actual scope exceed expectations.
+
+## Quick Reference
+The family reference contains 6 canonical techniques with intent, signals, avoid conditions, mechanics, preservation checkpoints, smell links, composition hints, JavaScript/TypeScript notes, React/Vue notes, adaptation guidance, and original frontend examples.
+
+## Common Mistakes
+- Choosing a technique by name without checking its preconditions.
+- Combining several structural intentions in one diff.
+- Assuming a classical class-based form is mandatory in modern frontend code.
+- Treating passing tests as proof when the relevant behavior is not covered.

package/skills/fec-refactoring-control/references/conditional-refactorings.md

@@ -0,0 +1,299 @@
+# Conditional Logic Refactorings
+
+These cards transform the supplied standard catalog into concise operational guidance for frontend agents. Standard IDs/names are preserved; examples and framework adaptations are original.
+
+## RF-DECOMPOSE-CONDITIONAL — Decompose Conditional
+
+### Intent
+Extract a complex condition and its branches into named operations that explain why each path exists.
+
+### Typical Signals
+- A conditional mixes domain predicates with substantial branch calculations.
+
+### Avoid When
+- Do not scatter tiny helpers when the condition is already simple and self-explanatory.
+
+### Preconditions
+- Current observable behavior and affected callers are understood.
+- The target scope is inside a declared diff budget and can be verified after this one primary transformation.
+
+### Mechanics
+1. Extract/name the predicate.
+2. Extract the then branch if it has a distinct purpose.
+3. Extract the else branch if useful.
+4. Verify short-circuiting, side effects, and branch results.
+
+### Behavior-Preservation Checkpoints
+- Compare inputs, outputs, exceptions, side effects, ordering, and public contracts before/after the step.
+- For frontend code, also check UI state, events, focus, network behavior, lifecycle/state transitions, and relevant identity semantics.
+
+### Related Code Smells
+- `SMELL-LONG-FUNCTION`
+
+### Composes Well With
+- Combine only with a separately justified next transformation; no fixed sequence is required.
+
+### JavaScript Notes
+- Preserve short-circuiting, exception timing, side-effect order, and default/fallthrough behavior.
+
+### TypeScript Notes
+- Use discriminated unions and `never` exhaustiveness when they clarify variants; assertions are not a substitute for runtime validation.
+
+### React Notes
+- Guard clauses must not skip loading cleanup or effect teardown; strategy/component registries often fit variant rendering better than classes.
+
+### Vue Notes
+- Preserve `finally`, pending/error state, watcher/effect behavior, and component branch lifecycle.
+
+### Frontend-Craft Adaptation
+- “Polymorphism” includes strategies, discriminated-union dispatch, handler/component registries, and delegation; use class hierarchies only when natural.
+
+### Example Transformation
+Before: a compose permission `if` embeds tenant/date/quota checks and actions. After: use `canSendNow()` plus named branch functions.
+
+## RF-CONSOLIDATE-CONDITIONAL-EXPRESSION — Consolidate Conditional Expression
+
+### Intent
+Combine separate checks that produce the same outcome into one named condition.
+
+### Typical Signals
+- Several adjacent conditions return/assign the same result for one conceptual reason.
+
+### Avoid When
+- Keep conditions separate when they represent different outcomes, logging, or error reasons users must distinguish.
+
+### Preconditions
+- Current observable behavior and affected callers are understood.
+- The target scope is inside a declared diff budget and can be verified after this one primary transformation.
+
+### Mechanics
+1. Confirm branches truly have the same effect.
+2. Combine predicates without changing short-circuit order.
+3. Extract a named predicate when it clarifies purpose.
+4. Verify side effects and error distinctions.
+
+### Behavior-Preservation Checkpoints
+- Compare inputs, outputs, exceptions, side effects, ordering, and public contracts before/after the step.
+- For frontend code, also check UI state, events, focus, network behavior, lifecycle/state transitions, and relevant identity semantics.
+
+### Related Code Smells
+- No single code smell required; select from concrete structural evidence.
+
+### Composes Well With
+- Combine only with a separately justified next transformation; no fixed sequence is required.
+
+### JavaScript Notes
+- Preserve short-circuiting, exception timing, side-effect order, and default/fallthrough behavior.
+
+### TypeScript Notes
+- Use discriminated unions and `never` exhaustiveness when they clarify variants; assertions are not a substitute for runtime validation.
+
+### React Notes
+- Guard clauses must not skip loading cleanup or effect teardown; strategy/component registries often fit variant rendering better than classes.
+
+### Vue Notes
+- Preserve `finally`, pending/error state, watcher/effect behavior, and component branch lifecycle.
+
+### Frontend-Craft Adaptation
+- “Polymorphism” includes strategies, discriminated-union dispatch, handler/component registries, and delegation; use class hierarchies only when natural.
+
+### Example Transformation
+Before: three separate guards all disable Send for the same “draft not sendable” outcome. After: combine only if individual user-facing reasons are not lost.
+
+## RF-REPLACE-NESTED-CONDITIONAL-WITH-GUARD-CLAUSES — Replace Nested Conditional with Guard Clauses
+
+### Intent
+Flatten exceptional or early-exit cases so the main path is visible.
+
+### Typical Signals
+- Nested `if/else` primarily checks invalid/special cases before normal work.
+
+### Avoid When
+- Do not return early before required cleanup, `finally`, loading-state reset, or transaction completion.
+
+### Preconditions
+- Current observable behavior and affected callers are understood.
+- The target scope is inside a declared diff budget and can be verified after this one primary transformation.
+
+### Mechanics
+1. Identify cases that can return/throw early.
+2. Convert the outermost special case to a guard.
+3. Repeat one nesting level at a time.
+4. Verify cleanup, loading state, and finally semantics.
+
+### Behavior-Preservation Checkpoints
+- Compare inputs, outputs, exceptions, side effects, ordering, and public contracts before/after the step.
+- For frontend code, also check UI state, events, focus, network behavior, lifecycle/state transitions, and relevant identity semantics.
+
+### Related Code Smells
+- No single code smell required; select from concrete structural evidence.
+
+### Composes Well With
+- Combine only with a separately justified next transformation; no fixed sequence is required.
+
+### JavaScript Notes
+- Preserve short-circuiting, exception timing, side-effect order, and default/fallthrough behavior.
+
+### TypeScript Notes
+- Use discriminated unions and `never` exhaustiveness when they clarify variants; assertions are not a substitute for runtime validation.
+
+### React Notes
+- Guard clauses must not skip loading cleanup or effect teardown; strategy/component registries often fit variant rendering better than classes.
+
+### Vue Notes
+- Preserve `finally`, pending/error state, watcher/effect behavior, and component branch lifecycle.
+
+### Frontend-Craft Adaptation
+- “Polymorphism” includes strategies, discriminated-union dispatch, handler/component registries, and delegation; use class hierarchies only when natural.
+
+### Example Transformation
+Before: a submit handler nests auth → draft → recipients → send. After: guard invalid states early while preserving `finally { setLoading(false) }`.
+
+## RF-REPLACE-CONDITIONAL-WITH-POLYMORPHISM — Replace Conditional with Polymorphism
+
+### Intent
+Move repeated variant-specific behavior behind a dispatch boundary so each variant owns its behavior.
+
+### Typical Signals
+- The same type/status discriminator drives behavior in several locations.
+
+### Avoid When
+- Do not replace a single clear conditional with a class hierarchy; frontend dispatch may be simpler as a strategy map or discriminated union.
+
+### Preconditions
+- Current observable behavior and affected callers are understood.
+- The target scope is inside a declared diff budget and can be verified after this one primary transformation.
+
+### Mechanics
+1. Identify the stable discriminator and variant behaviors.
+2. Choose an idiomatic dispatch form: strategy map, discriminated union, handler/component registry, delegation, or class hierarchy.
+3. Move one behavior into the dispatch boundary.
+4. Verify exhaustiveness and default/error behavior.
+
+### Behavior-Preservation Checkpoints
+- Compare inputs, outputs, exceptions, side effects, ordering, and public contracts before/after the step.
+- For frontend code, also check UI state, events, focus, network behavior, lifecycle/state transitions, and relevant identity semantics.
+
+### Related Code Smells
+- `SMELL-LONG-FUNCTION`
+- `SMELL-PRIMITIVE-OBSESSION`
+- `SMELL-REPEATED-SWITCHES`
+
+### Composes Well With
+- Combine only with a separately justified next transformation; no fixed sequence is required.
+
+### JavaScript Notes
+- Preserve short-circuiting, exception timing, side-effect order, and default/fallthrough behavior.
+
+### TypeScript Notes
+- Use discriminated unions and `never` exhaustiveness when they clarify variants; assertions are not a substitute for runtime validation.
+
+### React Notes
+- Guard clauses must not skip loading cleanup or effect teardown; strategy/component registries often fit variant rendering better than classes.
+
+### Vue Notes
+- Preserve `finally`, pending/error state, watcher/effect behavior, and component branch lifecycle.
+
+### Frontend-Craft Adaptation
+- “Polymorphism” includes strategies, discriminated-union dispatch, handler/component registries, and delegation; use class hierarchies only when natural.
+
+### Example Transformation
+Before: message type switches appear in rendering and actions. After: a typed handler/component registry dispatches by discriminant; no subclass hierarchy is required.
+
+## RF-INTRODUCE-SPECIAL-CASE — Introduce Special Case
+
+### Intent
+Represent a recurring exceptional value with an object/value that supplies common behavior, reducing repeated checks.
+
+### Typical Signals
+- Many callers repeat the same null/unknown/sentinel handling.
+
+### Avoid When
+- Avoid when special-case behavior varies by caller or hiding absence would obscure an error.
+
+### Preconditions
+- Current observable behavior and affected callers are understood.
+- The target scope is inside a declared diff budget and can be verified after this one primary transformation.
+
+### Mechanics
+1. List repeated checks and common behavior.
+2. Create the special-case representation.
+3. Return it from one boundary and migrate consumers.
+4. Remove duplicated checks only after behavior is equivalent.
+
+### Behavior-Preservation Checkpoints
+- Compare inputs, outputs, exceptions, side effects, ordering, and public contracts before/after the step.
+- For frontend code, also check UI state, events, focus, network behavior, lifecycle/state transitions, and relevant identity semantics.
+
+### Related Code Smells
+- `SMELL-TEMPORARY-FIELD`
+
+### Composes Well With
+- Combine only with a separately justified next transformation; no fixed sequence is required.
+
+### JavaScript Notes
+- Preserve short-circuiting, exception timing, side-effect order, and default/fallthrough behavior.
+
+### TypeScript Notes
+- Use discriminated unions and `never` exhaustiveness when they clarify variants; assertions are not a substitute for runtime validation.
+
+### React Notes
+- Guard clauses must not skip loading cleanup or effect teardown; strategy/component registries often fit variant rendering better than classes.
+
+### Vue Notes
+- Preserve `finally`, pending/error state, watcher/effect behavior, and component branch lifecycle.
+
+### Frontend-Craft Adaptation
+- “Polymorphism” includes strategies, discriminated-union dispatch, handler/component registries, and delegation; use class hierarchies only when natural.
+
+### Example Transformation
+Before: every recipient display checks `contact == null`. After: a stable `UnknownContact`/fallback view model supplies the shared display behavior.
+
+## RF-INTRODUCE-ASSERTION — Introduce Assertion
+
+### Intent
+Make an internal invariant executable where violating it indicates a programming error.
+
+### Typical Signals
+- Code relies on a condition that is assumed but not expressed.
+
+### Avoid When
+- Assertions do not replace user-input validation, network error handling, permissions, or recoverable business errors.
+
+### Preconditions
+- Current observable behavior and affected callers are understood.
+- The target scope is inside a declared diff budget and can be verified after this one primary transformation.
+
+### Mechanics
+1. State the invariant precisely.
+2. Place the assertion at the boundary where the assumption must hold.
+3. Ensure production/runtime assertion policy is understood.
+4. Keep normal validation for expected invalid inputs.
+
+### Behavior-Preservation Checkpoints
+- Compare inputs, outputs, exceptions, side effects, ordering, and public contracts before/after the step.
+- For frontend code, also check UI state, events, focus, network behavior, lifecycle/state transitions, and relevant identity semantics.
+
+### Related Code Smells
+- `SMELL-COMMENTS`
+
+### Composes Well With
+- Combine only with a separately justified next transformation; no fixed sequence is required.
+
+### JavaScript Notes
+- Preserve short-circuiting, exception timing, side-effect order, and default/fallthrough behavior.
+
+### TypeScript Notes
+- Use discriminated unions and `never` exhaustiveness when they clarify variants; assertions are not a substitute for runtime validation.
+
+### React Notes
+- Guard clauses must not skip loading cleanup or effect teardown; strategy/component registries often fit variant rendering better than classes.
+
+### Vue Notes
+- Preserve `finally`, pending/error state, watcher/effect behavior, and component branch lifecycle.
+
+### Frontend-Craft Adaptation
+- “Polymorphism” includes strategies, discriminated-union dispatch, handler/component registries, and delegation; use class hierarchies only when natural.
+
+### Example Transformation
+Before: an internal normalized draft silently assumes at least one recipient. After: assert that invariant after validated construction, not at raw user input.

package/skills/fec-refactoring-data/SKILL.md

@@ -0,0 +1,25 @@
+---
+name: fec-refactoring-data
+description: Use when behavior-preserving frontend refactoring focuses on variable meaning, field naming, derived state, or reference/value identity, and the selected technique needs family-specific mechanics, risks, and JavaScript/TypeScript/React/Vue adaptation.
+---
+
+# Data Refactorings
+
+## Overview
+Use this family after evidence identifies a fitting structural transformation. Apply one primary technique at a time and verify immediately.
+
+## Procedure
+1. Confirm the selected technique and its preconditions in [Data Refactorings](references/data-refactorings.md).
+2. Record affected behavior and a diff budget.
+3. Apply only the selected technique's smallest viable step.
+4. Verify the step before composing another transformation.
+5. Stop and reassess when public contracts, lifecycle, state identity, or actual scope exceed expectations.
+
+## Quick Reference
+The family reference contains 5 canonical techniques with intent, signals, avoid conditions, mechanics, preservation checkpoints, smell links, composition hints, JavaScript/TypeScript notes, React/Vue notes, adaptation guidance, and original frontend examples.
+
+## Common Mistakes
+- Choosing a technique by name without checking its preconditions.
+- Combining several structural intentions in one diff.
+- Assuming a classical class-based form is mandatory in modern frontend code.
+- Treating passing tests as proof when the relevant behavior is not covered.