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

package/skills/shared/api-design/evals/cases.yaml

@@ -0,0 +1,45 @@
+skill: api-design
+
+should_trigger:
+  - prompt: "Design the REST API for a multi-tenant invoicing service"
+    why: core greenfield contract-design request; resource modeling + URLs.
+  - prompt: "How do I add a field and a new status value to this endpoint without breaking existing clients?"
+    why: evolution/versioning; non-obvious — no words 'API' or 'design', it's the additive-non-breaking rule.
+  - prompt: "Should this be REST or GraphQL, and how should pagination work?"
+    why: paradigm choice plus pagination convention — both are design-time decisions.
+  - prompt: "What's the standard error format? I keep returning a different shape per endpoint"
+    why: symptom-led; routes to the single RFC 9457 problem-details envelope.
+  - prompt: "Our list endpoint times out at page 5000 with offset pagination"
+    why: non-obvious symptom — the fix is a cursor/keyset pagination design, not a query tweak.
+  - prompt: "diseña los endpoints y el versionado de nuestra API pública"
+    why: Spanish trigger for endpoint design + versioning strategy.
+  - prompt: "We need an Idempotency-Key on POST so retries don't double-charge — how should the contract handle it?"
+    why: non-obvious header-level contract decision (idempotency), design-time not implementation.
+
+should_not_trigger:
+  - prompt: "Implement these endpoints in FastAPI with Pydantic models and async routes"
+    route_to: fastapi
+    why: build-time framework implementation, not contract design.
+  - prompt: "Threat-model this endpoint and check the CORS and CSP config for OWASP issues"
+    route_to: secure-coding
+    why: security/hardening lens, not the API shape.
+  - prompt: "Verify the incoming Stripe webhook signature and dedupe replayed events"
+    route_to: webhooks
+    why: receiving inbound events with HMAC verification, not designing an exposed API.
+  - prompt: "Write a client that calls the OpenWeather API and handles its rate limits and retries"
+    route_to: api-connector-builder
+    why: building an outbound client to a third-party API, not designing one.
+  - prompt: "Wire a custom provider with useFactory in my NestJS module"
+    route_to: nestjs
+    why: framework dependency-injection wiring, not contract design.
+
+capability:
+  - scenario: "Design the public REST API contract for a 'projects' resource with nested tasks, supporting pagination, consistent errors, and a versioning plan."
+    must_include:
+      - plural noun collections and nested path `/projects/{id}/tasks` with no verbs in paths
+      - correct methods + status codes, including 201 + Location on create and the 409-vs-422 distinction
+      - one RFC 9457 `application/problem+json` error envelope used across all endpoints, with a stable machine `type` and a correlation id, no leaked internals
+      - cursor (keyset) pagination with a consistent response envelope (data + next_cursor/has_more)
+      - URL-path versioning for the public API plus the additive-non-breaking evolution rule (and Deprecation/Sunset on removal)
+      - a handoff note pointing to a framework skill (fastapi/nestjs/go/nodejs) to implement it
+      - bonus: an OpenAPI 3.1 sketch of the contract

package/skills/shared/api-design/references/graphql-design.md

@@ -0,0 +1,70 @@
+# GraphQL design
+
+When you chose GraphQL (many client shapes, deep graphs, over-fetch is real), design the schema as the contract. Framework-neutral.
+
+## Schema & nullability
+
+- **Model the domain graph, not your tables.** Types are nouns with relationships; let clients traverse instead of you minting endpoints.
+- **Nullability is a contract.** A non-null field (`String!`) means the resolver must always produce it — and if it errors, GraphQL nulls the *nearest nullable parent*, which can blank a whole subtree. Make a field non-null only when it truly cannot be absent; default to nullable for anything fetched from a flaky downstream.
+- **Use enums for closed sets** and add values additively (clients should tolerate unknown enum values).
+- **Evolve additively; deprecate with `@deprecated(reason: ...)`** instead of removing — GraphQL has no URL version to fall back on.
+
+## Pagination: Relay Connections
+
+Use the de-facto standard rather than a bespoke shape, so client tooling (Apollo/Relay) works out of the box.
+
+```graphql
+type ProjectConnection {
+  edges: [ProjectEdge!]!
+  pageInfo: PageInfo!
+}
+
+type ProjectEdge {
+  node: Project!
+  cursor: String!
+}
+
+type PageInfo {
+  hasNextPage: Boolean!
+  endCursor: String
+}
+
+type Query {
+  projects(first: Int!, after: String): ProjectConnection!
+}
+```
+
+- `first` + `after` paginate forward; `last` + `before` backward.
+- `cursor` is opaque — clients pass `endCursor` back as `after`; they never construct it.
+
+## Mutations & error model
+
+- **One input object per mutation, one payload type out** — keeps mutations evolvable: `createProject(input: CreateProjectInput!): CreateProjectPayload!`.
+- **Model expected, business-level failures as data, not as protocol errors.** A union or a payload with `userErrors { field, message }` lets clients handle validation without parsing the transport `errors[]`.
+
+```graphql
+type CreateProjectPayload {
+  project: Project
+  userErrors: [UserError!]!
+}
+```
+
+## The HTTP-200 error model (the big operational difference)
+
+GraphQL returns **HTTP 200 even when a field errored.** Failures appear in a top-level `errors[]` array alongside partial `data`:
+
+```json
+{
+  "data": { "project": null },
+  "errors": [
+    { "message": "Project not found", "path": ["project"], "extensions": { "code": "NOT_FOUND" } }
+  ]
+}
+```
+
+Consequences you must design for:
+- **Monitoring cannot rely on HTTP 5xx.** Alerting must inspect the `errors[]` payload and `extensions.code`, not the status line. Wire this before launch or outages go invisible.
+- **Clients must check `errors[]` on every response**, even a 200. Treating 200 as success silently swallows failures.
+- **Standardize `extensions.code`** (e.g. `NOT_FOUND`, `FORBIDDEN`, `VALIDATION`) so clients and dashboards branch on a stable machine value — the GraphQL analogue of an RFC 9457 `type`.
+
+This single difference, not the query syntax, is what makes GraphQL operationally distinct from REST. Decide it explicitly.

package/skills/shared/api-design/references/openapi-contract.md

@@ -0,0 +1,86 @@
+# OpenAPI 3.1 contract
+
+The contract is the artifact. Capture a REST design as an **OpenAPI 3.1** document — a real, lintable file that a framework skill generates server stubs and clients from, and that `scripts/verify.sh` checks.
+
+Why 3.1: it aligns with JSON Schema 2020-12, so your request/response schemas are reusable JSON Schema, and it adds `webhooks` and richer `$ref` handling over 3.0.
+
+## Minimal skeleton
+
+```yaml
+openapi: 3.1.0
+info:
+  title: Projects API
+  version: 1.0.0
+servers:
+  - url: https://api.acme.com/v1
+paths:
+  /projects:
+    get:
+      summary: List projects
+      parameters:
+        - { name: cursor, in: query, schema: { type: string } }
+        - { name: limit, in: query, schema: { type: integer, maximum: 100, default: 50 } }
+      responses:
+        "200":
+          description: A page of projects
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/ProjectPage" }
+        default:
+          $ref: "#/components/responses/Problem"
+    post:
+      summary: Create a project
+      parameters:
+        - { name: Idempotency-Key, in: header, schema: { type: string } }
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: "#/components/schemas/ProjectCreate" }
+      responses:
+        "201":
+          description: Created
+          headers:
+            Location: { schema: { type: string } }
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/Project" }
+        "422": { $ref: "#/components/responses/Problem" }
+        default: { $ref: "#/components/responses/Problem" }
+components:
+  responses:
+    Problem:
+      description: RFC 9457 problem details
+      content:
+        application/problem+json:
+          schema: { $ref: "#/components/schemas/Problem" }
+  schemas:
+    Problem:
+      type: object
+      properties:
+        type: { type: string, format: uri }
+        title: { type: string }
+        status: { type: integer }
+        detail: { type: string }
+        instance: { type: string }
+      required: [type, title, status]
+    ProjectPage:
+      type: object
+      properties:
+        data: { type: array, items: { $ref: "#/components/schemas/Project" } }
+        next_cursor: { type: [string, "null"] }
+        has_more: { type: boolean }
+      required: [data, has_more]
+```
+
+## Conventions that keep it clean
+
+- **One reusable `Problem` schema and `Problem` response**, referenced by every error case — enforces the single RFC 9457 envelope.
+- **A `default` response on every operation** so unexpected statuses still resolve to the problem shape.
+- **Every list operation carries `cursor` + `limit`** params — verify.sh warns when a list path lacks them.
+- **No verbs in path keys** — verify.sh flags `/get*`, `/create*`, `/delete*` segments.
+- **`info.version` is the contract version**, distinct from the URL `/v1` major; bump it on any non-breaking addition too.
+
+## Handoff
+
+Give the framework skill this file. It becomes the source of truth: FastAPI/NestJS/Go/Node tooling can generate models, route stubs, and validation from it, and clients can generate SDKs. Keep the OpenAPI doc updated *before* the code changes — design-first, not code-first.

package/skills/shared/api-design/references/rest-conventions.md

@@ -0,0 +1,63 @@
+# REST conventions
+
+Depth behind the SKILL. Framework-neutral. Adopt as house style and keep it consistent across every endpoint.
+
+## Status-code map — when each
+
+| Code | Meaning | Use when |
+|---|---|---|
+| 200 OK | success + body | GET, or a PUT/PATCH that returns the updated resource |
+| 201 Created | created | POST created a resource — include `Location: /collection/{id}` |
+| 202 Accepted | accepted, not done | async work queued — return a status/poll URL |
+| 204 No Content | success, no body | DELETE, or PUT/PATCH that returns nothing |
+| 304 Not Modified | cache hit | conditional GET with `If-None-Match` and ETag matched |
+| 400 Bad Request | malformed | body/params unparseable or syntactically wrong |
+| 401 Unauthorized | unauthenticated | missing/invalid credentials — re-auth may help |
+| 403 Forbidden | unauthorized | authenticated but lacks permission/scope |
+| 404 Not Found | absent | resource doesn't exist (or is hidden from this caller) |
+| 405 Method Not Allowed | wrong verb | path exists, method doesn't — set `Allow` header |
+| 409 Conflict | state collision | duplicate, version mismatch, concurrent edit |
+| 412 Precondition Failed | stale write | `If-Match` ETag no longer matches |
+| 415 Unsupported Media Type | bad content-type | server can't process the sent representation |
+| 422 Unprocessable Content | semantic invalid | parses fine, fails business validation |
+| 429 Too Many Requests | rate limited | include `Retry-After` |
+| 500 Internal Server Error | server fault | unexpected — never leak the stack |
+| 503 Service Unavailable | temporarily down | maintenance/overload — `Retry-After` if known |
+
+Rule of thumb: client mistakes are 4xx, server faults are 5xx. Never blame the client for your bug, never hide your bug behind a 200.
+
+## Query grammar (filter / sort / sparse fieldsets)
+
+Keep one grammar across all list endpoints so clients learn it once.
+
+```http
+GET /projects?status=active&owner=u_42&sort=-created_at,title&fields=id,title,status&limit=50
+```
+
+- **Filter** by field name as a query key: `?status=active`. For operators, namespace them: `?created_at[gte]=2026-01-01`. Pick one operator syntax and never mix.
+- **Sort** with a comma list; `-` prefix = descending: `?sort=-created_at,title`.
+- **Sparse fieldsets** let clients trim payloads: `?fields=id,title`. Whitelist allowed fields server-side.
+- **Reserve** `limit`, `cursor` (or `offset`), `sort`, `fields`, `q` (free-text search) so they never collide with resource fields.
+
+## Content negotiation
+
+- Default to `application/json`. Honor `Accept`; return `406 Not Acceptable` if you can't satisfy it.
+- Validate `Content-Type` on writes; `415` if unsupported.
+- Version via media type only if you chose header versioning (see versioning reference); otherwise keep it simple.
+
+## Rate-limit headers
+
+Expose limits so well-behaved clients self-throttle:
+
+```http
+RateLimit-Limit: 1000
+RateLimit-Remaining: 12
+RateLimit-Reset: 1735689600
+Retry-After: 30
+```
+
+On 429 always send `Retry-After`. Prefer the IETF `RateLimit-*` fields; the older `X-RateLimit-*` names are still common in the wild.
+
+## HATEOAS — pragmatic stance
+
+Full hypermedia (links driving all client navigation) is rarely worth it for typical JSON APIs; clients hardcode URLs anyway. Useful subset: include a `Location` on 201, a `Link` header for pagination/successor-version, and self/next links in list envelopes when it costs little. Don't build a hypermedia framework no client will follow.

package/skills/shared/api-design/references/versioning-and-evolution.md

@@ -0,0 +1,49 @@
+# Versioning & evolution
+
+Default posture: **evolve additively, version rarely.** A version is a fork of your client base — earn it.
+
+## Breaking vs non-breaking matrix
+
+| Change | Breaking? | Notes |
+|---|---|---|
+| Add a new optional response field | No | clients ignore unknown fields if you told them to |
+| Add a new endpoint | No | nothing existing changes |
+| Add a new optional query/body param | No | old requests still valid |
+| Add a new enum value | No* | *only if clients were told to tolerate unknown values; otherwise breaking |
+| Loosen a validation rule | No | previously-rejected input now accepted |
+| Remove or rename a field | **Yes** | clients reading it break |
+| Change a field's type or format | **Yes** | `string` → `object`, date format change, etc. |
+| Make an optional field required | **Yes** | old requests start failing |
+| Tighten validation (narrower accepted range) | **Yes** | previously-valid input now rejected |
+| Change a status code for a case | **Yes** | client branching breaks |
+| Change an error `type` URI for a case | **Yes** | clients branch on `type` |
+| Change pagination/cursor semantics | **Yes** | in-flight pagination breaks |
+
+Design hint: tell clients up front to **ignore unknown fields and tolerate unknown enum values** ("must-ignore" / robustness rule). That single contract clause turns many would-be breaking changes into additive ones.
+
+## Three versioning mechanisms
+
+| Mechanism | Example | Pros | Cons |
+|---|---|---|---|
+| **URL path** | `/v1/projects` | visible, cacheable, browser-testable, expected by most clients | version leaks into every URL; "v" is coarse-grained |
+| **Header / media type** | `Accept: application/vnd.acme.v2+json` | clean URLs, content-negotiated | harder to test/cache, easy to forget, opaque to humans |
+| **Query param** | `/projects?version=2` | trivial to add | pollutes URLs, easy to omit, muddies caching |
+
+**Default to URL path for public APIs.** Reserve header/media-type versioning for internal APIs where tooling controls the header. Don't mix mechanisms.
+
+## Deprecation & sunset workflow
+
+1. Ship the successor (new field/endpoint/version) additively.
+2. Mark the old surface deprecated in responses:
+
+```http
+Deprecation: true
+Sunset: Sat, 31 Oct 2026 23:59:59 GMT
+Link: <https://api.acme.com/v2/projects>; rel="successor-version"
+```
+
+3. Document the migration and the sunset date; notify known integrators.
+4. Hold the deprecated surface working until the `Sunset` date — give clients real time (months, not days, for public APIs).
+5. After sunset, return `410 Gone` for the removed surface (not `404`) so clients learn it was intentional.
+
+Keep the deprecation window generous and the messaging programmatic — clients should learn from headers, not from breakage.

package/skills/shared/api-design/scripts/verify.sh

@@ -0,0 +1,138 @@
+#!/usr/bin/env bash
+# verify.sh — read-only check of an API-design artifact (OpenAPI 3.1 spec).
+#
+# The api-design skill emits its contract as an OpenAPI document. This script
+# finds candidate spec files under a target dir, validates they parse and carry
+# the required OpenAPI keys, and emits non-fatal warnings for the design
+# anti-patterns it can detect statically. It never writes anything.
+#
+# Usage:   verify.sh [TARGET_DIR]   (default: current directory)
+# Exit:    0  no spec found (soft-pass) OR all found specs valid
+#          1  a spec file is present but invalid/unparseable
+#
+# Soft-pass on a clean/empty target: a design may live only in a doc.
+
+set -uo pipefail
+
+TARGET="${1:-.}"
+fail=0
+
+note()  { printf '  - %s\n' "$1"; }
+warn()  { printf '  ! %s\n' "$1"; }
+
+if [ ! -d "$TARGET" ]; then
+  echo "verify(api-design): target '$TARGET' is not a directory — nothing to check."
+  exit 0
+fi
+
+# Collect candidate OpenAPI files (read-only). Tolerate no matches.
+# Portable to bash 3.2 (macOS default): no mapfile; newline-delimited list.
+specs=()
+while IFS= read -r f; do
+  [ -n "$f" ] && specs+=("$f")
+done < <(
+  find "$TARGET" \
+    \( -name 'openapi.yaml' -o -name 'openapi.yml' -o -name 'openapi.json' \
+       -o -name '*.openapi.yaml' -o -name '*.openapi.yml' -o -name '*.openapi.json' \) \
+    -type f 2>/dev/null
+)
+
+if [ "${#specs[@]}" -eq 0 ]; then
+  echo "verify(api-design): no OpenAPI spec found under '$TARGET' — soft-pass (design may be in-doc only)."
+  exit 0
+fi
+
+# Choose a linter if available; else fall back to a structural check.
+LINTER=""
+if command -v redocly >/dev/null 2>&1; then
+  LINTER="redocly"
+elif command -v spectral >/dev/null 2>&1; then
+  LINTER="spectral"
+fi
+
+# Structural fallback: parse + required keys, using whatever is on PATH.
+parse_check() {
+  local f="$1"
+  case "$f" in
+    *.json)
+      if command -v jq >/dev/null 2>&1; then
+        jq -e 'has("openapi") and has("info") and has("paths")' "$f" >/dev/null 2>&1
+        return $?
+      fi
+      ;;
+    *.yaml|*.yml)
+      if command -v python3 >/dev/null 2>&1; then
+        python3 - "$f" <<'PY' >/dev/null 2>&1
+import sys
+try:
+    import yaml
+except Exception:
+    sys.exit(2)  # no yaml lib -> can't check, treat as inconclusive
+with open(sys.argv[1]) as fh:
+    d = yaml.safe_load(fh)
+sys.exit(0 if isinstance(d, dict) and all(k in d for k in ("openapi", "info", "paths")) else 1)
+PY
+        local rc=$?
+        [ "$rc" -eq 2 ] && return 3   # inconclusive
+        return $rc
+      fi
+      ;;
+  esac
+  return 3  # inconclusive: no suitable parser on PATH
+}
+
+# Static anti-pattern warnings (grep-based, never fatal).
+antipattern_scan() {
+  local f="$1"
+  if grep -Eiq '"?/[A-Za-z0-9_]*(get|create|update|delete|fetch|list)[A-Za-z0-9_]*"?[[:space:]]*:' "$f"; then
+    warn "verb-like path segment(s) detected — paths should be nouns; HTTP methods are the verbs."
+  fi
+  if grep -Eq '(/[A-Za-z0-9_/{}]*)+[[:space:]]*:' "$f" && ! grep -Eiq 'cursor|limit|offset|first|after|page' "$f"; then
+    warn "no pagination params (cursor/limit/offset) found — list endpoints should paginate."
+  fi
+  if ! grep -Eiq 'problem\+json|"4[0-9][0-9]"|default[[:space:]]*:' "$f"; then
+    warn "no 4xx / default error responses found — every operation should define an error response (RFC 9457)."
+  fi
+}
+
+echo "verify(api-design): checking ${#specs[@]} spec file(s) under '$TARGET'"
+[ -n "$LINTER" ] && echo "  using linter: $LINTER"
+
+for f in "${specs[@]}"; do
+  echo "* $f"
+  ok=1
+  if [ -n "$LINTER" ]; then
+    if [ "$LINTER" = "redocly" ]; then
+      redocly lint "$f" >/dev/null 2>&1 || ok=0
+    else
+      spectral lint "$f" >/dev/null 2>&1 || ok=0
+    fi
+    if [ "$ok" -eq 0 ]; then
+      # Linter unhappy: confirm with structural parse before failing hard.
+      parse_check "$f"; pc=$?
+      if [ "$pc" -eq 0 ]; then
+        warn "$LINTER reported issues but the spec parses and has required keys — review lint output."
+      else
+        note "spec is invalid per $LINTER."
+        fail=1
+        continue
+      fi
+    fi
+  else
+    parse_check "$f"; pc=$?
+    case "$pc" in
+      0) : ;;  # valid
+      3) warn "no parser on PATH (jq/python3+pyyaml) — skipped structural validation." ;;
+      *) note "spec does not parse or is missing required keys (openapi/info/paths)."; fail=1; continue ;;
+    esac
+  fi
+  antipattern_scan "$f"
+done
+
+if [ "$fail" -ne 0 ]; then
+  echo "verify(api-design): FAIL — one or more specs are invalid."
+  exit 1
+fi
+
+echo "verify(api-design): OK (warnings, if any, are advisory)."
+exit 0