skilldrop-cli 0.16.44 → 0.16.46

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.

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

@@ -0,0 +1,28 @@
+# 8. Store vehicle telemetry in TimescaleDB
+
+Date: 2023-04-11
+
+## Status
+
+Accepted
+
+Supersedes [3. Store vehicle telemetry in Cassandra](0003-store-vehicle-telemetry-in-cassandra.md)
+
+## Context
+
+The Cassandra cluster from ADR 3 needs specialist operations knowledge
+nobody on the team has, and geo queries over telemetry are now a product
+requirement.
+
+## Decision
+
+Vehicle telemetry moves to TimescaleDB (a PostgreSQL extension) in a
+separate database, `haulmark_telemetry`, written by `services/telemetry/`,
+using a hypertable partitioned by time with PostGIS for geo queries.
+Raw points are kept for 30 days and downsampled after that, as set out in
+[10. Telemetry retention and downsampling](0010-telemetry-retention-and-downsampling.md).
+
+## Consequences
+
+One database technology to operate instead of two. Write throughput must be
+watched as the fleet grows past 2,000 trucks.

package/packs/solution-architect/skills/context-graph/evals/files/15/doc/adr/0009-stateless-sessions-with-signed-cookies.md

@@ -0,0 +1,24 @@
+# 9. Stateless sessions with signed cookies
+
+Date: 2024-05-07
+
+## Status
+
+Accepted
+
+Supersedes [4. Use Redis for session storage](0004-use-redis-for-session-storage.md)
+
+## Context
+
+Redis was the only stateful dependency of `services/api/` and caused two
+outages in Q1 2024 when its primary failed over.
+
+## Decision
+
+Sessions are stateless: a signed, encrypted cookie carries the dispatcher's
+user ID, role and an 8-hour expiry. Redis is removed from `services/api/`.
+
+## Consequences
+
+No session store to operate. Revoking a single session before expiry needs a
+short deny-list, kept in `haulmark_core`.

package/packs/solution-architect/skills/context-graph/evals/files/15/services/api/session.py

@@ -0,0 +1,17 @@
+"""Dispatcher sessions for services/api (ADR 9): signed, encrypted cookies, no server store."""
+import os
+import time
+
+from itsdangerous import URLSafeTimedSerializer
+
+SECRET = os.environ.get("SESSION_SECRET", "placeholder-not-a-real-secret")
+MAX_AGE_SECONDS = 8 * 3600
+_serializer = URLSafeTimedSerializer(SECRET, salt="haulmark-session")
+
+
+def issue(user_id: str, role: str) -> str:
+    return _serializer.dumps({"uid": user_id, "role": role, "iat": int(time.time())})
+
+
+def read(cookie: str):
+    return _serializer.loads(cookie, max_age=MAX_AGE_SECONDS)

package/packs/solution-architect/skills/context-graph/evals/files/15/services/shipments/db.py

@@ -0,0 +1,30 @@
+"""Shipment persistence for services/shipments (ADR 2)."""
+import os
+
+import psycopg
+
+DSN = os.environ.get("SHIPMENTS_DSN", "postgresql://haulmark:placeholder@localhost:5432/haulmark_core")
+
+
+def connect():
+    return psycopg.connect(DSN)
+
+
+def get_shipment(conn, shipment_id: str):
+    with conn.cursor() as cur:
+        cur.execute(
+            "SELECT id, customer_id, status, custom_fields FROM shipments WHERE id = %s",
+            (shipment_id,),
+        )
+        return cur.fetchone()
+
+
+def mark_stop_delivered(conn, shipment_id: str, stop_id: str):
+    with conn.transaction():
+        with conn.cursor() as cur:
+            cur.execute("UPDATE stops SET status = 'delivered' WHERE id = %s", (stop_id,))
+            cur.execute(
+                "UPDATE shipments SET status = 'delivered' WHERE id = %s "
+                "AND NOT EXISTS (SELECT 1 FROM stops WHERE shipment_id = %s AND status <> 'delivered')",
+                (shipment_id, shipment_id),
+            )

package/packs/solution-architect/skills/context-graph/evals/files/15/services/shipments/migrations.sql

@@ -0,0 +1,3 @@
+-- 2022-09-30: per-customer custom fields as JSONB instead of new columns
+ALTER TABLE shipments ADD COLUMN custom_fields JSONB NOT NULL DEFAULT '{}'::jsonb;
+CREATE INDEX shipments_custom_fields_gin ON shipments USING GIN (custom_fields);

package/packs/solution-architect/skills/context-graph/evals/files/15/services/telemetry/store.py

@@ -0,0 +1,23 @@
+"""Telemetry writer for services/telemetry (ADR 8)."""
+import os
+
+import psycopg
+
+DSN = os.environ.get("TELEMETRY_DSN", "postgresql://haulmark:placeholder@localhost:5432/haulmark_telemetry")
+
+SCHEMA = """
+CREATE TABLE IF NOT EXISTS positions (
+    vehicle_id TEXT NOT NULL,
+    recorded_at TIMESTAMPTZ NOT NULL,
+    location GEOGRAPHY(POINT) NOT NULL
+);
+SELECT create_hypertable('positions', 'recorded_at', if_not_exists => TRUE);
+"""
+
+
+def write_position(conn, vehicle_id: str, recorded_at, lon: float, lat: float):
+    with conn.cursor() as cur:
+        cur.execute(
+            "INSERT INTO positions VALUES (%s, %s, ST_MakePoint(%s, %s)::geography)",
+            (vehicle_id, recorded_at, lon, lat),
+        )

package/packs/solution-architect/skills/context-graph/evals/files/15/web/dashboard/App.jsx

@@ -0,0 +1,3 @@
+export default function App() {
+  return <h1>Haulmark dispatch</h1>;
+}

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

@@ -0,0 +1,11 @@
+# 1. Record architecture decisions
+
+Date: 2023-04-03
+
+## Status
+
+Accepted
+
+## Decision
+
+We record architecture decisions as ADRs in `docs/adr/`, one numbered file each.

package/packs/solution-architect/skills/context-graph/evals/files/2/docs/adr/0002-rabbitmq-for-background-jobs.md

@@ -0,0 +1,15 @@
+---
+status: accepted
+date: 2023-05-22
+---
+
+# RabbitMQ for background jobs
+
+## Context and Problem Statement
+
+Checkout sends receipts and stock updates inline, which slows the request.
+
+## Decision Outcome
+
+Chosen option: "RabbitMQ", because the hosting provider offers it managed. Jobs are consumed by
+`services/worker/`, and `services/checkout/` only publishes.

package/packs/solution-architect/skills/context-graph/evals/files/2/docs/adr/0003-thumbnail-service.md

@@ -0,0 +1,20 @@
+# 3. A separate thumbnail service
+
+Date: 2023-09-11
+
+## Status
+
+Accepted
+
+## Context
+
+Resizing product images inside the API blocks request threads.
+
+## Decision
+
+Image resizing runs in its own service, `services/thumbnailer/`, which consumes `resize` jobs
+from the queue described in ADR-0002.
+
+## Consequences
+
+The API never touches image bytes after upload.