skilldrop-cli 0.16.45 → 0.16.46

package/packs/solution-architect/skills/context-graph/evals/files/8/docs/adr/0004-integer-minor-units.md

@@ -0,0 +1,32 @@
+---
+id: ADR-0004
+title: Store money as integer minor units
+status: accepted
+date: 2024-03-05
+deciders: [m.okafor, j.lindqvist]
+---
+
+# Store money as integer minor units
+
+## Context and Problem Statement
+
+Floating point and arbitrary-precision decimals have both caused rounding bugs on previous
+projects. How should monetary amounts be represented in the ledger?
+
+## Considered Options
+
+* `NUMERIC` columns with Python `Decimal`
+* Integer minor units (cents, pence) with a separate ISO 4217 currency code
+
+## Decision Outcome
+
+Chosen option: "Integer minor units", because sums are exact and every currency we support
+has a fixed minor-unit exponent.
+
+Every amount column in `services/ledger/db/migrations/` is `BIGINT` named `*_minor`, paired
+with a `currency CHAR(3)` column. `services/ledger/models/entry.py` exposes amounts as `int`.
+
+### Consequences
+
+* Good, because addition is exact and fast.
+* Bad, because display code must apply the currency exponent.

package/packs/solution-architect/skills/context-graph/evals/files/8/docs/adr/0005-provider-http-retries.md

@@ -0,0 +1,26 @@
+# ADR 0005: Retry and timeout policy for payment-provider calls
+
+* Status: Accepted
+* Date: 2024-04-18
+
+## Context
+
+The payment provider occasionally returns 502/503 during their deploys. Unbounded retries
+during an outage amplified load on them last year and held our worker threads.
+
+## Decision
+
+Calls from `services/ledger/clients/provider.py` to the provider:
+
+| Setting            | Value                                   |
+|--------------------|-----------------------------------------|
+| Request timeout    | 5 seconds                               |
+| Max retries        | 3                                       |
+| Backoff            | exponential, 200 ms base, full jitter   |
+| Retry on           | GET and idempotent POST (with key) only |
+
+Values are read from `config/http.yaml`; the code must not hard-code them.
+
+## Consequences
+
+Worst-case latency of a provider call is bounded at roughly 21 seconds.

package/packs/solution-architect/skills/context-graph/evals/files/8/docs/adr/0006-openapi-generated-clients.md

@@ -0,0 +1,20 @@
+# 6. Generate service clients from an OpenAPI spec
+
+Date: 2024-06-03
+
+## Status
+
+Accepted
+
+## Context
+
+Three internal teams call the ledger and each hand-wrote a client.
+
+## Decision
+
+The ledger's public interface is defined in `api/openapi.yaml`. Clients are generated from it
+into `clients/generated/` on every release; hand-written clients are not accepted.
+
+## Consequences
+
+- The spec is the source of truth; the server is checked against it in CI.

package/packs/solution-architect/skills/context-graph/evals/files/8/docs/adr/0007-kafka-domain-events.md

@@ -0,0 +1,25 @@
+---
+id: ADR-0007
+title: Move domain events to Kafka
+status: accepted
+date: 2025-03-11
+supersedes: ADR-0003
+---
+
+# Move domain events to Kafka
+
+## Context and Problem Statement
+
+Reporting now needs to replay the full history of posted entries, which RabbitMQ queues
+cannot give us once a message is acknowledged.
+
+## Decision Outcome
+
+Domain events are published to the Kafka topic `ledger.entry-events`, keyed by account id,
+with 30-day retention. This supersedes ADR-0003. Publishing stays in
+`services/ledger/events/`; broker settings stay in `config/messaging.yaml`.
+
+### Consequences
+
+* Good, because consumers can replay from any offset within retention.
+* Bad, because the team now operates a Kafka cluster.

package/packs/solution-architect/skills/context-graph/evals/files/8/docs/adr/0008-structured-logging.md

@@ -0,0 +1,18 @@
+# ADR 0008: Structured JSON logging
+
+* Status: Accepted
+* Date: 2025-05-20
+
+## Context
+
+Log search across services is painful because each one logs free text differently.
+
+## Decision
+
+All ledger logging goes through `services/ledger/logging.py`, which emits one JSON object per
+line with `ts`, `level`, `msg`, `trace_id` and `account_id` fields. The `trace_id` comes from
+the tracing setup described in ADR-0011.
+
+## Consequences
+
+Plain `print` and ad-hoc `logging.basicConfig` calls are not allowed in service code.

package/packs/solution-architect/skills/context-graph/evals/files/8/docs/rfcs/RFC-012-idempotency-keys.md

@@ -0,0 +1,19 @@
+# RFC-012: Idempotency keys for posting entries
+
+- **State:** Draft
+- **Author:** j.lindqvist
+- **Opened:** 2025-08-02
+
+## Summary
+
+Clients send an `Idempotency-Key` with every `PostEntry` call. The ledger stores the key and
+the response for 24 hours and returns the stored response on a repeat.
+
+## Proposed implementation
+
+`services/ledger/api/idempotency.py`, backed by a table `idempotency_keys` in PostgreSQL.
+
+## Open questions
+
+- Is 24 hours long enough for the batch importer, which can retry after a day?
+- Should a key reused with a different body be a 409 or a 422?

package/packs/solution-architect/skills/context-graph/evals/files/8/services/ledger/api/idempotency.py

@@ -0,0 +1,19 @@
+import json
+from datetime import timedelta
+
+KEY_TTL = timedelta(hours=24)
+
+
+def lookup(conn, key: str):
+    row = conn.execute(
+        "SELECT response FROM idempotency_keys WHERE key = %s AND created_at > now() - %s",
+        (key, KEY_TTL),
+    ).fetchone()
+    return json.loads(row[0]) if row else None
+
+
+def store(conn, key: str, response: dict) -> None:
+    conn.execute(
+        "INSERT INTO idempotency_keys (key, response) VALUES (%s, %s) ON CONFLICT DO NOTHING",
+        (key, json.dumps(response)),
+    )

package/packs/solution-architect/skills/context-graph/evals/files/8/services/ledger/api/server.py

@@ -0,0 +1,35 @@
+from concurrent import futures
+
+import grpc
+
+from services.ledger.api import idempotency
+from services.ledger.api.gen import ledger_pb2, ledger_pb2_grpc
+from services.ledger.logging import get_logger
+
+log = get_logger(__name__)
+
+
+class LedgerServicer(ledger_pb2_grpc.LedgerServicer):
+    def __init__(self, db):
+        self.db = db
+
+    def PostEntry(self, request, context):
+        with self.db.transaction() as conn:
+            cached = idempotency.lookup(conn, request.idempotency_key)
+            if cached:
+                return ledger_pb2.PostEntryResponse(**cached)
+            entry_id = self.db.post_entry(conn, request)
+            idempotency.store(conn, request.idempotency_key, {"entry_id": entry_id})
+        return ledger_pb2.PostEntryResponse(entry_id=entry_id)
+
+    def GetBalance(self, request, context):
+        return self.db.balance(request.account_id)
+
+
+def serve(db, port: int = 50051) -> None:
+    server = grpc.server(futures.ThreadPoolExecutor(max_workers=16))
+    ledger_pb2_grpc.add_LedgerServicer_to_server(LedgerServicer(db), server)
+    server.add_insecure_port(f"[::]:{port}")
+    server.start()
+    log.info("ledger gRPC server started")
+    server.wait_for_termination()

package/packs/solution-architect/skills/context-graph/evals/files/8/services/ledger/clients/provider.py

@@ -0,0 +1,33 @@
+import random
+import time
+
+import httpx
+import yaml
+
+with open("config/http.yaml") as fh:
+    _cfg = yaml.safe_load(fh)["provider"]
+
+
+def _sleep(attempt: int) -> None:
+    base = _cfg["backoff"]["base_ms"] / 1000
+    time.sleep(random.uniform(0, base * (2 ** attempt)))
+
+
+def call(method: str, path: str, **kwargs) -> httpx.Response:
+    retries = _cfg["max_retries"] if method in _cfg["retry_methods"] else 0
+    for attempt in range(retries + 1):
+        try:
+            resp = httpx.request(
+                method,
+                _cfg["base_url"] + path,
+                timeout=_cfg["timeout_seconds"],
+                headers={"Authorization": f"Bearer {_cfg['api_key']}"},
+                **kwargs,
+            )
+            if resp.status_code not in (502, 503):
+                return resp
+        except httpx.TransportError:
+            if attempt == retries:
+                raise
+        _sleep(attempt)
+    return resp

package/packs/solution-architect/skills/context-graph/evals/files/8/services/ledger/db/migrations/0001_init.sql

@@ -0,0 +1,14 @@
+CREATE TABLE accounts (
+    id            UUID PRIMARY KEY,
+    currency      CHAR(3) NOT NULL,
+    balance_minor BIGINT  NOT NULL DEFAULT 0,
+    frozen        BOOLEAN NOT NULL DEFAULT FALSE
+);
+
+CREATE TABLE entries (
+    id           UUID PRIMARY KEY,
+    account_id   UUID    NOT NULL REFERENCES accounts(id),
+    amount_minor BIGINT  NOT NULL,
+    currency     CHAR(3) NOT NULL,
+    posted_at    TIMESTAMPTZ NOT NULL DEFAULT now()
+);

package/packs/solution-architect/skills/context-graph/evals/files/8/services/ledger/db/migrations/0008_idempotency_keys.sql

@@ -0,0 +1,5 @@
+CREATE TABLE idempotency_keys (
+    key          TEXT PRIMARY KEY,
+    response     JSONB NOT NULL,
+    created_at   TIMESTAMPTZ NOT NULL DEFAULT now()
+);

package/packs/solution-architect/skills/context-graph/evals/files/8/services/ledger/db/migrations/0009_fx_entries.sql

@@ -0,0 +1,4 @@
+-- FX conversions: store the converted amount and the rate used.
+ALTER TABLE entries ADD COLUMN fx_amount   NUMERIC(18,4);
+ALTER TABLE entries ADD COLUMN fx_currency CHAR(3);
+ALTER TABLE entries ADD COLUMN fx_rate     NUMERIC(18,8);

package/packs/solution-architect/skills/context-graph/evals/files/8/services/ledger/events/publisher.py

@@ -0,0 +1,28 @@
+import json
+
+import yaml
+from confluent_kafka import Producer
+
+from services.ledger.logging import get_logger
+
+log = get_logger(__name__)
+
+with open("config/messaging.yaml") as fh:
+    _cfg = yaml.safe_load(fh)
+
+_producer = Producer({
+    "bootstrap.servers": ",".join(_cfg["bootstrap_servers"]),
+    "acks": _cfg["acks"],
+})
+
+
+def publish_entry_posted(entry) -> None:
+    payload = {
+        "type": "EntryPosted",
+        "entry_id": entry.id,
+        "account_id": entry.account_id,
+        "amount_minor": entry.amount_minor,
+        "currency": entry.currency,
+    }
+    _producer.produce(_cfg["topic"], key=entry.account_id, value=json.dumps(payload))
+    log.info("event published", extra={"account_id": entry.account_id})

package/packs/solution-architect/skills/context-graph/evals/files/8/services/ledger/logging.py

@@ -0,0 +1,25 @@
+import json
+import logging
+import sys
+from datetime import datetime, timezone
+
+
+class _JsonFormatter(logging.Formatter):
+    def format(self, record: logging.LogRecord) -> str:
+        return json.dumps({
+            "ts": datetime.now(timezone.utc).isoformat(),
+            "level": record.levelname,
+            "msg": record.getMessage(),
+            "trace_id": getattr(record, "trace_id", None),
+            "account_id": getattr(record, "account_id", None),
+        })
+
+
+def get_logger(name: str) -> logging.Logger:
+    logger = logging.getLogger(name)
+    if not logger.handlers:
+        handler = logging.StreamHandler(sys.stdout)
+        handler.setFormatter(_JsonFormatter())
+        logger.addHandler(handler)
+        logger.setLevel(logging.INFO)
+    return logger

package/packs/solution-architect/skills/context-graph/evals/files/8/services/ledger/models/entry.py

@@ -0,0 +1,16 @@
+from dataclasses import dataclass
+from datetime import datetime
+from decimal import Decimal
+from typing import Optional
+
+
+@dataclass(frozen=True)
+class Entry:
+    id: str
+    account_id: str
+    amount_minor: int
+    currency: str
+    posted_at: datetime
+    fx_amount: Optional[Decimal] = None
+    fx_currency: Optional[str] = None
+    fx_rate: Optional[Decimal] = None

package/packs/solution-architect/skills/context-graph/evals/files/9/.env.example

@@ -0,0 +1,3 @@
+DATABASE_URL=postgres://tidepool:example-only@postgres:5432/tidepool
+REDIS_URL=redis://redis:6379/0
+SESSION_SECRET=replace-me

package/packs/solution-architect/skills/context-graph/evals/files/9/README.md

@@ -0,0 +1,5 @@
+# tidepool-shop
+
+Storefront API for Tidepool Outfitters. TypeScript, Express, PostgreSQL, Redis.
+
+Run locally with `docker compose up`. Decision records live in `docs/decisions/`.

package/packs/solution-architect/skills/context-graph/evals/files/9/docker-compose.yml

@@ -0,0 +1,18 @@
+services:
+  app:
+    build: .
+    ports: ["3000:3000"]
+    env_file: .env
+    depends_on: [postgres, redis]
+  worker:
+    build: .
+    command: ["node", "dist/jobs/worker.js"]
+    env_file: .env
+    depends_on: [redis]
+  postgres:
+    image: postgres:16
+    environment:
+      POSTGRES_PASSWORD: example-only
+  redis:
+    image: redis:7
+    ports: ["6379:6379"]

package/packs/solution-architect/skills/context-graph/evals/files/9/docs/decisions/001-session-storage.md

@@ -0,0 +1,21 @@
+# 001. Store user sessions in Redis
+
+Date: 2023-05-09
+
+## Status
+
+Superseded by [003](003-jwt-sessions.md)
+
+## Context
+
+We run three app containers behind the load balancer. In-memory sessions log users out
+whenever a request lands on a different container.
+
+## Decision
+
+Sessions are stored in Redis via `connect-redis`, configured in `src/session/store.ts`,
+with a 7-day TTL.
+
+## Consequences
+
+Redis becomes a hard dependency of login.

package/packs/solution-architect/skills/context-graph/evals/files/9/docs/decisions/002-api-rate-limiting.md

@@ -0,0 +1,32 @@
+---
+status: accepted
+date: 2023-11-20
+deciders: platform team
+---
+
+# Rate-limit the public API with a shared token bucket
+
+## Context and Problem Statement
+
+A partner's misconfigured sync job hit `/v1/products` 40 times a second for an hour. We need
+per-API-key limits that hold across all app containers.
+
+## Considered Options
+
+* Per-container in-memory limiter
+* Token bucket in Redis, shared by all containers
+* Limit at the CDN edge
+
+## Decision Outcome
+
+Chosen option: "Token bucket in Redis", because limits must be global and the CDN plan we
+are on cannot key on API key.
+
+Implemented in `src/middleware/rateLimit.ts`: 600 requests per minute per API key, using a
+Lua script so refill-and-take is atomic. Redis availability and failover are covered in
+DR-007.
+
+### Consequences
+
+* Good, because limits are exact across containers.
+* Bad, because if Redis is down the limiter fails open.

package/packs/solution-architect/skills/context-graph/evals/files/9/docs/decisions/003-jwt-sessions.md

@@ -0,0 +1,29 @@
+# RFC 003 — Stateless JWT sessions
+
+| Field   | Value      |
+|---------|------------|
+| State   | Proposed   |
+| Author  | r.achebe   |
+| Created | 2026-09-02 |
+| Replaces | 001       |
+
+## Motivation
+
+Mobile clients want a bearer token rather than a cookie, and we would like login to keep
+working during a Redis restart.
+
+## Proposal
+
+Issue a signed access token (15 minutes) and a refresh token (7 days). The app verifies the
+signature locally; no session lookup per request.
+
+## Open questions
+
+1. **Revocation.** Logout and "sign out everywhere" need to invalidate tokens before they
+   expire. Current thinking: keep a denylist of revoked token ids in Redis with a TTL equal to
+   the token's remaining lifetime.
+2. Key rotation schedule — needs a decision before this is accepted.
+
+## Status of discussion
+
+Not yet reviewed by the platform team.

package/packs/solution-architect/skills/context-graph/evals/files/9/docs/decisions/004-catalog-cache.md

@@ -0,0 +1,19 @@
+# 004. Cache the product catalogue in process
+
+- Status: Accepted
+- Date: 2024-02-27
+
+## Context
+
+Catalogue reads are about 70% of API traffic, and the catalogue changes a few times a day.
+
+## Decision
+
+Each app container holds the catalogue in an in-process LRU cache (`lru-cache`, 5,000 items,
+10-minute TTL) in `src/catalog/cache.ts`. We deliberately do **not** put the catalogue in
+Redis: it adds a network hop to the hottest path for data that is fine to be a few minutes
+stale per container.
+
+## Consequences
+
+Containers may briefly disagree after a catalogue update. That is acceptable.

package/packs/solution-architect/skills/context-graph/evals/files/9/src/catalog/cache.ts

@@ -0,0 +1,13 @@
+import { redis } from "../lib/redis";
+import { loadProduct, type Product } from "./repository";
+
+const TTL_SECONDS = 600;
+
+// Moved to Redis so all containers see catalogue updates at once (see #482).
+export async function getProduct(id: string): Promise<Product | null> {
+  const hit = await redis.get(`catalog:${id}`);
+  if (hit) return JSON.parse(hit) as Product;
+  const product = await loadProduct(id);
+  if (product) await redis.set(`catalog:${id}`, JSON.stringify(product), { EX: TTL_SECONDS });
+  return product;
+}

package/packs/solution-architect/skills/context-graph/evals/files/9/src/catalog/repository.ts

@@ -0,0 +1,13 @@
+import { db } from "../lib/db";
+
+export interface Product {
+  id: string;
+  name: string;
+  priceCents: number;
+}
+
+export async function loadProduct(id: string): Promise<Product | null> {
+  const rows = await db.query("SELECT id, name, price_cents FROM products WHERE id = $1", [id]);
+  if (rows.length === 0) return null;
+  return { id: rows[0].id, name: rows[0].name, priceCents: rows[0].price_cents };
+}

package/packs/solution-architect/skills/context-graph/evals/files/9/src/jobs/email.ts

@@ -0,0 +1,3 @@
+export async function sendEmail(data: { orderId: string; to: string }): Promise<void> {
+  console.log(`would send order confirmation for ${data.orderId} to ${data.to}`);
+}

package/packs/solution-architect/skills/context-graph/evals/files/9/src/jobs/export.ts

@@ -0,0 +1,3 @@
+export async function exportOrder(data: { orderId: string }): Promise<void> {
+  console.log(`would export order ${data.orderId} to the warehouse feed`);
+}

package/packs/solution-architect/skills/context-graph/evals/files/9/src/jobs/queue.ts

@@ -0,0 +1,10 @@
+import { Queue } from "bullmq";
+
+const connection = { url: process.env.REDIS_URL };
+
+export const emailQueue = new Queue("email", { connection });
+export const orderExportQueue = new Queue("order-export", { connection });
+
+export async function enqueueOrderConfirmation(orderId: string, to: string) {
+  await emailQueue.add("order-confirmation", { orderId, to }, { attempts: 5 });
+}

package/packs/solution-architect/skills/context-graph/evals/files/9/src/jobs/worker.ts

@@ -0,0 +1,8 @@
+import { Worker } from "bullmq";
+import { sendEmail } from "./email";
+import { exportOrder } from "./export";
+
+const connection = { url: process.env.REDIS_URL };
+
+new Worker("email", async (job) => sendEmail(job.data), { connection });
+new Worker("order-export", async (job) => exportOrder(job.data), { connection });

package/packs/solution-architect/skills/context-graph/evals/files/9/src/lib/db.ts

@@ -0,0 +1,10 @@
+import { Pool } from "pg";
+
+const pool = new Pool({ connectionString: process.env.DATABASE_URL });
+
+export const db = {
+  async query(text: string, params: unknown[] = []) {
+    const result = await pool.query(text, params);
+    return result.rows;
+  },
+};

package/packs/solution-architect/skills/context-graph/evals/files/9/src/lib/redis.ts

@@ -0,0 +1,8 @@
+import { createClient } from "redis";
+
+export const redis = createClient({ url: process.env.REDIS_URL });
+redis.on("error", (err) => console.error("redis error", err));
+
+export async function connectRedis(): Promise<void> {
+  if (!redis.isOpen) await redis.connect();
+}

package/packs/solution-architect/skills/context-graph/evals/files/9/src/middleware/rateLimit.ts

@@ -0,0 +1,26 @@
+import type { Request, Response, NextFunction } from "express";
+import { redis } from "../lib/redis";
+
+const LIMIT_PER_MINUTE = 600;
+
+const TAKE_TOKEN = `
+local tokens = tonumber(redis.call('GET', KEYS[1]) or ARGV[1])
+if tokens <= 0 then return 0 end
+redis.call('SET', KEYS[1], tokens - 1, 'EX', 60, 'KEEPTTL')
+return 1
+`;
+
+export async function rateLimit(req: Request, res: Response, next: NextFunction) {
+  const apiKey = req.header("x-api-key");
+  if (!apiKey) return next();
+  try {
+    const ok = await redis.eval(TAKE_TOKEN, {
+      keys: [`rl:${apiKey}`],
+      arguments: [String(LIMIT_PER_MINUTE)],
+    });
+    if (ok === 0) return res.status(429).json({ error: "rate_limited" });
+  } catch {
+    // fail open, per decision 002
+  }
+  next();
+}

package/packs/solution-architect/skills/context-graph/evals/files/9/src/server.ts

@@ -0,0 +1,17 @@
+import express from "express";
+import { connectRedis } from "./lib/redis";
+import { sessionMiddleware } from "./session/store";
+import { rateLimit } from "./middleware/rateLimit";
+import { getProduct } from "./catalog/cache";
+
+const app = express();
+app.use(sessionMiddleware);
+app.use("/v1", rateLimit);
+
+app.get("/v1/products/:id", async (req, res) => {
+  const product = await getProduct(req.params.id);
+  if (!product) return res.status(404).end();
+  res.json(product);
+});
+
+connectRedis().then(() => app.listen(3000));

package/packs/solution-architect/skills/context-graph/evals/files/9/src/session/store.ts

@@ -0,0 +1,10 @@
+import session from "express-session";
+import RedisStore from "connect-redis";
+import { redis } from "../lib/redis";
+
+export const sessionMiddleware = session({
+  store: new RedisStore({ client: redis, prefix: "sess:", ttl: 60 * 60 * 24 * 7 }),
+  secret: process.env.SESSION_SECRET ?? "",
+  resave: false,
+  saveUninitialized: false,
+});

package/packs/solution-architect/skills/context-graph/examples/inputs/order-events/docs/adr/0004-kafka-for-order-events.md

@@ -0,0 +1,19 @@
+# ADR-0004: Kafka for order events
+
+## Status
+
+Accepted
+
+Date: 2025-03-02
+
+## Context
+
+Order events feed billing, notifications and the warehouse. We need replay for new consumers.
+
+## Decision
+
+Order events are published to Kafka from `services/orders/`, one topic per event type.
+
+## Consequences
+
+Replay works for a new consumer. We run a Kafka cluster.

package/packs/solution-architect/skills/context-graph/examples/inputs/order-events/docs/adr/0006-email-receipts.md

@@ -0,0 +1,7 @@
+---
+status: accepted
+date: 2025-06-11
+---
+# Email receipts from the notifications service
+
+Receipts are sent by `services/notifications/` when it reads an OrderPlaced event (see ADR-0004).