@ekzs/cli 0.2.0

package/skills/ekz-data-sqlite/SKILL.md

@@ -0,0 +1,261 @@
+---
+name: ekz-data-sqlite
+description: >-
+  SQLite STRICT tables, json1, WAL mode, and the fit-for-purpose
+  guidance for when SQLite is and isn't appropriate for payment flows
+  (tests, embedded, single-process). Includes parity DDL for the payment
+  primitives.
+---
+
+# SQLite Data Layer
+
+Use this skill when the host codebase uses SQLite (test suites, CLI
+tools, embedded apps, local-first products). SQLite is small, fast,
+and reliable when used inside its lane. Outside that lane, it bites.
+
+## When SQLite is right
+
+- **Test suites** that need a real SQL engine without a service.
+- **CLI tools and developer tooling** with per-user data.
+- **Single-process desktop/mobile apps** (Electron, mobile).
+- **Local-first / offline-first** products that sync to a server later.
+- **Edge deployments** with single-writer assumptions (Cloudflare D1,
+  Turso, LiteFS — each adds its own constraints).
+
+## When SQLite is wrong
+
+- **Multi-writer production workloads.** SQLite serialises writes
+  globally. A payments backend with concurrent webhook handlers will
+  contend on every transaction.
+- **Multi-tenant SaaS with shared data.** No RLS, no per-row auth.
+  Tenant isolation is purely the application's responsibility.
+- **Anything requiring strong durability over network.** SQLite is a
+  *library*, not a service. Distributed SQLite (LiteFS, Turso) adds back
+  durability but with replication semantics you must read carefully.
+
+If the production engine is Postgres and SQLite is only used for tests,
+keep schema and queries **portability-conservative** — avoid Postgres-only
+syntax (`RETURNING`, `JSONB`, partial indexes, RLS, generated columns
+with `STORED` semantics that differ) inside code paths the SQLite tests
+run.
+
+## What SQLite gives you
+
+- One-file durability. Easy backups (copy the file).
+- WAL mode for concurrent readers + one writer.
+- `json1` extension for structured payloads.
+- STRICT tables (3.37+) for real type enforcement.
+- `RETURNING` (3.35+) — yes, Postgres-style.
+- Full-text search (FTS5) and R-Tree spatial indexes built in.
+
+## Bootstrap configuration
+
+```sql
+-- Run once when opening the DB:
+PRAGMA journal_mode = WAL;       -- readers + one writer concurrent.
+PRAGMA synchronous = NORMAL;     -- safe with WAL; FULL is overkill.
+PRAGMA foreign_keys = ON;        -- off by default. Always turn on.
+PRAGMA busy_timeout = 5000;      -- wait 5s on SQLITE_BUSY instead of failing.
+```
+
+These settings live with the connection, not the DB file — set them on
+every open. Most drivers have a `pragmas` option for this.
+
+## DDL conventions
+
+```sql
+BEGIN;
+
+CREATE TABLE IF NOT EXISTS app_payment_requests (
+  id            TEXT PRIMARY KEY,        -- UUID v4 string.
+  tenant_id     TEXT NOT NULL,
+  kind          TEXT NOT NULL CHECK (kind IN ('order','ticket','subscription_cycle','usage_charge')),
+  amount        REAL NOT NULL CHECK (amount > 0),  -- see note below
+  currency      TEXT NOT NULL DEFAULT 'AOA',
+  status        TEXT NOT NULL DEFAULT 'pending'
+                CHECK (status IN ('pending','paid','failed','expired','canceled')),
+  business_object_kind TEXT,
+  business_object_id   TEXT,
+  metadata      TEXT NOT NULL DEFAULT '{}',         -- JSON as TEXT.
+  due_at        TEXT,                                -- ISO-8601 UTC string.
+  resolved_at   TEXT,
+  created_at    TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now')),
+  updated_at    TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now'))
+) STRICT;
+
+CREATE INDEX IF NOT EXISTS idx_app_payment_requests_due
+  ON app_payment_requests (tenant_id, status, due_at);
+
+COMMIT;
+```
+
+Rules of thumb:
+
+- **`STRICT` tables.** Without it, SQLite's type column declarations are
+  *suggestions* and a column declared `INTEGER` will happily store `"abc"`.
+  Always add `STRICT` (3.37+).
+- **Storage classes are limited.** STRICT allows: `INTEGER`, `REAL`, `TEXT`,
+  `BLOB`, `ANY`. No `BOOLEAN`, no `DECIMAL`, no `DATETIME`.
+- **Money — pick one and stay consistent.** Either:
+  - `INTEGER` minor units (cents), which is exact and recommended.
+  - `TEXT` numeric string parsed by the app, exact but slower comparisons.
+  - `REAL` (floating-point), simple but accumulates errors. Acceptable
+    only for low-stakes prototypes.
+- **Timestamps as ISO-8601 TEXT.** Always UTC, always with `Z` suffix.
+  `strftime('%Y-%m-%dT%H:%M:%fZ', 'now')` gives millisecond precision.
+- **UUIDs as TEXT** (36 chars). Or BLOB(16) if size matters and you don't
+  query them outside the app.
+- **`CHECK` constraints** are enforced. Use them for enums.
+- **No native `auto-updated` timestamp.** Use a trigger.
+
+### Updated-at trigger
+
+```sql
+CREATE TRIGGER tg_app_payment_requests_updated
+  AFTER UPDATE ON app_payment_requests
+  FOR EACH ROW BEGIN
+    UPDATE app_payment_requests
+       SET updated_at = strftime('%Y-%m-%dT%H:%M:%fZ', 'now')
+     WHERE id = OLD.id;
+  END;
+```
+
+The trigger recurses unless you also set
+`PRAGMA recursive_triggers = OFF;` (default OFF in modern SQLite). Verify.
+
+## Tenant isolation
+
+There is no Row-Level Security. Tenant isolation is **entirely** the
+application's job:
+
+- Repository layer that takes `tenantId` and injects it into every
+  `WHERE`.
+- Code review checklist item.
+- One linting rule per project: no raw SQL on tenant-scoped tables
+  outside the repository module.
+
+For local-first / single-tenant SQLite use, isolation isn't needed —
+there's one user per file.
+
+## json1 usage
+
+SQLite ships `json1` enabled by default in any modern build:
+
+```sql
+-- Read a JSON value.
+SELECT json_extract(metadata, '$.rail') AS rail
+  FROM app_payment_requests;
+
+-- Update a JSON path.
+UPDATE app_payment_requests
+   SET metadata = json_set(metadata, '$.normalized_status', 'paid')
+ WHERE id = ?;
+
+-- Query a JSON path with an index via generated column.
+ALTER TABLE app_webhook_events
+  ADD COLUMN payload_rail TEXT AS (json_extract(payload, '$.rail')) STORED;
+CREATE INDEX idx_webhook_rail ON app_webhook_events (payload_rail);
+```
+
+`json_set` / `json_insert` / `json_replace` differ:
+
+- `json_set`: write whether the path exists or not.
+- `json_insert`: write only if path doesn't exist.
+- `json_replace`: write only if path exists.
+
+## Idempotent inserts and upserts
+
+```sql
+-- Webhook dedupe.
+INSERT INTO app_webhook_events (id, provider, event_id, status, payload)
+VALUES (?, ?, ?, 'processing', ?)
+ON CONFLICT (provider, event_id) DO NOTHING
+RETURNING id;
+
+-- Upsert.
+INSERT INTO app_usage_records (id, entitlement_id, meter, quantity, idempotency_key, occurred_at)
+VALUES (?, ?, ?, ?, ?, ?)
+ON CONFLICT (entitlement_id, meter, idempotency_key)
+DO UPDATE SET quantity = excluded.quantity, occurred_at = excluded.occurred_at;
+```
+
+`excluded.col` is SQLite's name for the row that was being inserted.
+
+## Optimistic claim pattern
+
+```sql
+UPDATE app_scheduled_jobs
+   SET claimed_at = strftime('%Y-%m-%dT%H:%M:%fZ', 'now'),
+       claimed_by = ?,
+       updated_at = strftime('%Y-%m-%dT%H:%M:%fZ', 'now')
+ WHERE id = ?
+   AND (claimed_at IS NULL
+        OR claimed_at < strftime('%Y-%m-%dT%H:%M:%fZ', 'now', '-10 minutes'))
+RETURNING id, kind, payload, due_at, attempts;
+```
+
+`RETURNING` lands the claim in one round trip. Empty result = lost race.
+
+Because SQLite serialises writes globally, contention is naturally low —
+but `busy_timeout` is essential or you'll see `SQLITE_BUSY` on contention.
+
+## Append-only ledger
+
+No real GRANT/REVOKE in SQLite (it's a library, not a service). Enforce
+at the app layer + a trigger:
+
+```sql
+CREATE TRIGGER tg_app_ledger_no_update
+  BEFORE UPDATE ON app_ledger_entries
+  FOR EACH ROW BEGIN
+    SELECT RAISE(ABORT, 'ledger entries are append-only');
+  END;
+
+CREATE TRIGGER tg_app_ledger_no_delete
+  BEFORE DELETE ON app_ledger_entries
+  FOR EACH ROW BEGIN
+    SELECT RAISE(ABORT, 'ledger entries are append-only');
+  END;
+```
+
+## Migrations
+
+Without a migration tool of choice, a minimal scheme:
+
+```sql
+-- 001_init.sql
+CREATE TABLE IF NOT EXISTS _migrations (
+  id TEXT PRIMARY KEY,
+  applied_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now'))
+) STRICT;
+```
+
+App code on boot:
+
+1. Open DB, set pragmas.
+2. `BEGIN`; check `_migrations` for each file in `db/`; run each missing
+   one; insert `_migrations` row; `COMMIT`.
+3. SQLite migrations CAN be transactional — unlike MySQL most DDL is
+   inside the transaction. Use this.
+
+## Gotchas
+
+- **`DEFAULT` expressions need parentheses for non-literal values.**
+  `DEFAULT now()` won't parse; `DEFAULT (strftime(...))` will.
+- **`ALTER TABLE` is limited.** You can add columns, rename tables, rename
+  columns (3.25+). To drop/rename with constraints, copy-rebuild:
+  ```sql
+  BEGIN;
+  CREATE TABLE app_payments_new (...);
+  INSERT INTO app_payments_new SELECT ... FROM app_payments;
+  DROP TABLE app_payments;
+  ALTER TABLE app_payments_new RENAME TO app_payments;
+  -- Recreate indexes and triggers.
+  COMMIT;
+  ```
+- **Boolean returns INTEGER 0/1.** No native boolean — just be consistent.
+- **`PRAGMA` doesn't take parameters in PREPARE statements.** Set them
+  with literal values in raw SQL on connection open.
+- **WAL files (`-wal`, `-shm`) must travel with the DB.** Backups via
+  file copy must do `PRAGMA wal_checkpoint(FULL);` first or use the
+  online backup API.

package/skills/ekz-ekwanza-provider-adapter/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: ekz-ekwanza-provider-adapter
+description: >-
+  e-Kwanza provider adapter: auth, config, credentials, GPO, EMIS reference,
+  Ticket API, one-time charge creation, provider identifiers, env validation,
+  and provider-specific callback verification.
+---
+
+# e-Kwanza Provider Adapter
+
+This skill owns e-Kwanza-specific behavior only. It should not own product fulfillment, ticket inventory, subscription cycles, overage settlement, or entitlements.
+
+## API limitation
+
+e-Kwanza provides one-time payment primitives. There is no native subscription API, no native overage billing, and no app-level inventory model. Those behaviors must be implemented locally in the application.
+
+## Responsibilities
+
+- Load and validate credentials.
+- Select sandbox or production endpoints.
+- Expose rail capabilities.
+- Create one-time payment attempts.
+- Return provider identifiers and customer-facing instructions.
+- Verify provider-specific callback signatures.
+- Keep provider details behind an adapter boundary.
+
+## Rails
+
+| Rail | API | Customer UX | Required capability |
+|------|-----|-------------|---------------------|
+| `gpo` | AppyPay charges + phone | Multicaixa Express push | `GPO_*` payment method, phone |
+| `emis_ref` | AppyPay charges `REF_*` | ATM/home banking reference | `REF_*` payment method |
+| `ticket` | `POST /Ticket/{notificationToken}` | SMS/QR/code in e-Kwanza wallet | notification token, phone, HMAC config |
+
+Do not use `"reference"` as a new rail ID. If an app already stores `"reference"`, inspect whether it means `emis_ref`, `ticket`, or a UI label that can resolve to either.
+
+## Required config
+
+```text
+EKWANZA_CLIENT_ID
+EKWANZA_CLIENT_SECRET
+EKWANZA_MERCHANT_ACCOUNT
+EKWANZA_API_KEY
+EKWANZA_ENV=sandbox|production
+```
+
+Rail-specific:
+
+```text
+EKWANZA_PAYMENT_METHOD_GPO=GPO_...
+EKWANZA_PAYMENT_METHOD_GPR=REF_...   # or EKWANZA_PAYMENT_METHOD_REF
+EKWANZA_NOTIFICATION_TOKEN=...
+EKWANZA_COMPANY_REGISTRATION=...
+```
+
+## Adapter contract
+
+Create exactly one provider attempt for one local payment attempt:
+
+```typescript
+await client.createPayment("gpo", {
+  amountAoa: 15000,
+  merchantTransactionId: "REQ1234567890",
+  phoneNumber: "935095730",
+});
+```
+
+Persist `merchantTransactionId`, provider operation IDs, Ticket `operationCode`, reference/code, QR payload, expiration, and raw provider response.
+
+## Ticket HMAC
+
+Ticket-like callbacks must verify:
+
+```text
+message = code + operationCode + partnerRegistrationNumber + notificationToken
+signature = HMAC_SHA256(message, EKWANZA_API_KEY)
+```
+
+Production behavior must fail closed when the signature is missing, invalid, or required signing config is missing.
+
+## Configuration policy
+
+- Do not expose a rail in UI unless its config is complete.
+- Decide explicitly whether credentials are platform-level or merchant/account-level.
+- Never log secrets.
+- Keep sandbox/production URL selection explicit.
+- Normalize provider errors into local errors that domain code can handle.
+
+## Internal provider-config case study
+
+One internal reference combines env fallback and tenant-owned payment-method config. That is a valid implementation choice, not a rule. In a new codebase, first decide who receives the money, then place credentials at the matching owner boundary.

package/skills/ekz-integration-playbook/SKILL.md

@@ -0,0 +1,122 @@
+---
+name: ekz-integration-playbook
+description: >-
+  Integration playbook for unknown codebases: inspect existing models, map
+  payment primitives onto local routes, jobs, auth, persistence, and provider
+  interfaces without copying internal reference-app plans or tables.
+---
+
+# Integration Playbook
+
+Use this skill when adapting the payment architecture to any codebase.
+
+## First inspect
+
+Before editing, answer:
+
+- Where are users, accounts, tenants, merchants, or organizations stored?
+- Is there already an order, invoice, cart, subscription, or usage table?
+- Is there a payment/provider abstraction?
+- How are statuses represented?
+- How are webhooks authenticated, deduped, and retried?
+- Is there a job, cron, queue, scheduled function, or worker system?
+- Is there a ledger or audit table?
+- What business object needs fulfillment after payment?
+- What should happen on pending, paid, failed, expired, duplicate callback?
+- Who receives the money: platform or merchant?
+
+## Mapping rule
+
+Map concepts into the target app's existing vocabulary:
+
+```text
+PaymentRequest -> invoice/payment_intent/order_payment/billing_request
+PaymentAttempt -> payment_attempt/provider_attempt/charge_attempt
+WebhookEvent -> webhook_event/provider_event/idempotency_record
+FulfillmentAction -> fulfillment/job/outbox/domain_event
+Entitlement -> subscription_access/quota/license/membership
+UsageRecord -> usage_event/meter_event/activity_record
+```
+
+Do not force internal reference-app table names, plan names, or routes into another app.
+
+## Plain-language prompts
+
+Users do not need to know the architecture names. Translate their intent:
+
+- "payment link" -> public one-time payment checkout
+- "product in stock" -> inventory guard plus paid-only fulfillment
+- "store checkout" -> one-time product/order payment flow
+- "Multicaixa Express" -> GPO rail
+- "reference code" -> EMIS reference rail unless the existing app clearly means Ticket API
+- "ticket/invite sale" -> reservation, paid issuance, QR/code ownership
+- "subscription/monthly plan" -> local recurring one-time billing requests
+- "extra usage/overage" -> usage ledger, aggregation, charge, settlement
+
+Implement the correct architecture without requiring the user to say these internal terms.
+
+## Suggested greenfield layout
+
+```text
+src/
+  payments/
+    core/
+      types.ts
+      state-machine.ts
+      idempotency.ts
+      ledger.ts
+    providers/
+      ekwanza/
+        client.ts
+        rails.ts
+        webhooks.ts
+    webhooks/
+      payment-webhook-router.ts
+
+  billing/
+    subscriptions/
+      cycles.ts
+      payment-requests.ts
+      entitlements.ts
+      scheduler.ts
+    overage/
+      usage-ledger.ts
+      aggregation.ts
+      charges.ts
+
+  commerce/
+    orders/
+      checkout.ts
+      fulfillment.ts
+
+  tickets/
+    reservations.ts
+    issuance.ts
+    qr.ts
+```
+
+For an existing app, adapt to its structure instead of creating this exact tree.
+
+## Implementation order
+
+1. Add provider adapter and env validation.
+2. Add payment core primitives or map to existing models.
+3. Add webhook normalization and idempotency.
+4. Add one business flow at a time.
+5. Add scheduler only for recurring/overage flows.
+6. Add tests for duplicate callbacks and business side effects.
+
+## What not to do
+
+- Do not fulfill from client-side success screens.
+- Do not trust amount, plan, product, or usage from the browser.
+- Do not let raw provider status leak into domain logic.
+- Do not create duplicate local lifecycle systems for the same business object.
+- Do not expose rails with incomplete config.
+- Do not process Ticket webhooks without fail-closed signature verification in production.
+
+## Internal subscription case study
+
+The internal subscription reference teaches one way to run subscriptions over one-time e-Kwanza charges: local billing cycles, due dates, grace, reminders, webhook-driven state, and entitlement updates.
+
+Use it to learn the pattern. The target codebase remains the source of truth for naming, routes, models, policies, and entitlements.

package/skills/ekz-one-time-product-payments/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: ekz-one-time-product-payments
+description: >-
+  One-time product payment architecture: orders, products, invoices, checkout
+  links, payment requests, payment attempts, paid fulfillment, failed/expired
+  recovery, stock updates, and receipts.
+---
+
+# One-Time Product Payments
+
+Use this skill for products, orders, invoices, checkout links, donations, bookings, deposits, and payment collections.
+
+## Plain-language trigger
+
+If the user says "create a payment link", "add payment to my store", "sell this product", "25 in stock", "checkout with Multicaixa Express", or "pay with reference code", implement a one-time product/order payment flow. Do not require the user to name payment primitives.
+
+## Pattern
+
+```text
+Order/Product/Invoice -> PaymentRequest -> PaymentAttempt
+                      -> normalized paid webhook -> FulfillmentAction
+```
+
+The business object owns what is being sold. The payment layer owns collection. Fulfillment happens after a normalized paid event.
+
+## Minimal concepts
+
+- Domain object: order, invoice, cart, booking, product sale, collection.
+- Payment request: amount and reason to collect.
+- Payment attempt: one provider try using GPO, EMIS ref, or Ticket.
+- Fulfillment action: ship, mark paid, deliver access, send receipt, increment sold count.
+- Webhook event: normalized and idempotent.
+
+Use existing tables/models if present. Do not create a parallel order system unless the app has none.
+
+## Flow
+
+1. Validate the domain object and compute amount server-side.
+2. Check availability, ownership, status, and currency.
+3. Create a local `PaymentRequest`.
+4. Create a local `PaymentAttempt`.
+5. Call the provider adapter to create the one-time charge.
+6. Store provider identifiers and customer-facing instructions.
+7. Poll local status or show instructions.
+8. On normalized paid webhook, mark request paid and run fulfillment once.
+9. On failed/expired, mark recoverable state and allow retry if business policy permits.
+
+## Payment link acceptance criteria
+
+For a simple payment link request, deliver a usable vertical slice:
+
+- admin/seller can create or configure a product/payment link
+- public customer page shows product name, amount, stock/availability, and allowed rails
+- customer can start payment server-side
+- provider identifiers and instructions are persisted
+- status page or polling reflects pending/paid/failed/expired
+- webhook paid event marks the payment paid and fulfills exactly once
+- stock/capacity is decremented only after paid, or reservation is released on expiry
+- duplicate webhook is harmless
+
+## Fulfillment guard
+
+Fulfillment must be protected by a one-time guard:
+
+```text
+if payment_request.status == paid and fulfillment_action.status != completed:
+  perform domain side effect
+  mark fulfillment completed
+```
+
+This prevents duplicate webhooks from shipping, delivering, or counting the same sale twice.
+
+## Inventory
+
+For normal products:
+
+- validate stock before payment start
+- reserve if needed
+- decrement or mark sold only after paid
+- release reservation on expiration
+
+For event tickets or invite inventory, use **ekz-ticket-invite-selling**.
+
+## Tests
+
+- client cannot alter amount
+- paid event fulfills exactly once
+- duplicate paid event is ignored safely
+- failed/expired event does not fulfill
+- sold-out object cannot start a new payment
+- retry does not create a duplicate order

package/skills/ekz-overage-billing/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: ekz-overage-billing
+description: >-
+  Overage billing architecture: metered usage records, usage ledgers,
+  aggregation windows, thresholds, end-of-cycle charges, settlement, and
+  one-time payment requests for usage beyond allowance.
+---
+
+# Overage Billing
+
+Use this skill when charging for usage beyond a plan allowance, quota, prepaid balance, or threshold.
+
+## Pattern
+
+```text
+UsageRecord -> UsageLedger -> OverageCharge/Invoice
+            -> PaymentRequest -> PaymentAttempt
+            -> paid webhook -> settle usage balance
+```
+
+## Concepts
+
+- Meter: what is measured, such as seats, messages, API calls, storage, minutes, or transactions.
+- UsageRecord: idempotent raw usage event.
+- UsageLedger: append-only rollup/audit of usage and charges.
+- Allowance: included quota from plan or entitlement.
+- Aggregation window: billing period or threshold window.
+- Overage charge: amount due for usage above allowance.
+- Settlement: mark the billed usage window paid.
+
+## Charging models
+
+Choose one policy explicitly:
+
+- End-of-cycle postpaid: aggregate usage, charge at cycle close.
+- Threshold billing: charge when usage exceeds a monetary or unit threshold.
+- Prepaid drawdown: deduct from balance and request top-up when low.
+- Hybrid subscription + overage: subscription grants allowance, overage charges excess.
+
+## Flow
+
+1. Ingest usage with an idempotency key.
+2. Store usage records append-only.
+3. Aggregate by account, meter, and billing window.
+4. Subtract included allowance or credits.
+5. Create an overage invoice or charge when policy says due.
+6. Create a `PaymentRequest` for the charge.
+7. On normalized paid webhook, mark the overage window settled.
+8. On failed/expired, apply retry, grace, throttling, or suspension policy.
+
+## Invariants
+
+- Usage ingestion must be idempotent.
+- Usage records should not be mutated to hide history.
+- Amount is computed server-side from metered usage and pricing rules.
+- A settled usage window cannot be charged twice.
+- Overage payment failure should affect only the policy-defined entitlement or quota.
+- Subscription renewal and overage settlement are related but separate lifecycle events.
+
+## Tests
+
+- duplicate usage event does not double count
+- usage below allowance creates no charge
+- usage above allowance creates the expected charge
+- duplicate paid webhook does not settle twice
+- failed overage charge leaves the balance collectible
+- end-of-cycle aggregation uses the correct window boundaries
+