skilldrop-cli 0.16.45 → 0.16.46

package/packs/solution-architect/skills/context-graph/evals/files/12/src/store/delivery_log.py

@@ -0,0 +1,18 @@
+"""Delivery attempt log (see ADR-0002)."""
+from src.db import execute
+
+
+def record_attempt(event_id, partner_id, attempt_no, status_code):
+    execute(
+        "INSERT INTO delivery_attempts (event_id, partner_id, attempt_no, status_code, sent_at) "
+        "VALUES (%s, %s, %s, %s, now())",
+        (event_id, partner_id, attempt_no, status_code),
+    )
+
+
+def mark_failed(event_id, partner_id):
+    execute(
+        "UPDATE delivery_attempts SET final_status = 'failed' "
+        "WHERE event_id = %s AND partner_id = %s",
+        (event_id, partner_id),
+    )

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

@@ -0,0 +1,3 @@
+# shopfront
+
+The Brindle & Co. web store monolith: catalog, cart, checkout. Design records live in `docs/decisions/`.

package/packs/solution-architect/skills/context-graph/evals/files/13/config/cache.yaml

@@ -0,0 +1,2 @@
+pricing:
+  ttl_seconds: 60

package/packs/solution-architect/skills/context-graph/evals/files/13/config/settings.yaml

@@ -0,0 +1,2 @@
+PRICING_SVC_URL: http://pricing-svc.internal:8080
+REDIS_URL: redis://cache.internal:6379/0

package/packs/solution-architect/skills/context-graph/evals/files/13/docs/decisions/RFC-008-pricing-from-erp.md

@@ -0,0 +1,10 @@
+# RFC-008: Read prices from the Halvorsen ERP
+
+Status: Accepted
+Date: 2023-02-07
+Author: M. Okafor
+Governs: shopfront/pricing/erp_client.py
+
+## Decision
+Shopfront reads the current price for a SKU from the Halvorsen ERP `GetItemPrice` SOAP call
+through `shopfront/pricing/erp_client.py`. The ERP is the single source of truth for prices.

package/packs/solution-architect/skills/context-graph/evals/files/13/docs/decisions/RFC-012-pricing-cache.md

@@ -0,0 +1,23 @@
+# RFC-012: Cache prices in Redis
+
+Status: Accepted
+Date: 2023-06-14
+Author: M. Okafor
+Builds on: RFC-008
+Governs: shopfront/pricing/cache.py, config/cache.yaml
+
+## Context
+The Halvorsen ERP limits `GetItemPrice` to 40 requests/second per client and its p95 latency is
+~900 ms. During the June sale the product page timed out and the ERP throttled us for 20 minutes.
+
+## Decision
+Put a read-through Redis cache in front of pricing. Key `price:{sku}`, TTL 60 seconds. A price
+change in the ERP can therefore take up to a minute to show on the site; merchandising agreed
+this is acceptable.
+
+## Alternatives considered
+- Nightly price snapshot: rejected, price changes during sales must show within minutes.
+- Asking Halvorsen to raise the limit: rejected by the vendor.
+
+## Revisit when
+The ERP rate limit no longer applies to us.

package/packs/solution-architect/skills/context-graph/evals/files/13/docs/decisions/RFC-015-checkout-price-lock.md

@@ -0,0 +1,15 @@
+# RFC-015: Lock the price for the duration of checkout
+
+Status: Accepted
+Date: 2024-01-09
+Author: J. Lindqvist
+Amends: RFC-012
+Governs: shopfront/checkout/lock.py
+
+## Context
+Customers were charged a different price from the one shown when a price changed mid-checkout.
+
+## Decision
+When a cart enters checkout, the price a customer saw must be the price they are charged for
+15 minutes. We do this by reusing the pricing cache: checkout keeps the cached price for each
+SKU in the cart alive for 15 minutes.

package/packs/solution-architect/skills/context-graph/evals/files/13/docs/decisions/RFC-019-pricing-service.md

@@ -0,0 +1,17 @@
+# RFC-019: Read prices from pricing-svc instead of the ERP
+
+Status: Proposed
+Date: 2025-03-18
+Author: P. Achterberg
+Supersedes: RFC-008
+
+## Context
+The pricing team now runs `pricing-svc`, a REST service that replicates ERP prices within
+5 seconds of a change. It has no per-client rate limit and a p95 of 35 ms.
+
+## Proposal
+Shopfront calls `GET {PRICING_SVC_URL}/v1/prices/{sku}` instead of the ERP SOAP call, and
+`erp_client.py` is deleted.
+
+## Open questions
+- Do we still need the Redis cache from RFC-012 once the ERP is out of the path?

package/packs/solution-architect/skills/context-graph/evals/files/13/shopfront/catalog/views.py

@@ -0,0 +1,8 @@
+"""Product detail page."""
+from shopfront.pricing import cache
+
+
+def product_detail(request, sku):
+    product = request.catalog.get(sku)
+    price = cache.get_price(sku)
+    return request.render("product.html", {"product": product, "price": price})

package/packs/solution-architect/skills/context-graph/evals/files/13/shopfront/checkout/lock.py

@@ -0,0 +1,14 @@
+"""Hold prices steady while a cart is in checkout (RFC-015)."""
+from shopfront.pricing import cache
+
+LOCK_SECONDS = 15 * 60
+
+
+def lock_cart_prices(cart) -> None:
+    for line in cart.lines:
+        cache.get_price(line.sku)              # make sure the entry exists
+        cache.touch(line.sku, LOCK_SECONDS)    # keep it alive for the checkout window
+
+
+def price_for_charge(sku: str) -> dict:
+    return cache.get_price(sku)

package/packs/solution-architect/skills/context-graph/evals/files/13/shopfront/pricing/cache.py

@@ -0,0 +1,22 @@
+"""Read-through price cache (RFC-012)."""
+import json
+
+from shopfront.redis_client import redis
+from shopfront.settings import load_yaml
+from shopfront.pricing.client import fetch_price
+
+TTL = load_yaml("config/cache.yaml")["pricing"]["ttl_seconds"]
+
+
+def get_price(sku: str) -> dict:
+    key = f"price:{sku}"
+    hit = redis.get(key)
+    if hit is not None:
+        return json.loads(hit)
+    price = fetch_price(sku)
+    redis.set(key, json.dumps(price), ex=TTL)
+    return price
+
+
+def touch(sku: str, ttl: int) -> None:
+    redis.expire(f"price:{sku}", ttl)

package/packs/solution-architect/skills/context-graph/evals/files/13/shopfront/pricing/client.py

@@ -0,0 +1,10 @@
+"""Fetch the current price for a SKU."""
+import json
+import urllib.request
+
+from shopfront.settings import PRICING_SVC_URL
+
+
+def fetch_price(sku: str) -> dict:
+    with urllib.request.urlopen(f"{PRICING_SVC_URL}/v1/prices/{sku}", timeout=2) as resp:
+        return json.load(resp)  # {"sku": ..., "amount_minor": ..., "currency": ...}

package/packs/solution-architect/skills/context-graph/evals/files/14/docs/rfcs/0001-idempotency-keys.md

@@ -0,0 +1,33 @@
+---
+rfc: 0001
+title: Idempotency keys on every charge request
+status: accepted
+date: 2024-02-12
+authors: [mira.okafor]
+governs:
+  - src/payments/charge.ts
+---
+
+# RFC-0001: Idempotency keys on every charge request
+
+## Problem
+
+Mobile clients retry on flaky networks. Without a dedupe key, a retried
+`POST /charges` can bill a customer twice. We had 14 double-charge tickets in
+January 2024.
+
+## Decision
+
+Every `POST /charges` request MUST carry an `Idempotency-Key` header. The
+charge handler rejects requests without one (HTTP 400) and stores the key with
+the charge for 24 hours. A repeat key returns the original response instead of
+creating a new charge.
+
+The check lives in the charge handler itself, not in the retry layer: the
+retry layer only sees our own outbound retries to the card processor, not
+inbound client retries.
+
+## Consequences
+
+- Clients must generate a UUID per logical charge.
+- The `idempotency_keys` table grows; rows expire after 24 hours.

package/packs/solution-architect/skills/context-graph/evals/files/14/docs/rfcs/0002-processor-retry-policy.md

@@ -0,0 +1,26 @@
+---
+rfc: 0002
+title: Fixed-interval retries to the card processor
+status: superseded
+superseded_by: 0005
+date: 2024-02-20
+authors: [dev.raman]
+governs:
+  - src/payments/retry.ts
+---
+
+# RFC-0002: Fixed-interval retries to the card processor
+
+## Problem
+
+Calls to the card processor occasionally time out. We need a retry policy.
+
+## Decision
+
+Retry failed processor calls up to 3 times with a fixed 2-second delay
+between attempts.
+
+## Consequences
+
+- Simple to reason about.
+- Under a processor outage every instance retries in lockstep.

package/packs/solution-architect/skills/context-graph/evals/files/14/docs/rfcs/0003-money-in-minor-units.md

@@ -0,0 +1,31 @@
+---
+rfc: 0003
+title: Represent money as integer minor units
+status: accepted
+date: 2024-03-04
+authors: [mira.okafor]
+governs:
+  - src/payments/amount.ts
+  - src/payments/charge.ts
+---
+
+# RFC-0003: Represent money as integer minor units
+
+## Problem
+
+A refund of 19.99 was stored as 19.989999999999998 after a floating-point
+round trip, and the ledger failed to reconcile.
+
+## Decision
+
+All monetary amounts inside the service and on the wire are integers in the
+currency's minor unit (cents for USD, pence for GBP), in a field named
+`amountMinor`, paired with an ISO 4217 `currency` code. No decimal or
+floating-point money fields anywhere in `src/payments/`. Conversion to a
+display string happens only at the edge, via `formatAmount()` in
+`src/payments/amount.ts`.
+
+## Consequences
+
+- API consumers must send `amountMinor: 1999`, not `amount: 19.99`.
+- Currencies with three minor digits (e.g. KWD) work without special cases.

package/packs/solution-architect/skills/context-graph/evals/files/14/docs/rfcs/0004-webhook-signing.md

@@ -0,0 +1,27 @@
+---
+rfc: 0004
+title: HMAC-SHA256 signatures on outbound webhooks
+status: accepted
+date: 2024-04-15
+authors: [dev.raman]
+governs:
+  - src/webhooks/sign.ts
+---
+
+# RFC-0004: HMAC-SHA256 signatures on outbound webhooks
+
+## Problem
+
+Merchants cannot tell a genuine `charge.succeeded` webhook from a forged one.
+
+## Decision
+
+Every outbound webhook carries a `Ledgerline-Signature` header: an
+HMAC-SHA256 of `timestamp + "." + body`, keyed with the merchant's webhook
+secret. Signing is implemented in one place, `src/webhooks/sign.ts`, and every
+sender must call `signPayload()` from it.
+
+## Consequences
+
+- Merchants verify with a constant-time compare.
+- Rotating a merchant secret invalidates in-flight retries.

package/packs/solution-architect/skills/context-graph/evals/files/14/docs/rfcs/0005-retry-with-jitter.md

@@ -0,0 +1,30 @@
+---
+rfc: 0005
+title: Exponential backoff with full jitter for processor retries
+status: accepted
+supersedes: 0002
+date: 2024-06-03
+authors: [dev.raman, mira.okafor]
+governs:
+  - src/payments/retry.ts
+---
+
+# RFC-0005: Exponential backoff with full jitter for processor retries
+
+## Problem
+
+During the processor outage on 2024-05-21, RFC-0002's fixed 2-second retries
+made all 40 instances hit the processor in synchronised waves, extending the
+outage on our side by about 25 minutes.
+
+## Decision
+
+Replace RFC-0002. Retry failed processor calls up to 4 times using
+exponential backoff with full jitter: before attempt `n`, wait a random delay
+between 0 and `min(8000, 250 * 2^n)` milliseconds. Never retry a 4xx response
+from the processor.
+
+## Consequences
+
+- Retries spread out; no lockstep under outage.
+- Worst-case added latency is bounded at roughly 15 seconds.

package/packs/solution-architect/skills/context-graph/evals/files/14/docs/rfcs/0006-idempotency-at-gateway.md

@@ -0,0 +1,28 @@
+---
+rfc: 0006
+title: Move idempotency handling to the API gateway
+status: proposed
+date: 2024-09-30
+authors: [tomas.vey]
+governs:
+  - src/payments/charge.ts
+---
+
+# RFC-0006: Move idempotency handling to the API gateway
+
+## Problem
+
+Three services now implement their own idempotency-key tables, each slightly
+differently.
+
+## Proposal
+
+Enforce `Idempotency-Key` once at the API gateway and remove the per-service
+checks, including the one RFC-0001 put in the charge handler.
+
+## Open questions
+
+- The gateway team has not yet committed to a delivery date.
+- How are responses replayed for keys the gateway has seen?
+
+Not yet reviewed. Until this is accepted, RFC-0001 stands.

package/packs/solution-architect/skills/context-graph/evals/files/14/pr-summary.md

@@ -0,0 +1,27 @@
+# PR #412 — "Simplify charge path" (author: tomas.vey)
+
+Description from the author:
+> Cleanup of the charge path. Retries are back to the simple policy from RFC-0002,
+> which is much easier to reason about. Dedupe now happens in the retry layer so the
+> header check in the handler is redundant. All in line with our RFCs.
+
+## Files changed
+
+### src/payments/charge.ts  (+9 / -14)
+- `ChargeRequest.amountMinor: number` renamed to `amount: number`; value is now
+  decimal major units (e.g. `19.99`) "to match what the mobile app sends".
+- Removed the `Idempotency-Key` header check and the `idempotencyStore.get/put`
+  calls. Comment added: `// dedupe handled by retry layer`.
+- `assertMinorUnits(req.amountMinor)` call removed.
+
+### src/payments/retry.ts  (+6 / -12)
+- `MAX_ATTEMPTS` 4 -> 3.
+- Backoff replaced with a fixed `await sleep(2000)` between attempts.
+- 4xx short-circuit kept.
+- Header comment changed to `// Processor retry policy: RFC-0002`.
+
+### src/webhooks/sign.ts -> src/webhooks/signature.ts  (rename, no content change)
+- `send.ts` import updated to `./signature`.
+
+### src/webhooks/send.ts  (+1 / -1)
+- `console.log` replaced with `logger.info` (same fields).

package/packs/solution-architect/skills/context-graph/evals/files/14/src/payments/amount.ts

@@ -0,0 +1,10 @@
+// RFC-0003: money is integer minor units.
+export function assertMinorUnits(amountMinor: number): void {
+  if (!Number.isInteger(amountMinor) || amountMinor < 0) {
+    throw new Error("amountMinor must be a non-negative integer");
+  }
+}
+
+export function formatAmount(amountMinor: number, currency: string, digits = 2): string {
+  return `${(amountMinor / 10 ** digits).toFixed(digits)} ${currency}`;
+}

package/packs/solution-architect/skills/context-graph/evals/files/14/src/payments/charge.ts

@@ -0,0 +1,28 @@
+import { retryProcessorCall } from "./retry";
+import { assertMinorUnits } from "./amount";
+import { idempotencyStore } from "./idempotency";
+import { sendWebhook } from "../webhooks/send";
+
+export interface ChargeRequest {
+  amountMinor: number; // integer minor units, see RFC-0003
+  currency: string;    // ISO 4217
+  cardToken: string;
+}
+
+export async function createCharge(req: ChargeRequest, headers: Record<string, string>) {
+  const key = headers["idempotency-key"];
+  if (!key) {
+    return { status: 400, body: { error: "Idempotency-Key header is required" } }; // RFC-0001
+  }
+  const previous = await idempotencyStore.get(key);
+  if (previous) return previous;
+
+  assertMinorUnits(req.amountMinor);
+  const result = await retryProcessorCall(() => processor.charge(req));
+  const response = { status: 201, body: result };
+  await idempotencyStore.put(key, response, 24 * 3600);
+  await sendWebhook("charge.succeeded", result);
+  return response;
+}
+
+declare const processor: { charge(req: ChargeRequest): Promise<unknown> };

package/packs/solution-architect/skills/context-graph/evals/files/14/src/payments/idempotency.ts

@@ -0,0 +1,4 @@
+export const idempotencyStore = {
+  async get(_key: string): Promise<any> { return undefined; },
+  async put(_key: string, _value: unknown, _ttlSeconds: number): Promise<void> {},
+};

package/packs/solution-architect/skills/context-graph/evals/files/14/src/payments/retry.ts

@@ -0,0 +1,21 @@
+// Processor retry policy: RFC-0005 (supersedes RFC-0002).
+const MAX_ATTEMPTS = 4;
+const BASE_MS = 250;
+const CAP_MS = 8000;
+
+export async function retryProcessorCall<T>(fn: () => Promise<T>): Promise<T> {
+  let lastErr: unknown;
+  for (let n = 0; n < MAX_ATTEMPTS; n++) {
+    try {
+      return await fn();
+    } catch (err: any) {
+      if (err?.status >= 400 && err?.status < 500) throw err; // never retry 4xx
+      lastErr = err;
+      const ceiling = Math.min(CAP_MS, BASE_MS * 2 ** n);
+      await sleep(Math.random() * ceiling); // full jitter
+    }
+  }
+  throw lastErr;
+}
+
+const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms));

package/packs/solution-architect/skills/context-graph/evals/files/14/src/webhooks/send.ts

@@ -0,0 +1,9 @@
+import { signPayload } from "./sign";
+
+export async function sendWebhook(event: string, payload: unknown): Promise<void> {
+  const body = JSON.stringify({ event, payload });
+  const ts = Math.floor(Date.now() / 1000);
+  const signature = signPayload(process.env.WEBHOOK_SECRET ?? "placeholder-secret", ts, body);
+  console.log("webhook", event, signature.slice(0, 8));
+  // HTTP delivery omitted in this excerpt
+}

package/packs/solution-architect/skills/context-graph/evals/files/14/src/webhooks/sign.ts

@@ -0,0 +1,6 @@
+import { createHmac } from "crypto";
+
+// RFC-0004: the single place outbound webhooks are signed.
+export function signPayload(secret: string, timestamp: number, body: string): string {
+  return createHmac("sha256", secret).update(`${timestamp}.${body}`).digest("hex");
+}

package/packs/solution-architect/skills/context-graph/evals/files/15/deploy/services.yaml

@@ -0,0 +1,14 @@
+# Services deployed to the production cluster
+services:
+  - name: shipments
+    path: services/shipments
+    datastores: [postgres:haulmark_core]
+  - name: telemetry
+    path: services/telemetry
+    datastores: [postgres:haulmark_telemetry]
+  - name: api
+    path: services/api
+    datastores: [postgres:haulmark_core]
+  - name: dashboard
+    path: web/dashboard
+    datastores: []

package/packs/solution-architect/skills/context-graph/evals/files/15/doc/adr/0001-record-architecture-decisions.md

@@ -0,0 +1,20 @@
+# 1. Record architecture decisions
+
+Date: 2021-01-18
+
+## Status
+
+Accepted
+
+## Context
+
+We need to record the architectural decisions made on Haulmark.
+
+## Decision
+
+We will use Architecture Decision Records, as described by Michael Nygard,
+kept in `doc/adr/`.
+
+## Consequences
+
+See Michael Nygard's article "Documenting Architecture Decisions".

package/packs/solution-architect/skills/context-graph/evals/files/15/doc/adr/0002-use-postgresql-for-shipment-data.md

@@ -0,0 +1,23 @@
+# 2. Use PostgreSQL for shipment data
+
+Date: 2021-02-10
+
+## Status
+
+Accepted
+
+## Context
+
+Shipments, stops and consignees are relational and need transactional
+updates when a stop is marked delivered. The team already runs PostgreSQL 13.
+
+## Decision
+
+Shipment data lives in a single PostgreSQL database, `haulmark_core`, owned by
+`services/shipments/`. Other services read shipment data only through the
+shipments API, never by connecting to the database directly.
+
+## Consequences
+
+Strong consistency for status transitions. Schema migrations are needed for
+new shipment fields.

package/packs/solution-architect/skills/context-graph/evals/files/15/doc/adr/0003-store-vehicle-telemetry-in-cassandra.md

@@ -0,0 +1,22 @@
+# 3. Store vehicle telemetry in Cassandra
+
+Date: 2021-06-02
+
+## Status
+
+Superseded by [8. Store vehicle telemetry in TimescaleDB](0008-store-vehicle-telemetry-in-timescaledb.md)
+
+## Context
+
+Each truck reports GPS position every 5 seconds. At 1,200 trucks this is
+about 20 million rows a day, too much write volume for `haulmark_core`.
+
+## Decision
+
+Vehicle telemetry is written to a 3-node Cassandra cluster by
+`services/telemetry/`, partitioned by vehicle and day.
+
+## Consequences
+
+High write throughput. Ad-hoc queries (e.g. "all trucks within 5 km of the
+depot yesterday") are hard to express.

package/packs/solution-architect/skills/context-graph/evals/files/15/doc/adr/0004-use-redis-for-session-storage.md

@@ -0,0 +1,22 @@
+# 4. Use Redis for session storage
+
+Date: 2021-07-19
+
+## Status
+
+Accepted
+
+## Context
+
+The dispatcher web app needs server-side sessions shared across the API
+instances in `services/api/`.
+
+## Decision
+
+Sessions are stored in Redis with a 12-hour TTL, keyed by an opaque session
+ID held in a cookie.
+
+## Consequences
+
+One more piece of infrastructure to run. Logging out everywhere is a single
+key delete.

package/packs/solution-architect/skills/context-graph/evals/files/15/doc/adr/0005-use-react-for-dispatcher-dashboard.md

@@ -0,0 +1,19 @@
+# 5. Use React for the dispatcher dashboard
+
+Date: 2021-09-06
+
+## Status
+
+Accepted
+
+## Context
+
+The dispatcher dashboard is moving off server-rendered templates.
+
+## Decision
+
+We will build the dashboard in React.
+
+## Consequences
+
+The front-end team needs a separate build pipeline.

package/packs/solution-architect/skills/context-graph/evals/files/15/doc/adr/0006-archive-delivered-shipments-to-object-storage.md

@@ -0,0 +1,23 @@
+# 6. Archive delivered shipments to object storage
+
+Date: 2022-03-14
+
+## Status
+
+Accepted
+
+## Context
+
+`haulmark_core` has grown to 900 GB, most of it shipments delivered more
+than a year ago that are only read for audits.
+
+## Decision
+
+A nightly job in `services/archiver/` moves shipments delivered more than
+90 days ago out of `haulmark_core` into S3-compatible object storage as
+Parquet files, one file per depot per day, and deletes them from PostgreSQL.
+
+## Consequences
+
+`haulmark_core` stays small. Audit queries over archived shipments go
+through the object store, not the shipments API.

package/packs/solution-architect/skills/context-graph/evals/files/15/doc/adr/0007-move-shipment-records-to-mongodb.md

@@ -0,0 +1,23 @@
+# 7. Move shipment records to MongoDB
+
+Date: 2022-08-22
+
+## Status
+
+Accepted
+
+## Context
+
+Enterprise customers want custom fields on shipments (purchase order numbers,
+temperature bands, hazmat codes) that differ per customer. Every new field
+currently needs a PostgreSQL migration.
+
+## Decision
+
+Shipment records will be stored as documents in MongoDB, owned by
+`services/shipments/`, so per-customer fields need no schema migration.
+
+## Consequences
+
+Status transitions that touch several stops lose multi-row transactions
+unless we use MongoDB multi-document transactions.