@lexq/cli 0.1.0

package/skills/lexq-rules/SKILL.md

@@ -0,0 +1,264 @@
+# LexQ CLI — Policy Rules
+
+> **Prerequisite:** Read `lexq-shared/SKILL.md` first.
+
+## Overview
+
+A **Policy Rule** is a condition → actions pair within a version. Rules are evaluated in priority order (0 = highest). When a rule's condition matches the input facts, its actions fire.
+
+## Rule Structure
+
+```json
+{
+  "name": "VIP 10% Discount",
+  "priority": 0,
+  "condition": { ... },
+  "actions": [ ... ],
+  "mutexGroup": null,
+  "mutexMode": "NONE",
+  "mutexStrategy": "FIRST_MATCH",
+  "mutexLimit": null,
+  "isEnabled": true
+}
+```
+
+## Condition Syntax
+
+Conditions use a tree structure with two node types: `SINGLE` and `GROUP`.
+
+### SINGLE Condition
+
+```json
+{
+  "type": "SINGLE",
+  "field": "payment_amount",
+  "operator": "GREATER_THAN_OR_EQUAL",
+  "value": 100000,
+  "valueType": "NUMBER"
+}
+```
+
+### GROUP Condition (logical combinator)
+
+```json
+{
+  "type": "GROUP",
+  "operator": "AND",
+  "children": [
+    {
+      "type": "SINGLE",
+      "field": "customer_tier",
+      "operator": "EQUALS",
+      "value": "VIP",
+      "valueType": "STRING"
+    },
+    {
+      "type": "SINGLE",
+      "field": "payment_amount",
+      "operator": "GREATER_THAN",
+      "value": 50000,
+      "valueType": "NUMBER"
+    }
+  ]
+}
+```
+
+### Operators
+
+| Operator | Types | Description |
+|---|---|---|
+| `EQUALS` | all | Exact match |
+| `NOT_EQUALS` | all | Negation |
+| `GREATER_THAN` | NUMBER | `>` |
+| `GREATER_THAN_OR_EQUAL` | NUMBER | `>=` |
+| `LESS_THAN` | NUMBER | `<` |
+| `LESS_THAN_OR_EQUAL` | NUMBER | `<=` |
+| `CONTAINS` | STRING | Substring match |
+| `IN` | STRING, NUMBER | Value is in the provided list |
+| `NOT_IN` | STRING, NUMBER | Value is not in the provided list |
+
+### Value Types
+
+| Type | JSON Value | Example |
+|---|---|---|
+| `STRING` | `"string"` | `"VIP"` |
+| `NUMBER` | `number` | `100000` |
+| `BOOLEAN` | `true/false` | `true` |
+| `LIST_STRING` | `["a","b"]` | `["KR","US"]` |
+| `LIST_NUMBER` | `[1,2]` | `[10000, 20000]` |
+
+### Nested Conditions Example
+
+`(customer_tier = "VIP" AND payment_amount >= 100000) OR region IN ["KR", "JP"]`:
+
+```json
+{
+  "type": "GROUP",
+  "operator": "OR",
+  "children": [
+    {
+      "type": "GROUP",
+      "operator": "AND",
+      "children": [
+        { "type": "SINGLE", "field": "customer_tier", "operator": "EQUALS", "value": "VIP", "valueType": "STRING" },
+        { "type": "SINGLE", "field": "payment_amount", "operator": "GREATER_THAN_OR_EQUAL", "value": 100000, "valueType": "NUMBER" }
+      ]
+    },
+    {
+      "type": "SINGLE", "field": "region", "operator": "IN", "value": ["KR", "JP"], "valueType": "LIST_STRING"
+    }
+  ]
+}
+```
+
+## Action Types
+
+Each rule can have multiple actions. Actions fire sequentially.
+
+| Type | Description | Key Parameters |
+|---|---|---|
+| `DISCOUNT` | Apply a discount | `method` (PERCENTAGE/FIXED), `rate`, `referenceFactKey` |
+| `POINT` | Award points | `amount`, `pointType` |
+| `COUPON_ISSUE` | Issue a coupon | `couponId`, `expiryDays` |
+| `BLOCK` | Block the transaction | `reason`, `code` |
+| `NOTIFICATION` | Send notification | `channel`, `template` |
+| `WEBHOOK` | Call external URL | `url`, `method`, `headers`, `body` |
+| `SET_FACT` | Set an output variable | `key`, `value` |
+| `ADD_TAG` | Add a tag to the result | `tag` |
+
+### Action Example: 10% Percentage Discount
+
+```json
+{
+  "type": "DISCOUNT",
+  "parameters": {
+    "method": "PERCENTAGE",
+    "rate": 10,
+    "referenceFactKey": "payment_amount"
+  }
+}
+```
+
+### Action Example: Block Transaction
+
+```json
+{
+  "type": "BLOCK",
+  "parameters": {
+    "reason": "Suspected fraud",
+    "code": "FRAUD_DETECTED"
+  }
+}
+```
+
+## CRUD Commands
+
+### List Rules
+
+```bash
+lexq rules list --group-id <gid> --version-id <vid> --page 0 --size 20
+```
+
+### Get Rule Detail
+
+```bash
+lexq rules get --group-id <gid> --version-id <vid> --id <ruleId>
+```
+
+### Create Rule
+
+**Important:** Always run `lexq facts list` first to confirm available fact keys and types.
+
+```bash
+lexq rules create --group-id <gid> --version-id <vid> --json '{
+  "name": "VIP 10% Discount",
+  "priority": 0,
+  "condition": {
+    "type": "GROUP",
+    "operator": "AND",
+    "children": [
+      { "type": "SINGLE", "field": "customer_tier", "operator": "EQUALS", "value": "VIP", "valueType": "STRING" },
+      { "type": "SINGLE", "field": "payment_amount", "operator": "GREATER_THAN_OR_EQUAL", "value": 100000, "valueType": "NUMBER" }
+    ]
+  },
+  "actions": [
+    {
+      "type": "DISCOUNT",
+      "parameters": { "method": "PERCENTAGE", "rate": 10, "referenceFactKey": "payment_amount" }
+    }
+  ],
+  "isEnabled": true
+}'
+```
+
+### Update Rule
+
+```bash
+lexq rules update --group-id <gid> --version-id <vid> --id <ruleId> --json '{
+  "name": "VIP 15% Discount",
+  "actions": [
+    {
+      "type": "DISCOUNT",
+      "parameters": { "method": "PERCENTAGE", "rate": 15, "referenceFactKey": "payment_amount" }
+    }
+  ]
+}'
+```
+
+### Delete Rule
+
+```bash
+lexq rules delete --group-id <gid> --version-id <vid> --id <ruleId>
+lexq rules delete --group-id <gid> --version-id <vid> --id <ruleId> --force
+```
+
+### Reorder Rules
+
+Pass rule IDs in desired priority order (index 0 = highest priority):
+
+```bash
+lexq rules reorder --group-id <gid> --version-id <vid> \
+  --rule-ids "ruleId_A,ruleId_B,ruleId_C"
+```
+
+### Toggle Rule
+
+Enable or disable a rule without deleting it:
+
+```bash
+lexq rules toggle --group-id <gid> --version-id <vid> --id <ruleId> --enabled true
+lexq rules toggle --group-id <gid> --version-id <vid> --id <ruleId> --enabled false
+```
+
+## Mutex (Rule-Level Conflict Resolution)
+
+Within a single version, rules can belong to a `mutexGroup` to limit how many fire.
+
+| mutexMode | Behavior |
+|---|---|
+| `NONE` | All matching rules fire (default) |
+| `EXCLUSIVE` | Only one rule per mutex group fires |
+| `MAX_N` | Up to `mutexLimit` rules per mutex group fire |
+
+```bash
+lexq rules create --group-id <gid> --version-id <vid> --json '{
+  "name": "Discount A",
+  "priority": 0,
+  "mutexGroup": "discounts",
+  "mutexMode": "EXCLUSIVE",
+  "mutexStrategy": "HIGHEST_PRIORITY",
+  "condition": { ... },
+  "actions": [ ... ]
+}'
+```
+
+**Constraint:** All rules in the same `mutexGroup` must use identical `mutexMode` and `mutexStrategy`.
+
+## Pre-Create Checklist
+
+Before creating rules, always:
+
+1. **Check available facts:** `lexq facts list`
+2. **Confirm the version is DRAFT:** `lexq versions get --group-id <gid> --id <vid>` → status must be `DRAFT`
+3. **Use exact fact keys** from the fact definitions (snake_case, case-sensitive)
+4. **Match value types** — a fact defined as `NUMBER` must receive numeric values, not strings

package/skills/lexq-shared/SKILL.md

@@ -0,0 +1,139 @@
+# LexQ CLI — Shared Context
+
+> **Read this skill first.** All other LexQ skills assume you have read this document.
+
+## What is LexQ?
+
+LexQ is a **policy execution engine**. Customers define business rules (conditions → actions), deploy them to production, and execute them via API — all without touching application code. Core differentiators are **pre-deploy simulation** and **A/B testing** for rule versions.
+
+## Authentication
+
+```bash
+# Store your API key (persisted at ~/.lexq/config.json)
+lexq auth login
+# Enter your API Key: lxk_xxxxxxxxxxxxx
+
+# Verify authentication
+lexq auth whoami
+```
+
+The API key is passed as `X-API-KEY` header on every request. You can also override per-command:
+
+```bash
+lexq groups list --api-key lxk_override_key
+```
+
+**Base URL:** `https://api.lexq.io/api/v1/partners` (default). Override with `--base-url`.
+
+## Core Concepts
+
+| Concept | Description | Analogy |
+|---|---|---|
+| **Policy Group** | A container for rule versions. Has a lifecycle status (ACTIVE / DISABLED / ARCHIVED). | Git repository |
+| **Policy Version** | A snapshot of rules within a group. Follows DRAFT → ACTIVE → ARCHIVED lifecycle. | Git branch / commit |
+| **Policy Rule** | A condition + actions pair within a version. Evaluated in priority order. | if-then statement |
+| **Fact Definition** | Input schema — declares available variables and their types (STRING, NUMBER, BOOLEAN, LIST_STRING, LIST_NUMBER). | Function parameter |
+| **Deployment** | Promotes a PUBLISHED version to live traffic. Supports rollback. | Production release |
+| **Dry Run** | Tests a single input against a DRAFT or ACTIVE version without side effects. | Unit test |
+| **Simulation** | Batch-tests a version against historical execution data. Compares with a baseline. | Integration test suite |
+
+## Standard Workflow
+
+This is the typical lifecycle. **Always follow this order:**
+
+```
+1. lexq groups create          → Create a policy group
+2. lexq versions create        → Create a DRAFT version inside it
+3. lexq facts create           → Register input variables (if not already defined)
+4. lexq rules create           → Add rules with conditions + actions
+5. lexq analytics dry-run      → Test with sample facts (validate before publish)
+6. lexq deploy publish         → DRAFT → ACTIVE (locks the version)
+7. lexq deploy live            → Deploy ACTIVE version to production
+8. lexq analytics simulation   → Run batch comparison against baseline (optional)
+```
+
+### Critical Ordering Constraints
+
+- **Cannot create rules without a DRAFT version.** Create the version first.
+- **Cannot publish without at least one rule.** Add rules before publishing.
+- **Cannot modify a published version.** Clone it to create a new DRAFT if changes are needed.
+- **Cannot deploy a DRAFT version.** Must publish first (DRAFT → ACTIVE).
+- **Always run `lexq analytics dry-run` before publishing.** This is your safety net.
+
+## Global Options
+
+Every command accepts these flags:
+
+| Flag | Description | Default |
+|---|---|---|
+| `--format <json\|table>` | Output format | `json` |
+| `--api-key <key>` | Override stored API key | from config |
+| `--base-url <url>` | Override API base URL | `https://api.lexq.io/api/v1/partners` |
+| `--dry-run` | Preview the HTTP request without executing | off |
+| `--verbose` | Show request/response details | off |
+| `--no-color` | Disable colored output | off |
+
+**Agent best practice:** Always use `--format json` (the default). Parse JSON output programmatically. Use `--format table` only when displaying to humans.
+
+## Command Groups
+
+| Group | Commands | Description |
+|---|---|---|
+| `auth` | `login`, `logout`, `whoami` | Authentication |
+| `status` | (root) | API health check |
+| `groups` | `list`, `get`, `create`, `update`, `delete` + `ab-test start\|stop\|adjust` | Policy group CRUD + A/B testing |
+| `versions` | `list`, `get`, `create`, `update`, `delete`, `clone` | Version CRUD |
+| `rules` | `list`, `get`, `create`, `update`, `delete`, `reorder`, `toggle` | Rule CRUD |
+| `facts` | `list`, `create`, `update`, `delete` | Fact definition CRUD |
+| `deploy` | `publish`, `live`, `rollback`, `undeploy`, `history`, `detail`, `overview` | Deployment lifecycle |
+| `analytics` | `dry-run`, `dry-run-compare`, `requirements`, `simulation start/status/list/cancel/export` | Testing & analysis |
+| `history` | `list`, `get`, `stats` | Execution history |
+| `integrations` | `list`, `get`, `save`, `delete`, `config-spec` | External integrations |
+| `logs` | `list`, `get`, `action`, `bulk-action` | Failure log management |
+
+## Pagination
+
+All list endpoints return a `PageResponse`:
+
+```json
+{
+  "content": [...],
+  "totalElements": 42,
+  "totalPages": 3,
+  "pageNo": 0,
+  "pageSize": 20
+}
+```
+
+Use `--page` and `--size` to paginate. Pages are **0-indexed**.
+
+## Error Handling
+
+API errors return:
+
+```json
+{
+  "result": "ERROR",
+  "message": "Policy version not found.",
+  "code": "ENTITY_NOT_FOUND"
+}
+```
+
+**Common error codes and what to do:**
+
+| Code | Meaning | Action |
+|---|---|---|
+| `ENTITY_NOT_FOUND` | Resource doesn't exist | Verify the ID. Run the corresponding `list` command. |
+| `INVALID_INPUT` | Validation failed | Check required fields. Run `lexq analytics requirements` for fact requirements. |
+| `CANNOT_MODIFY` | Version is not DRAFT | Clone the version to create a new DRAFT: `lexq versions clone` |
+| `EMPTY_RULES` | Publish attempted with 0 rules | Add at least one rule before publishing. |
+| `UNAUTHORIZED` | Invalid or missing API key | Run `lexq auth login` with a valid key. |
+
+## Important Conventions
+
+1. **Fact keys use `snake_case`.** Example: `payment_amount`, `customer_tier`. Always lowercase.
+2. **IDs are UUIDs.** Always copy the full ID from list/create output — do not guess.
+3. **Dates use ISO 8601.** Example: `2025-01-01T00:00:00Z`. Time zone is UTC.
+4. **JSON bodies via `--json`.** Most create/update commands accept `--json '<body>'` for the request body.
+5. **File input via `--file`.** Analytics commands accept `--file path/to/body.json` as an alternative to `--json`.
+6. **Confirmation prompts.** Destructive operations (delete, cancel, undeploy) prompt for confirmation. Use `--force` to skip in automation.

package/skills/lexq-simulation/SKILL.md

@@ -0,0 +1,279 @@
+# LexQ CLI — Simulation & Testing
+
+> **Prerequisite:** Read `lexq-shared/SKILL.md` first.
+
+## Overview
+
+LexQ provides three levels of pre-deploy validation:
+
+| Tool | Scope | When to Use |
+|---|---|---|
+| **Dry Run** | Single input | Quick validation of one scenario |
+| **Dry Run Compare** | Single input, two versions | Side-by-side version comparison |
+| **Simulation** | Batch (historical data) | Full regression test before deploy |
+
+**Golden rule:** Always dry-run before publishing, always simulate before deploying to production.
+
+## 1. Requirements Analysis
+
+Before testing, check what facts a version expects:
+
+```bash
+lexq analytics requirements --group-id <gid> --version-id <vid>
+```
+
+Response includes:
+
+```json
+{
+  "groupId": "...",
+  "versionId": "...",
+  "versionNo": 3,
+  "requiredFacts": [
+    { "key": "payment_amount", "type": "NUMBER", "required": true, "usedBy": ["VIP Discount", "Premium Block"] },
+    { "key": "customer_tier", "type": "STRING", "required": true, "usedBy": ["VIP Discount"] }
+  ],
+  "exampleRequest": {
+    "facts": { "payment_amount": 0, "customer_tier": "" },
+    "context": {}
+  }
+}
+```
+
+**Always run this before dry-run.** Copy `exampleRequest.facts` as your starting template and fill in real values.
+
+## 2. Dry Run (Single Input)
+
+Test a single set of facts against a version:
+
+```bash
+lexq analytics dry-run --version-id <vid> --json '{
+  "facts": {
+    "payment_amount": 150000,
+    "customer_tier": "VIP"
+  }
+}'
+```
+
+### Options
+
+| Flag | Description | Default |
+|---|---|---|
+| `--debug` | Include execution traces (which rules matched, why) | `false` |
+| `--mock` | Mock external calls (webhooks, integrations) | `false` |
+| `--file <path>` | Read request body from file instead of `--json` | — |
+
+### Recommended: Always Use `--debug --mock`
+
+```bash
+lexq analytics dry-run --version-id <vid> --debug --mock --json '{
+  "facts": { "payment_amount": 150000, "customer_tier": "VIP" }
+}'
+```
+
+### Response Structure
+
+```json
+{
+  "outputVariables": { "discount_amount": 15000 },
+  "executionTraces": [
+    {
+      "traceId": "...",
+      "ruleId": "...",
+      "ruleName": "VIP 10% Discount",
+      "matched": true,
+      "matchExpression": "(customer_tier == VIP AND payment_amount >= 100000)",
+      "generatedActions": [ { "type": "DISCOUNT", "parameters": { ... } } ]
+    }
+  ],
+  "decisionTraces": [
+    {
+      "ruleId": "...",
+      "ruleName": "VIP 10% Discount",
+      "status": "SELECTED",
+      "reasonCode": "FINAL_WINNER",
+      "reasonDetail": "..."
+    }
+  ],
+  "latencyMs": 12,
+  "versionNo": 3
+}
+```
+
+### Reading Decision Traces
+
+| Status | Meaning |
+|---|---|
+| `SELECTED` | Rule matched and its actions fired |
+| `NO_MATCH` | Condition did not match the input |
+| `NOT_SELECTED` | Matched but excluded by conflict resolution |
+| `BLOCKED_MUTEX` | Blocked by mutex group constraint |
+| `LOST_PRIORITY` | Lost to a higher-priority rule |
+| `DROPPED_LIMIT` | Execution limit reached |
+| `ERROR` | Rule evaluation failed |
+
+### Reading Reason Codes
+
+| Code | Meaning |
+|---|---|
+| `FINAL_WINNER` | Successfully executed |
+| `CONDITION_MISMATCH` | Input facts didn't satisfy the condition |
+| `MUTEX_PRIORITY_LOST` | Another rule in the same mutex group had higher priority |
+| `MUTEX_LIMIT_REACHED` | Mutex group's max rules already fired |
+| `GROUP_LIMIT_REACHED` | Group's `executionLimit` reached |
+| `ACTION_ERROR` | Action execution failed (e.g., webhook timeout) |
+
+## 3. Dry Run Compare
+
+Compare how two versions evaluate the same input:
+
+```bash
+lexq analytics dry-run-compare --json '{
+  "facts": { "payment_amount": 150000, "customer_tier": "VIP" },
+  "versionIdA": "<baselineVersionId>",
+  "versionIdB": "<candidateVersionId>"
+}'
+```
+
+Useful for validating that changes in a new version produce expected differences.
+
+## 4. Batch Simulation
+
+Run a full regression test against historical execution data:
+
+### Start Simulation
+
+```bash
+lexq analytics simulation start --json '{
+  "policyVersionId": "<targetVersionId>",
+  "dataset": {
+    "type": "HISTORICAL",
+    "source": "EXECUTION_LOGS",
+    "from": "2025-01-01",
+    "to": "2025-01-31"
+  },
+  "options": {
+    "includeRuleStats": true,
+    "maxRecords": 10000,
+    "baselinePolicyVersionId": "<currentLiveVersionId>",
+    "metricConfig": {
+      "targetVariable": "discount_amount",
+      "aggregationType": "SUM"
+    }
+  }
+}'
+```
+
+### Dataset Types
+
+| Type | Source | Description |
+|---|---|---|
+| `HISTORICAL` | `EXECUTION_LOGS` | Replay past executions from a date range |
+| `MANUAL` | `REQUEST_BODY` | Provide `manualData` array in the request |
+| `UPLOADED` | `S3_BUCKET` | Reference an uploaded dataset by `path` |
+
+### Check Status (Poll)
+
+```bash
+lexq analytics simulation status --id <simulationId>
+```
+
+Simulation is async. Poll until `status` is `COMPLETED` or `FAILED`.
+
+| Status | Meaning |
+|---|---|
+| `PENDING` | Queued |
+| `RUNNING` | In progress (`progress` field shows 0–100) |
+| `COMPLETED` | Done — results available |
+| `FAILED` | Error occurred |
+| `CANCELLED` | Manually cancelled |
+
+### List Simulations
+
+```bash
+lexq analytics simulation list --page 0 --size 20
+lexq analytics simulation list --status COMPLETED --from 2025-01-01 --to 2025-01-31
+```
+
+### Cancel Simulation
+
+```bash
+lexq analytics simulation cancel --id <simulationId>
+lexq analytics simulation cancel --id <simulationId> --force
+```
+
+### Export Results
+
+```bash
+lexq analytics simulation export --id <simulationId> --format json
+lexq analytics simulation export --id <simulationId> --format csv --output results.csv
+```
+
+## Simulation Response (COMPLETED)
+
+```json
+{
+  "simulationId": "...",
+  "status": "COMPLETED",
+  "summary": {
+    "totalRecords": 10000,
+    "matchedRecords": 8500,
+    "executionTimeMs": 3200,
+    "matchRate": 0.85
+  },
+  "metricSummary": {
+    "targetVariable": "discount_amount",
+    "aggregationType": "SUM",
+    "baselineValue": 5000000,
+    "simulatedValue": 4500000,
+    "delta": -500000,
+    "deltaPercentage": -10.0
+  },
+  "policyImpact": {
+    "policyVersionId": "...",
+    "comparison": {
+      "baselineVersionId": "...",
+      "difference": {
+        "matchedCountDelta": -200,
+        "matchedRateDelta": -0.02,
+        "metricValueDelta": -500000
+      }
+    }
+  },
+  "ruleStats": [
+    { "ruleId": "...", "ruleName": "VIP Discount", "matchedCount": 5000, "metricValue": 3000000 }
+  ]
+}
+```
+
+## Agent Workflow: Validate Before Deploy
+
+```bash
+# 1. Check what facts the version needs
+lexq analytics requirements --group-id <gid> --version-id <vid>
+
+# 2. Dry-run with representative inputs
+lexq analytics dry-run --version-id <vid> --debug --mock --json '{
+  "facts": { "payment_amount": 150000, "customer_tier": "VIP" }
+}'
+
+# 3. If dry-run looks good, publish
+lexq deploy publish --group-id <gid> --version-id <vid> --memo "Validated by agent"
+
+# 4. Run simulation comparing new vs. current live version
+lexq analytics simulation start --json '{
+  "policyVersionId": "<newVersionId>",
+  "dataset": { "type": "HISTORICAL", "source": "EXECUTION_LOGS", "from": "2025-01-01", "to": "2025-01-31" },
+  "options": {
+    "baselinePolicyVersionId": "<currentLiveVersionId>",
+    "includeRuleStats": true,
+    "metricConfig": { "targetVariable": "discount_amount", "aggregationType": "SUM" }
+  }
+}'
+
+# 5. Poll until complete
+lexq analytics simulation status --id <simId>
+
+# 6. If results acceptable, deploy
+lexq deploy live --group-id <gid> --version-id <newVersionId> --memo "Simulation passed"
+```