skilldrop-cli 0.16.44 → 0.16.46

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).

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

@@ -0,0 +1,19 @@
+---
+status: accepted
+date: 2026-02-10
+---
+# Order events on SQS
+
+## Context
+
+Only two consumers ever replayed, and the Kafka cluster is the team's largest on-call load.
+
+## Decision
+
+Supersedes ADR-0004. Order events move to SQS queues, one per consumer, published from
+`services/orders/`. The bridge in `services/kafka-bridge/` is removed once billing has moved.
+
+## Consequences
+
+One fewer system to run, and the volume fits SQS. Replay for a new consumer now means a
+backfill from the orders table.

package/packs/solution-architect/skills/context-graph/examples/order-events.md

@@ -0,0 +1,63 @@
+# Worked example: why do order events go through Kafka?
+
+A made-up repository, in [`inputs/order-events/`](inputs/order-events/), with three ADRs:
+- **ADR-0004** chose Kafka for order events in 2025.
+- **ADR-0006** has receipts sent when the notifications service reads an OrderPlaced event, and
+  cites ADR-0004.
+- **ADR-0009** moved order events to SQS in 2026, and says it supersedes ADR-0004. Nobody updated
+  ADR-0004's Status line, and ADR-0009 names a bridge folder that has since been deleted.
+
+## The request
+
+> I'm changing `services/orders/publisher.py`. Why do we publish order events to Kafka, and is
+> that still the plan?
+
+## Script runs
+
+```bash
+python3 scripts/context_graph.py --root examples/inputs/order-events --why services/orders/publisher.py
+python3 scripts/context_graph.py --root examples/inputs/order-events
+```
+
+The `--why` output:
+
+```text
+# Decisions governing services/orders/publisher.py
+
+- **ADR-0009 Order events on SQS** (accepted, current, 2026-02-10), via `services/orders/`: docs/adr/0009-sqs-for-order-events.md
+- **ADR-0004 Kafka for order events** (marked accepted, but superseded by ADR-0009, 2025-03-02), via `services/orders/`: docs/adr/0004-kafka-for-order-events.md
+```
+
+The full check, which exits 1 because it found problems:
+
+```text
+## Problems (2)
+
+- ADR-0004 is still marked Accepted, but ADR-0009 supersedes it: mark it 'Superseded by ADR-0009'
+- ADR-0009 is accepted but points at code that is gone: services/kafka-bridge
+
+## Warnings (1)
+
+- ADR-0006 is current but cites ADR-0004, which ADR-0009 supersedes: check it still holds
+```
+
+## The reply
+
+It isn't the plan any more. ADR-0009 (accepted 2026-02-10) moved order events from Kafka to SQS
+queues, one per consumer, published from `services/orders/`. Its reasons: "only two consumers
+ever replayed, and the Kafka cluster is the team's largest on-call load". It replaces ADR-0004,
+which chose Kafka in 2025. ADR-0004's own Status line still says Accepted, so anyone reading it on
+its own gets the wrong answer.
+
+Before you change the publisher:
+
+1. **ADR-0004 needs its status fixed.** Change `## Status` to `Superseded by ADR-0009`, linked
+   to `0009-sqs-for-order-events.md`.
+2. **ADR-0009 names `services/kafka-bridge/`, which no longer exists.** If billing has moved, add a
+   line saying the bridge was removed. If it hasn't, find where the bridge went.
+3. **ADR-0006 (receipts) still cites ADR-0004.** It has the notifications service read OrderPlaced
+   events, which now come from an SQS queue. Check that the receipts consumer has its queue before
+   you change what the publisher sends.
+
+What the records don't say: when billing moved off Kafka, and whether replay for a new consumer
+(now a backfill from the orders table, per ADR-0009) has been tested.

package/packs/solution-architect/skills/context-graph/manifest.json

@@ -0,0 +1,33 @@
+{
+  "name": "context-graph",
+  "version": "0.1.0",
+  "description": "Map the decisions behind a codebase from its ADRs, RFCs and design records — each record's status and date, what supersedes or amends what, which records cite which, the files and folders each decision governs, and with git the commits that implemented it — then answer \"why is it like this?\" from the record and check the record is still true. Finds supersessions only one side records, current decisions pointing at code that is gone, two current decisions governing the same path, and references to records that don't exist. Use when the user asks \"why do we use X\", \"which decisions govern this file or service\", \"is this ADR still current\", \"are our ADRs out of date\", \"what was decided before I change this\", wants a map of the architecture decisions, or is onboarding onto a codebase's history.",
+  "entrypoint": "SKILL.md",
+  "deps": { "npm": [], "pip": [] },
+  "env": { "required": [], "optional": [] },
+  "related": [
+    "adr-generator",
+    "codebase-tour",
+    "reverse-architecture",
+    "decision-log"
+  ],
+  "handoff": [
+    {
+      "to": "adr-generator",
+      "when": "a decision is live but unrecorded, or a record needs superseding, deprecating or correcting",
+      "purpose": "Write the new or corrected record, with the supersession link the graph found missing.",
+      "fallback": "If adr-generator is absent, give the record's title, status line, the context in two sentences, the decision and its consequences, and the exact Superseded by line for the old record."
+    }
+  ],
+  "tags": ["architecture", "adr", "decision-records", "onboarding", "documentation"],
+  "permissions": {
+    "network": [],
+    "commands": ["git"],
+    "files": "named-paths",
+    "notes": "context_graph.py reads the decision-record folders under --root and checks whether the paths they name exist. With --git it runs `git log` read-only. It writes only to the -o and --mermaid paths."
+  },
+  "model": {
+    "tier": "standard",
+    "rationale": "The graph and its checks are computed by the script; the model reads records, quotes the rationale and writes the fixes."
+  }
+}