@dsalazardev/ai-hub-cli 0.0.0-stage → 0.1.0

package/skills/shared/python/references/async.md

@@ -0,0 +1,136 @@
+# Async (language level) — deep dive
+
+Read when the SKILL.md async section is not enough: the runtime model, structured concurrency,
+timeouts, cancellation discipline, queues, sync<->async bridging, and the IO-bound vs CPU-bound
+decision. HTTP servers are out of scope here -> `fastapi`.
+
+## Runtime model
+
+One event loop per thread runs coroutines cooperatively: a coroutine runs until it `await`s,
+which yields control back to the loop. `asyncio.run(main())` creates the loop, runs the top
+coroutine to completion, and tears the loop down — call it **once**, at the program entry point.
+Never create nested loops or call `asyncio.run` from inside a running loop.
+
+A coroutine only makes progress at `await` points. A blocking call (`time.sleep`, a sync DB
+driver, heavy CPU) between awaits freezes the *entire* loop, including unrelated tasks.
+
+## Structured concurrency: TaskGroup vs gather
+
+`asyncio.TaskGroup` (3.11+) is the default for running tasks concurrently. Its contract:
+
+- Tasks created via `tg.create_task(...)` are all awaited at the end of the `async with` block.
+- If any task raises, the remaining tasks are **cancelled**, and the errors surface as an
+  `ExceptionGroup` (handle with `except*`).
+- No task outlives the block — there is no leak window.
+
+```python
+import asyncio
+
+async def fetch_all(ids: list[int]) -> list[bytes]:
+    async with asyncio.TaskGroup() as tg:
+        tasks = [tg.create_task(fetch(i)) for i in ids]
+    return [t.result() for t in tasks]   # reached only if all succeeded
+
+async def fetch_all_handled(ids: list[int]) -> list[bytes]:
+    try:
+        return await fetch_all(ids)
+    except* ConnectionError as eg:
+        for exc in eg.exceptions:        # ExceptionGroup members
+            log.warning("fetch failed: %s", exc)
+        return []
+```
+
+`asyncio.gather` has no sibling cancellation: on first failure the other tasks keep running
+detached. Reserve `gather(..., return_exceptions=True)` only for the deliberate "run all, collect
+every result-or-error" case where partial failure is acceptable and you process the list yourself.
+
+## Timeouts
+
+Bound every wait. `asyncio.timeout` (3.11+) is a context manager; on expiry it cancels the body
+and raises `TimeoutError`:
+
+```python
+async def with_deadline() -> bytes:
+    async with asyncio.timeout(5.0):
+        return await slow_fetch()
+
+# Or wrap a single coroutine:
+result = await asyncio.wait_for(slow_fetch(), timeout=5.0)
+```
+
+`asyncio.timeout_at(loop.time() + 5)` for an absolute deadline you thread through nested calls.
+
+## Cancellation discipline
+
+Cancellation is delivered as `CancelledError` raised at the current `await`. The rule:
+**clean up, then re-raise** — never swallow it, or you break cancellation for the whole tree.
+
+```python
+async def worker(q: asyncio.Queue[int]) -> None:
+    try:
+        while True:
+            item = await q.get()
+            await handle(item)
+    except asyncio.CancelledError:
+        await flush()        # cleanup is fine
+        raise                # MUST re-raise
+```
+
+If you must run shielded cleanup that itself awaits, use `asyncio.shield(...)` sparingly — it is
+easy to leak with. Prefer making cleanup synchronous or fast.
+
+## Queues
+
+`asyncio.Queue` is the producer/consumer hand-off; `maxsize` applies backpressure.
+
+```python
+async def pipeline(items: list[int]) -> None:
+    q: asyncio.Queue[int] = asyncio.Queue(maxsize=10)
+
+    async def producer() -> None:
+        for it in items:
+            await q.put(it)        # blocks when full -> backpressure
+
+    async def consumer() -> None:
+        while True:
+            it = await q.get()
+            try:
+                await handle(it)
+            finally:
+                q.task_done()
+
+    async with asyncio.TaskGroup() as tg:
+        tg.create_task(producer())
+        c = tg.create_task(consumer())
+        await q.join()             # wait until every put is task_done()'d
+        c.cancel()                 # then stop the consumer
+```
+
+## Bridging sync and async
+
+- **Run a blocking call without freezing the loop**: `await asyncio.to_thread(blocking_fn, arg)`
+  offloads it to a thread pool. Use for sync IO (a legacy DB driver, a `requests` call).
+- **CPU-bound work**: a thread does not help (the GIL serializes it on a non-free-threaded build).
+  Use `loop.run_in_executor(ProcessPoolExecutor(), cpu_fn, arg)` to use real parallelism.
+- **Call async from sync** only at a top boundary via `asyncio.run`; do not block on a coroutine
+  from inside a running loop.
+
+## IO-bound vs CPU-bound
+
+| Workload | Right tool |
+| --- | --- |
+| Many network/disk waits | `asyncio` + `TaskGroup` (this skill) |
+| One blocking sync call inside async | `asyncio.to_thread` |
+| CPU-heavy (parse, compress, math) | `ProcessPoolExecutor` (real parallelism) |
+| CPU-heavy, 3.14 free-threaded build | threads (PEP 703 build removes the GIL; ~5–10% single-thread cost) |
+
+Async buys you *concurrency for waiting*, not *parallelism for computing*. If your bottleneck is
+CPU, `asyncio` will not speed it up — reach for processes (or the 3.14 free-threaded interpreter).
+
+## Common pitfalls
+
+- A coroutine you never `await` (or never wrap in a task) silently does nothing — "coroutine was
+  never awaited" warning.
+- `await`ing inside a lock you also need elsewhere can deadlock; keep critical sections short.
+- Mixing `time.sleep` into a coroutine (use `asyncio.sleep`).
+- Forgetting `task_done()` so `queue.join()` never returns.

package/skills/shared/python/references/stdlib.md

@@ -0,0 +1,162 @@
+# Stdlib cookbook
+
+Read when reaching for the standard library before a dependency. Recipes for
+`pathlib`/`itertools`/`functools`/`collections`/`contextlib`, the `match` statement, the
+dataclass field machinery, and Enum patterns.
+
+## pathlib
+
+```python
+from pathlib import Path
+
+root = Path(__file__).resolve().parent
+cfg = root / "config" / "app.toml"        # join with /
+cfg.read_text(encoding="utf-8")
+cfg.with_suffix(".bak")                    # app.bak
+list(root.glob("**/*.py"))                 # recursive
+cfg.parent.mkdir(parents=True, exist_ok=True)
+```
+
+`Path` is typed, OS-independent, and composable — use it everywhere instead of `os.path` string
+joins. For just-a-string interop, `str(path)` or pass the `Path` directly (most stdlib accepts it).
+
+## collections
+
+```python
+from collections import defaultdict, Counter, deque
+
+groups: defaultdict[str, list[int]] = defaultdict(list)
+groups[key].append(n)                      # no KeyError, auto-creates the list
+
+counts = Counter(words)
+counts.most_common(3)                      # top 3 (word, count)
+
+window: deque[int] = deque(maxlen=100)     # fixed-size ring buffer; old items drop off
+window.append(x)
+```
+
+`ChainMap` layers several dicts (defaults <- env <- overrides) into one lookup.
+
+## itertools
+
+```python
+from itertools import chain, groupby, islice, batched, pairwise
+
+list(chain(a, b, c))                       # flatten iterables
+list(islice(gen, 10))                      # first 10 of a (possibly infinite) generator
+for size, group in groupby(rows, key=lambda r: r.size):   # input MUST be pre-sorted by key
+    ...
+list(batched(range(10), 3))                # 3.12+: [(0,1,2),(3,4,5),(6,7,8),(9,)]
+list(pairwise([1, 2, 3]))                  # [(1,2),(2,3)]
+```
+
+## functools
+
+```python
+from functools import cache, cached_property, partial, reduce
+
+@cache                                     # unbounded memo for a pure function
+def fib(n: int) -> int:
+    return n if n < 2 else fib(n - 1) + fib(n - 2)
+
+class Report:
+    @cached_property                       # computed once per instance, then stored
+    def total(self) -> int:
+        return sum(self.rows)
+
+add5 = partial(add, 5)                     # pre-bind an argument
+```
+
+Prefer `@cache` over `@lru_cache(maxsize=None)`; keep `@lru_cache(maxsize=N)` only when you need
+a bound.
+
+## contextlib
+
+```python
+from contextlib import contextmanager, ExitStack, suppress
+
+@contextmanager
+def timer(label: str):
+    start = time.perf_counter()
+    try:
+        yield
+    finally:
+        log.info("%s took %.3fs", label, time.perf_counter() - start)
+
+with ExitStack() as stack:                 # dynamic, variable number of resources
+    files = [stack.enter_context(open(p)) for p in paths]
+    # all closed on block exit, in reverse order
+
+with suppress(FileNotFoundError):          # ignore one specific error, cleanly
+    Path("cache").unlink()
+```
+
+## The match statement
+
+Structural pattern matching — dispatch on shape, not a chain of `isinstance`.
+
+```python
+def describe(value: object) -> str:
+    match value:
+        case []:
+            return "empty list"
+        case [x]:
+            return f"one item: {x}"
+        case [first, *rest]:
+            return f"{first} and {len(rest)} more"
+        case {"type": "point", "x": int(x), "y": int(y)}:
+            return f"point {x},{y}"
+        case Point(x=0, y=0):              # class pattern, captures by attribute
+            return "origin"
+        case str() | bytes():
+            return "text-ish"
+        case _:
+            return "other"
+```
+
+Capture patterns bind names; `case _` is the wildcard. Guard with `case x if x > 0:`.
+
+## dataclasses, in depth
+
+```python
+from dataclasses import dataclass, field
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class Order:
+    id: str
+    items: list[str] = field(default_factory=list)   # NEVER `= []` (shared mutable default)
+    total: float = 0.0
+    _cache: dict[str, int] = field(default_factory=dict, compare=False, repr=False)
+
+    def __post_init__(self) -> None:
+        if self.total < 0:                 # frozen: validate, don't mutate
+            raise ValueError("total < 0")
+```
+
+- `frozen=True` -> immutable + hashable. `slots=True` -> no `__dict__`, less memory, faster attrs.
+- `kw_only=True` -> all fields keyword-only (avoids positional-order foot-guns).
+- `field(default_factory=...)` for any mutable default; `compare=False`/`repr=False` to exclude a field.
+- `__post_init__` for validation/derived values (assign via `object.__setattr__` when frozen).
+
+## Enum patterns
+
+```python
+from enum import Enum, StrEnum, IntEnum, IntFlag, auto
+
+class Color(Enum):
+    RED = auto()
+    GREEN = auto()
+
+class Status(StrEnum):                     # 3.11+: members ARE strings
+    ACTIVE = "active"
+    CLOSED = "closed"
+# Status.ACTIVE == "active" -> True; great for JSON/DB string columns.
+
+class Perm(IntFlag):                       # bitwise-combinable flags
+    READ = auto()
+    WRITE = auto()
+    ALL = READ | WRITE
+```
+
+Use `StrEnum`/`IntEnum` when the value must interop as a primitive (JSON, DB); plain `Enum` for
+opaque tokens. Pair an `Enum` with `Literal` types at boundaries for exhaustiveness checking.

package/skills/shared/python/references/typing.md

@@ -0,0 +1,160 @@
+# Typing — deep dive
+
+Read when the SKILL.md typing section is not enough: generic bounds/variance, structural vs
+nominal typing, `TypedDict` precision, callable-shape generics, narrowing, and the common
+`mypy --strict` errors and their fixes.
+
+## PEP 695 generics in full (Python 3.12+)
+
+Inline type parameters replace explicit `TypeVar` objects for new code.
+
+```python
+# Bound: T must be (a subtype of) Comparable.
+from typing import Protocol
+
+class Comparable(Protocol):
+    def __lt__(self, other: object) -> bool: ...
+
+def smallest[T: Comparable](xs: list[T]) -> T:
+    return min(xs)
+
+# Constraints: T is exactly one of these types (not "any subtype").
+def join[T: (str, bytes)](sep: T, parts: list[T]) -> T:
+    return sep.join(parts)
+
+# Generic class and a generic method on it.
+class Stack[T]:
+    def __init__(self) -> None:
+        self._items: list[T] = []
+    def push(self, item: T) -> None:
+        self._items.append(item)
+    def pop(self) -> T:
+        return self._items.pop()
+
+# The `type` statement: a true alias, lazily evaluated, can be generic.
+type Pair[T] = tuple[T, T]
+type Json = dict[str, "Json"] | list["Json"] | str | int | float | bool | None
+```
+
+**Variance** is inferred by the checker from how a type parameter is used — you no longer
+declare `covariant=`/`contravariant=`. A `list[T]` is invariant; a read-only `Sequence[T]`
+behaves covariantly. When you need an explicit infer-variance marker, PEP 695 exposes it, but
+in practice let the checker decide and fix the reported error.
+
+Legacy `TypeVar`/`Generic` syntax is **not deprecated** and may be mixed with the new syntax
+in the same file — but write PEP 695 for anything new.
+
+## Protocol (structural) vs ABC (nominal)
+
+- **`Protocol`**: duck typing the checker enforces. A class satisfies it by *shape*, with no
+  inheritance. Use for "anything with these methods". Add `@runtime_checkable` only if you need
+  `isinstance` against it (it checks method presence, not signatures).
+- **ABC** (`abc.ABC` + `@abstractmethod`): nominal — subclasses must explicitly inherit. Use
+  when you own the hierarchy and want to *share implementation* or force registration.
+
+```python
+from typing import Protocol, runtime_checkable
+
+@runtime_checkable
+class Closeable(Protocol):
+    def close(self) -> None: ...
+
+def shut(x: Closeable) -> None:
+    x.close()        # any object with close()->None type-checks; no base class needed
+```
+
+Prefer `Protocol` for boundaries you consume from elsewhere; reserve ABCs for frameworks you author.
+
+## TypedDict — Required / NotRequired
+
+Types a plain dict (e.g. a JSON payload) without a runtime class.
+
+```python
+from typing import TypedDict, Required, NotRequired
+
+class Config(TypedDict):
+    name: Required[str]
+    retries: NotRequired[int]     # key may be absent
+
+# total=False flips the default: every key NotRequired unless marked Required.
+class Patch(TypedDict, total=False):
+    name: str
+    retries: int
+```
+
+For closed value sets inside a dict field, combine with `Literal`. When you need *runtime
+validation* of the dict (untrusted input), that is a Pydantic/service concern -> `fastapi`.
+
+## Callable shapes: ParamSpec and TypeVarTuple
+
+```python
+from collections.abc import Callable
+from functools import wraps
+
+# ParamSpec: preserve the wrapped function's full signature through a decorator.
+def timed[**P, R](fn: Callable[P, R]) -> Callable[P, R]:
+    @wraps(fn)
+    def inner(*args: P.args, **kwargs: P.kwargs) -> R:
+        return fn(*args, **kwargs)
+    return inner
+
+# TypeVarTuple: variadic generics over an arbitrary number of types.
+def first_and_rest[T, *Ts](x: T, *rest: *Ts) -> tuple[T, tuple[*Ts]]:
+    return x, rest
+```
+
+## @overload — signature families
+
+When one function has distinct return types per argument shape, declare overloads then a single
+untyped-to-the-caller implementation:
+
+```python
+from typing import overload
+
+@overload
+def get(key: str) -> str: ...
+@overload
+def get(key: str, default: int) -> str | int: ...
+def get(key: str, default: int | None = None) -> str | int:
+    ...
+```
+
+## Narrowing: guards, TypeGuard, TypeIs
+
+Mypy follows control flow, so `isinstance`, `is None`, and `assert` narrow automatically.
+For custom predicates use `TypeIs` (3.13+, narrows in both branches) or `TypeGuard`:
+
+```python
+from typing import TypeIs
+
+def is_str_list(xs: list[object]) -> TypeIs[list[str]]:
+    return all(isinstance(x, str) for x in xs)
+
+def handle(xs: list[object]) -> None:
+    if is_str_list(xs):
+        xs[0].upper()        # narrowed to list[str] here
+```
+
+Use `typing.cast(T, value)` only as a last resort when you know more than the checker; it is an
+unchecked assertion. `reveal_type(x)` (no import needed under mypy) prints the inferred type at
+check time — delete it before committing.
+
+## Common `mypy --strict` errors and fixes
+
+| Error | Fix |
+| --- | --- |
+| `Function is missing a return type annotation` | Add `-> T` (use `-> None` for procedures). |
+| `Need type annotation for "x"` | Annotate the empty container: `x: list[int] = []`. |
+| `Returning Any from function declared to return "T"` | Type the source, or `cast` if truly unknowable. |
+| `Incompatible default for argument` | A `None` default needs `X | None` in the type. |
+| `Item "None" of "X | None" has no attribute ...` | Narrow with `if v is None: return` first. |
+| `Untyped decorator makes function "f" untyped` | Type the decorator with `ParamSpec` (see above). |
+| `Call to untyped function in typed context` | Add hints to the callee, or stub it. |
+
+## 3.14: deferred annotations
+
+Annotations are evaluated **lazily by default** (PEP 649/749): forward references resolve
+without `from __future__ import annotations`, recursive type aliases just work, and the new
+`annotationlib` module inspects annotations as live objects (`get_annotations`). `types.UnionType`
+is now an alias for `typing.Union`. Drop the `__future__` import in 3.14-only code; keep it for
+3.12/3.13 compatibility.

package/skills/shared/python/scripts/verify.sh

@@ -0,0 +1,125 @@
+#!/usr/bin/env bash
+#
+# verify.sh - local quality gate for a Python project (single mirror of CI).
+#
+# Usage:
+#   cd <your-project-root>   # the directory containing pyproject.toml
+#   ./verify.sh
+#
+# Runs: uv sync --frozen, ruff check, ruff format --check, mypy --strict (or ty),
+# and pytest. Tools/dirs that are absent are skipped with a yellow warning, never a
+# failure. Real problems (lint, format drift, type errors, test failures) exit non-zero.
+# Read-only by default: it does not reformat or autofix your source.
+#
+# Portability: stock macOS bash 3.2 (no mapfile, no associative arrays, guarded under set -u).
+
+set -euo pipefail
+
+if [ -t 1 ]; then
+  YELLOW=$'\033[33m'; RED=$'\033[31m'; GREEN=$'\033[32m'; RESET=$'\033[0m'
+else
+  YELLOW=''; RED=''; GREEN=''; RESET=''
+fi
+
+failed=0
+
+have()  { command -v "$1" >/dev/null 2>&1; }
+warn()  { printf '%s[skip]%s %s\n' "$YELLOW" "$RESET" "$*"; }
+fail()  { printf '%s[fail]%s %s\n' "$RED" "$RESET" "$*"; failed=1; }
+ok()    { printf '%s[ ok ]%s %s\n' "$GREEN" "$RESET" "$*"; }
+info()  { printf -- '----- %s\n' "$*"; }
+
+# Must run from a project root.
+if [ ! -f pyproject.toml ]; then
+  printf '%serror:%s no pyproject.toml in %s - cd into your project root first.\n' \
+    "$RED" "$RESET" "$(pwd)" >&2
+  exit 2
+fi
+
+# Choose a runner: prefer `uv run <tool>` when uv is present, else the bare tool.
+have_uv=0
+if have uv; then have_uv=1; fi
+
+run_tool() {
+  # run_tool <toolname> [args...] : invoke via uv when available, else directly.
+  local tool="$1"; shift
+  if [ "$have_uv" -eq 1 ]; then
+    uv run "$tool" "$@"
+  else
+    "$tool" "$@"
+  fi
+}
+tool_present() {
+  # tool_present <toolname> : true if reachable directly or via uv.
+  if have "$1"; then return 0; fi
+  if [ "$have_uv" -eq 1 ] && uv run "$1" --version >/dev/null 2>&1; then return 0; fi
+  return 1
+}
+
+# 1. uv sync --frozen - reproducible install from the committed lockfile.
+info "uv sync"
+if [ "$have_uv" -eq 1 ]; then
+  if [ -f uv.lock ]; then
+    if uv sync --frozen; then ok "uv sync --frozen"; else fail "uv sync --frozen failed"; fi
+  else
+    warn "no uv.lock; trying uv sync (will create one)"
+    if uv sync; then ok "uv sync"; else fail "uv sync failed"; fi
+  fi
+else
+  warn "uv not found (https://docs.astral.sh/uv/); using whatever is on PATH"
+fi
+
+# 2. ruff check - lint. Read-only here (no --fix); CI should not mutate source.
+info "ruff check"
+if tool_present ruff; then
+  if run_tool ruff check .; then ok "ruff check clean"; else fail "ruff reported lint issues (run: ruff check --fix .)"; fi
+else
+  warn "ruff not found (uv add --dev ruff)"
+fi
+
+# 3. ruff format --check - formatting must be clean, but do not rewrite files.
+info "ruff format --check"
+if tool_present ruff; then
+  if run_tool ruff format --check .; then ok "ruff format clean"; else fail "formatting drift (run: ruff format .)"; fi
+else
+  warn "ruff not found - skipping format check"
+fi
+
+# 4. type check: mypy --strict, or ty if the project opted into it via [tool.ty].
+info "type check"
+type_target="."
+if [ -d src ]; then type_target="src"; fi
+if grep -q '^\[tool\.ty\]' pyproject.toml 2>/dev/null && tool_present ty; then
+  if run_tool ty check "$type_target"; then ok "ty clean"; else fail "ty reported type errors"; fi
+elif tool_present mypy; then
+  if run_tool mypy --strict "$type_target"; then ok "mypy --strict clean ($type_target)"; else fail "mypy --strict reported type errors"; fi
+else
+  warn "no type checker found (uv add --dev mypy)"
+fi
+
+# 5. pytest - only if there are tests to run.
+info "pytest"
+has_tests=0
+if [ -d tests ]; then has_tests=1; fi
+# Any test_*.py / *_test.py anywhere also counts.
+if [ "$has_tests" -eq 0 ]; then
+  if find . -type d -name .venv -prune -o -type f \( -name 'test_*.py' -o -name '*_test.py' \) -print 2>/dev/null | grep -q .; then
+    has_tests=1
+  fi
+fi
+if [ "$has_tests" -eq 1 ]; then
+  if tool_present pytest; then
+    if run_tool pytest -q; then ok "pytest passed"; else fail "pytest failed"; fi
+  else
+    warn "pytest not found (uv add --dev pytest)"
+  fi
+else
+  warn "no tests found - skipping pytest"
+fi
+
+echo
+if [ "$failed" -ne 0 ]; then
+  printf '%sFAIL:%s one or more checks failed.\n' "$RED" "$RESET"
+  exit 1
+fi
+printf '%sPASS:%s all checks passed.\n' "$GREEN" "$RESET"