@dynokostya/just-works 1.0.0

package/.claude/skills/python-coding/SKILL.md

@@ -0,0 +1,293 @@
+---
+name: python-coding
+description: Apply when writing or editing Python (.py) files. Behavioral corrections for error handling, resource management, async patterns, data modeling, type safety, security defaults, and common antipatterns. Project conventions always override these defaults.
+---
+
+# Python Coding
+
+Match the project's existing conventions. When uncertain, read 2-3 existing modules to infer the local style. Check `pyproject.toml` for Python version target, linter config, and tooling. These defaults apply only when the project has no established convention.
+
+## Never rules
+
+These are unconditional. They prevent bugs and vulnerabilities regardless of project style.
+
+- **Never `except: pass`** or bare `except Exception` without re-raise. Catch specific exception types. Broad catches silently swallow bugs — a `KeyError` from a typo looks the same as a network failure, and you'll spend hours debugging something the traceback would have told you instantly.
+- **Never `datetime.now()` or `datetime.utcnow()`** -- both produce naive datetimes that lose timezone info. Naive datetimes cause subtle bugs when code crosses timezone boundaries (servers, users, DST). Use `datetime.now(tz=timezone.utc)`. Use `zoneinfo.ZoneInfo` for other timezones, not `pytz`.
+- **Never `random` for security** -- `random` uses a predictable PRNG; an attacker who observes a few outputs can predict future ones. Use `secrets.token_hex()`, `secrets.token_urlsafe()`, or `secrets.token_bytes()` for tokens, keys, session IDs.
+- **Never `shell=True` in `subprocess`** -- shell interpretation enables command injection if any argument contains user input. Use argument lists: `subprocess.run(["cmd", arg1, arg2])`.
+- **Never string formatting in SQL** -- SQL injection is one of the most exploited vulnerabilities. Use parameterized queries only. `f"SELECT * FROM users WHERE id = {uid}"` is always a defect.
+- **Never `yaml.load()`** without `SafeLoader` -- use `yaml.safe_load()`. Unsafe YAML loading deserializes arbitrary Python objects, enabling remote code execution from a crafted YAML file.
+- **Never `pickle.load()` on untrusted data** -- pickle executes arbitrary code during deserialization by design. Use JSON, MessagePack, or Protocol Buffers for data interchange.
+- **Never `eval()` or `exec()` on external input** -- use `ast.literal_eval()` for safe evaluation of literals.
+- **Never mutable default arguments** -- `def f(items=[])` shares one list across all calls. Appending in one call mutates the default for every subsequent call. Use `None` sentinel: `def f(items: list[str] | None = None)` then `items = items or []`.
+- **Never shadow builtins** -- don't use `list`, `dict`, `id`, `type`, `input`, `hash`, `map`, `set`, `filter` as variable names. Shadowing causes confusing errors when you later need the builtin in the same scope.
+- **Never blocking calls in async** -- no `time.sleep()`, bare `open()`, or `requests.get()` inside `async def`. These block the entire event loop, freezing all concurrent tasks. Use `asyncio.sleep()`, `aiofiles`, `httpx`.
+- **Never `+=` string concatenation in loops** -- use `"".join(parts)`. Python strings are immutable, so each `+=` allocates a new string and copies all previous content — O(n²) at scale. At 10k iterations this turns milliseconds into seconds.
+
+## Error handling
+
+Always use `raise ... from e` when re-raising at I/O boundaries. This preserves the original traceback -- essential for production debugging. Use `raise ... from None` only when the original exception is genuinely irrelevant to the caller.
+
+```python
+async def get_user(user_id: int) -> User:
+    try:
+        result = await db.fetchrow("SELECT * FROM users WHERE id = $1", user_id)
+    except asyncpg.PostgresError as e:
+        raise DatabaseError(f"Failed to query user {user_id}") from e
+    if result is None:
+        raise UserNotFoundError(user_id)
+    return User(**result)
+```
+
+Create custom exception types when callers need to distinguish failure modes:
+
+```python
+class AppError(Exception):
+    """Base exception."""
+
+class NotFoundError(AppError):
+    def __init__(self, resource: str, id: Any) -> None:
+        self.resource = resource
+        self.id = id
+        super().__init__(f"{resource} not found: {id}")
+```
+
+When logging a caught exception, always preserve the traceback:
+
+```python
+# Wrong: traceback lost
+except httpx.HTTPStatusError as e:
+    logger.error(f"API call failed: {e}")
+    raise
+
+# Correct: logger.exception() includes full traceback
+except httpx.HTTPStatusError:
+    logger.exception("API call failed")
+    raise
+```
+
+Use `exc_info=True` for non-error log levels: `logger.warning("retrying", exc_info=True)`.
+
+## Resource cleanup
+
+Use context managers for anything that needs cleanup -- clients, connections, file handles. Never instantiate `httpx.AsyncClient()`, database pools, or similar without a context manager or explicit `finally` cleanup.
+
+For managing multiple async resources, use `AsyncExitStack`:
+
+```python
+from contextlib import AsyncExitStack
+
+async def setup_resources() -> AsyncIterator[Resources]:
+    async with AsyncExitStack() as stack:
+        db = await stack.enter_async_context(create_pool(dsn))
+        cache = await stack.enter_async_context(create_redis(url))
+        yield Resources(db=db, cache=cache)
+```
+
+For custom resource lifecycles where no built-in context manager exists:
+
+```python
+from contextlib import asynccontextmanager
+
+@asynccontextmanager
+async def managed_session(config: Config) -> AsyncIterator[Session]:
+    session = await Session.connect(config)
+    try:
+        yield session
+    finally:
+        await session.disconnect()
+```
+
+## Async patterns
+
+**Prefer `TaskGroup` (3.11+) over `gather` for most concurrent work.** TaskGroup enforces structured concurrency: if one task fails, siblings are cancelled and errors are raised as `ExceptionGroup`. `gather(return_exceptions=True)` silently mixes exceptions into results, which is error-prone. Use `gather` when you genuinely need partial results despite failures, or when targeting Python < 3.11.
+
+```python
+async with asyncio.TaskGroup() as tg:
+    task1 = tg.create_task(fetch_users())
+    task2 = tg.create_task(fetch_orders())
+# Both guaranteed complete here. If either failed, ExceptionGroup is raised.
+
+# Handle multiple failure types with except*
+try:
+    async with asyncio.TaskGroup() as tg:
+        tg.create_task(operation_a())
+        tg.create_task(operation_b())
+except* ConnectionError as eg:
+    for exc in eg.exceptions:
+        logger.error(f"Connection failed: {exc}")
+except* ValueError as eg:
+    for exc in eg.exceptions:
+        logger.error(f"Validation failed: {exc}")
+```
+
+Share a single `AsyncClient` across concurrent requests -- don't create one per call. Configure timeouts explicitly:
+
+```python
+async with httpx.AsyncClient(base_url="https://api.example.com", timeout=30.0) as client:
+    async with asyncio.TaskGroup() as tg:
+        task1 = tg.create_task(client.get("/users"))
+        task2 = tg.create_task(client.get("/orders"))
+```
+
+## Type hints
+
+Use modern syntax: `list[str]`, `dict[str, Any]`, `X | None`. Use native type parameter syntax when the project targets 3.12+; fall back to `TypeVar` for older targets.
+
+```python
+class Repository[T]:
+    def __init__(self, model_class: type[T]) -> None:
+        self._model_class = model_class
+        self._items: dict[int, T] = {}
+
+    def get(self, id: int) -> T | None:
+        return self._items.get(id)
+```
+
+**Use `object` instead of `Any`** when you mean "accepts anything." `Any` silently disables type checking -- it's a hole in type safety. Reserve `Any` for when the type system genuinely cannot express something.
+
+**Covariant inputs, concrete outputs.** Function parameters should accept abstract types (`Sequence`, `Mapping`, `Iterable`); return types should be concrete (`list`, `dict`):
+
+```python
+from collections.abc import Sequence, Mapping
+
+def process_items(items: Sequence[str]) -> list[str]:  # accepts tuple, list, etc.
+    return [item.upper() for item in items]
+
+def merge_configs(base: Mapping[str, Any], override: Mapping[str, Any]) -> dict[str, Any]:
+    return {**base, **override}
+```
+
+**Use `TYPE_CHECKING` for import-only types.** When a type is only needed for annotations (not at runtime), import it under `TYPE_CHECKING` to avoid circular imports and reduce startup cost:
+
+```python
+from __future__ import annotations
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from myapp.services import PaymentService
+
+class OrderProcessor:
+    def __init__(self, payments: PaymentService) -> None:
+        self._payments = payments
+```
+
+## Pattern matching
+
+Use `match`/`case` (3.10+) when branching on structure — it's clearer than if/elif chains for destructuring dicts, tuples, or typed objects. Don't use it as a substitute for simple value comparisons where `if/elif` reads fine.
+
+```python
+match event:
+    case {"type": "click", "target": target}:
+        handle_click(target)
+    case {"type": "scroll", "offset": int(offset)} if offset > 0:
+        handle_scroll(offset)
+    case _:
+        logger.warning("Unhandled event: %s", event.get("type"))
+```
+
+## Data modeling
+
+| Use Case | Choice | Reason |
+|----------|--------|--------|
+| API request/response | Pydantic | Validation, serialization, OpenAPI |
+| Config from env/files | Pydantic | Built-in settings management |
+| Internal data transfer | dataclass | Lighter weight, no runtime validation |
+| Simple value objects | dataclass | Minimal boilerplate |
+
+Pydantic at system boundaries:
+
+```python
+class UserCreate(BaseModel):
+    email: str = Field(..., min_length=5)
+    name: str = Field(..., min_length=1, max_length=100)
+
+class UserResponse(BaseModel):
+    id: int
+    email: str
+    model_config = {"from_attributes": True}
+```
+
+Dataclasses internally. Use `frozen=True` for value objects, `slots=True` when you have many instances:
+
+```python
+@dataclass(frozen=True, slots=True)
+class CacheKey:
+    namespace: str
+    id: str
+```
+
+## Dependency injection
+
+Constructor injection. Dependencies are explicit, testable, and swappable.
+
+```python
+class UserService:
+    def __init__(self, repository: UserRepository, email_client: EmailClient) -> None:
+        self._repository = repository
+        self._email_client = email_client
+```
+
+## Protocol
+
+Use Protocol for structural interfaces -- duck typing with full type safety, no inheritance required.
+
+```python
+from typing import Protocol, runtime_checkable
+
+@runtime_checkable
+class Serializable(Protocol):
+    def to_dict(self) -> dict[str, Any]: ...
+```
+
+## Enums
+
+Use `StrEnum` instead of raw string literals for known value sets. Catches typos at type-check time. Use `IntEnum` only when interfacing with systems that require integer codes.
+
+```python
+from enum import StrEnum, unique
+
+@unique
+class OrderStatus(StrEnum):
+    PENDING = "pending"
+    CONFIRMED = "confirmed"
+    SHIPPED = "shipped"
+```
+
+## Imports
+
+Import order: standard library, third-party, local. Define `__all__` if the project convention uses it. Use `pathlib.Path` over `os.path`. No import-time side effects -- don't connect to databases, read files, or run computations at module level. Defer to first use.
+
+## Retry logic
+
+Use tenacity for transient errors: network failures, rate limits, 5xx responses. Let 4xx errors propagate -- they indicate a request problem, not a transient failure.
+
+```python
+@retry(
+    retry=retry_if_exception_type((httpx.RequestError, httpx.HTTPStatusError)),
+    stop=stop_after_attempt(3),
+    wait=wait_exponential(multiplier=1, min=2, max=10),
+    before_sleep=before_sleep_log(logger, logging.WARNING),
+    reraise=True,
+)
+async def fetch_with_retry(url: str) -> dict[str, Any]:
+    async with httpx.AsyncClient() as client:
+        response = await client.get(url, timeout=30.0)
+        response.raise_for_status()
+        return response.json()
+```
+
+## Logging
+
+Match the project's logging library (stdlib `logging`, `structlog`, etc.). With stdlib, use `__name__` and pass structured data via `extra`:
+
+```python
+logger = logging.getLogger(__name__)
+logger.info("User created", extra={"user_id": user.id})
+```
+
+## Testing
+
+Match the project's test runner and async plugin. Check for `pytest-asyncio` `mode = "auto"` (no manual `@pytest.mark.asyncio` needed) or `anyio`-based setup.
+
+When to mock: external APIs with rate limits/costs, error paths, deterministic results. When to use real services: verifying actual integration behavior, sandbox/test modes available. Test behavior, not implementation -- test what a function returns, not how it does it internally.

package/.claude/skills/react-coding/SKILL.md

@@ -0,0 +1,264 @@
+---
+name: react-coding
+description: Apply when writing or editing React (.tsx/.jsx) files. Behavioral corrections for hooks, state management, component structure, memoization, security, and common antipatterns. Project conventions always override these defaults.
+---
+
+# React Coding
+
+Match the project's existing conventions. When uncertain, read 2-3 existing components to infer the local style. Check `tsconfig.json` for strictness settings, `package.json` for React version, and framework config (Next.js, Remix, Vite) for routing and rendering conventions. These defaults apply only when the project has no established convention.
+
+## Never rules
+
+These are unconditional. They prevent bugs, wasted renders, and vulnerabilities regardless of project style.
+
+- **Never `useEffect` for derived state** -- if a value can be computed from props or state, compute it during render. `useEffect` + `setState` for derivable values causes an unnecessary extra render cycle. This is the most common React mistake.
+
+```tsx
+// Wrong: extra render cycle for a value computable from props
+const [fullName, setFullName] = useState("");
+useEffect(() => {
+  setFullName(`${first} ${last}`);
+}, [first, last]);
+
+// Correct: compute during render
+const fullName = `${first} ${last}`;
+```
+
+- **Never `useEffect` for event-driven logic** -- user-triggered actions belong in event handlers, not effects keyed to state flags. Effects are for synchronizing with external systems.
+
+```tsx
+// Wrong: effect triggered by state flag
+const [submitted, setSubmitted] = useState(false);
+useEffect(() => {
+  if (submitted) sendAnalytics();
+}, [submitted]);
+
+// Correct: logic in the event handler
+function handleSubmit() {
+  sendAnalytics();
+  navigate("/done");
+}
+```
+
+- **Never fetch data in `useEffect` without cleanup** -- missing `AbortController` causes race conditions on rapid prop changes. Prefer TanStack Query or framework data fetching over raw `useEffect` fetching entirely.
+
+```tsx
+// Wrong: no abort, race condition on rapid userId changes
+useEffect(() => {
+  fetch(`/api/users/${userId}`).then(r => r.json()).then(setUser);
+}, [userId]);
+
+// Correct: AbortController for cleanup
+useEffect(() => {
+  const controller = new AbortController();
+  fetch(`/api/users/${userId}`, { signal: controller.signal })
+    .then(r => r.json())
+    .then(setUser)
+    .catch(e => { if (e.name !== "AbortError") throw e; });
+  return () => controller.abort();
+}, [userId]);
+
+// Best: TanStack Query handles caching, deduplication, and cancellation
+const { data: user } = useQuery({
+  queryKey: ["user", userId],
+  queryFn: () => fetchUser(userId),
+});
+```
+
+- **Never chain `useEffect` calls that sync state to other state** -- cascading effects create render waterfalls (render, effect, setState, render, effect, setState…). Each link in the chain adds a full render cycle, so three chained effects means four renders for one user action — visible jank and wasted CPU. Compute derived values inline or batch updates in event handlers.
+
+- **Never mutate state directly** -- React detects changes by reference. `array.push()` and `obj.prop = x` won't trigger re-renders. Use spread, `structuredClone`, or non-mutating methods like `.toSorted()` (not `.sort()` which mutates).
+
+```tsx
+// Wrong: mutates existing array, React sees same reference
+items.push(newItem);
+setItems(items);
+
+// Correct: new array reference, non-mutating sort
+setItems([...items, newItem].toSorted((a, b) => a.name.localeCompare(b.name)));
+```
+
+- **Never use array index as `key` for dynamic lists** -- index keys cause React to reuse DOM nodes incorrectly when items are reordered, inserted, or removed, corrupting component state. Use stable unique IDs.
+
+```tsx
+// Wrong: index key breaks on reorder/insert/delete
+{items.map((item, i) => <ListItem key={i} item={item} />)}
+
+// Correct: stable unique ID
+{items.map(item => <ListItem key={item.id} item={item} />)}
+```
+
+- **Never add `"use client"` by default** -- in Next.js App Router, components are Server Components by default. Adding `"use client"` unnecessarily pushes components and their entire subtree to the client bundle, losing server-side rendering, data fetching, and streaming benefits. Only add it when the component uses hooks (`useState`, `useEffect`), event handlers, or browser APIs. Place the boundary as low in the tree as possible.
+
+- **Never use `forwardRef` in React 19+** -- `ref` is a regular prop in React 19+. `forwardRef` is deprecated. In React 18, `forwardRef` is still required.
+
+```tsx
+// Wrong (React 19): forwardRef is deprecated
+const Input = forwardRef<HTMLInputElement, InputProps>((props, ref) => (
+  <input ref={ref} {...props} />
+));
+
+// Correct (React 19): ref is a regular prop
+function Input({ ref, ...props }: InputProps & { ref?: React.Ref<HTMLInputElement> }) {
+  return <input ref={ref} {...props} />;
+}
+
+// React 18: forwardRef is still required
+const Input = forwardRef<HTMLInputElement, InputProps>((props, ref) => (
+  <input ref={ref} {...props} />
+));
+```
+
+- **Never define components inside other components** -- the inner component is recreated every render, destroying all state and DOM on each cycle.
+
+```tsx
+// Wrong: Child is a new component identity every render
+function Parent() {
+  function Child() { return <div>child</div>; }
+  return <Child />;
+}
+
+// Correct: Child defined outside
+function Child() { return <div>child</div>; }
+function Parent() { return <Child />; }
+```
+
+- **Never suppress `react-hooks/exhaustive-deps`** -- `eslint-disable` for this rule masks stale closures, where an effect captures an old value of a prop or state and silently operates on outdated data. The resulting bugs are intermittent and hard to trace because the component appears to work until a specific re-render order exposes the stale value. Fix the code: extract functions, use updater functions for state, or move objects inside the effect.
+
+- **Never mirror props in state** -- `useState(prop)` captures the initial value only. Subsequent prop changes are silently ignored. Use the prop directly, or name it `initialX` to signal intent.
+
+```tsx
+// Wrong: color prop changes are silently ignored after mount
+function Badge({ color }: { color: string }) {
+  const [badgeColor, setBadgeColor] = useState(color);
+  return <span style={{ color: badgeColor }}>badge</span>;
+}
+
+// Correct: use the prop directly
+function Badge({ color }: { color: string }) {
+  return <span style={{ color }}>badge</span>;
+}
+```
+
+- **Never use `useEffect` to reset state on prop change** -- use the `key` prop to unmount/remount the component, which resets all state automatically.
+
+```tsx
+// Wrong: effect to reset state when userId changes
+function Profile({ userId }: { userId: string }) {
+  const [comment, setComment] = useState("");
+  useEffect(() => { setComment(""); }, [userId]);
+  return <textarea value={comment} onChange={e => setComment(e.target.value)} />;
+}
+
+// Correct: key forces remount, all state resets
+<Profile key={userId} userId={userId} />
+```
+
+- **Never generate class components** -- all modern React features (Server Components, Suspense, hooks, React Compiler) require function components. The only exception: error boundaries (which still require class components or `react-error-boundary`).
+
+- **Never use `dangerouslySetInnerHTML` without sanitization** -- renders raw HTML, enabling XSS attacks. Always sanitize with DOMPurify or similar. Prefer React's built-in escaping over raw HTML injection entirely.
+
+```tsx
+// Wrong: unsanitized HTML injection
+<div dangerouslySetInnerHTML={{ __html: userContent }} />
+
+// Correct: sanitize first
+import DOMPurify from "dompurify";
+<div dangerouslySetInnerHTML={{ __html: DOMPurify.sanitize(userContent) }} />
+```
+
+- **Never use `React.lazy` without a `<Suspense>` boundary** -- lazy components suspend during loading. Without `<Suspense>`, the thrown promise is unhandled and crashes the app. Wrap with `<Suspense>` and an error boundary.
+
+```tsx
+// Wrong: no Suspense boundary, crashes on load
+const Dashboard = lazy(() => import("./Dashboard"));
+function App() { return <Dashboard />; }
+
+// Correct: Suspense with fallback and error boundary
+const Dashboard = lazy(() => import("./Dashboard"));
+function App() {
+  return (
+    <ErrorBoundary fallback={<p>Something went wrong.</p>}>
+      <Suspense fallback={<p>Loading...</p>}>
+        <Dashboard />
+      </Suspense>
+    </ErrorBoundary>
+  );
+}
+```
+
+## Memoization
+
+**With React Compiler (v19.x + compiler enabled):** The compiler auto-memoizes components, hooks, and JSX elements. Remove manual `useMemo`, `useCallback`, and `React.memo` -- they add noise and the compiler may deopt on components where it cannot preserve manual memoization. Let the compiler handle it.
+
+**Without React Compiler:** Memoize at measured bottlenecks only. Don't wrap everything in `useMemo`/`useCallback`/`React.memo` preemptively. When you do memoize, avoid creating new object/array literals in JSX props to memoized children -- `style={{ color: "red" }}` creates a new reference every render, defeating `React.memo`. Hoist static objects outside the component.
+
+```tsx
+// Wrong: new style object every render defeats React.memo on Child
+function Parent() {
+  return <MemoizedChild style={{ color: "red" }} />;
+}
+
+// Correct: hoist static objects outside the component
+const childStyle = { color: "red" } as const;
+function Parent() {
+  return <MemoizedChild style={childStyle} />;
+}
+```
+
+## Hooks
+
+Rules of hooks -- no exceptions:
+- Call hooks at the top level of function components and custom hooks only.
+- Never call hooks inside conditions, loops, nested functions, `try`/`catch`, or after early returns.
+- The `use()` API (React 19) is the exception -- it can be called conditionally.
+
+**`useEffect` decision tree -- ask before writing any effect:**
+
+1. Can the value be computed from existing props/state? Compute during render.
+2. Is this responding to a user event? Put it in the event handler.
+3. Do you need to reset state when a prop changes? Use `key` on the component.
+4. Do you need to sync with an external system (DOM, network, third-party widget)? This is a valid `useEffect`. Add cleanup.
+5. Do you need to fetch data? Prefer framework data fetching or TanStack Query. If raw `useEffect`, always use `AbortController`.
+
+## Component typing
+
+**Prefer typed function declarations over `React.FC`.** `React.FC` is no longer broken (implicit `children` was removed in React 18 types), but plain function declarations are clearer, support generics naturally, and are the community standard.
+
+```tsx
+interface UserCardProps {
+  user: User;
+  onSelect: (id: string) => void;
+  variant?: "compact" | "full";
+}
+
+function UserCard({ user, onSelect, variant = "full" }: UserCardProps) {
+  return ( /* JSX */ );
+}
+```
+
+Generic components:
+
+```tsx
+function List<T>({ items, renderItem, keyExtractor }: {
+  items: T[];
+  renderItem: (item: T) => React.ReactNode;
+  keyExtractor: (item: T) => string;
+}) {
+  return (
+    <ul>
+      {items.map(item => (
+        <li key={keyExtractor(item)}>{renderItem(item)}</li>
+      ))}
+    </ul>
+  );
+}
+```
+
+Use discriminated unions for impossible states:
+
+```tsx
+type ButtonProps =
+  | { variant: "link"; href: string; onClick?: never }
+  | { variant: "button"; onClick: () => void; href?: never };
+```