@lexq/cli 0.1.0

package/AGENTS.md

@@ -0,0 +1,117 @@
+# AGENTS.md — LexQ CLI Agent Guide
+
+> **For AI Agents and AI-powered IDEs** (Claude Code, Cursor, Windsurf, Cline, Gemini CLI, Copilot, and others).
+
+## What is this?
+
+LexQ CLI (`@lexq/cli`, binary: `lexq`) manages a policy execution engine. Policies are business rules (if-then) that evaluate input facts and produce actions (discounts, blocks, notifications, etc.).
+
+This file tells you how to use the CLI as an AI agent.
+
+## Quick Start
+
+```bash
+# 1. Install
+npm install -g @lexq/cli
+# or: npx @lexq/cli
+
+# 2. Authenticate
+lexq auth login
+# Enter API key when prompted
+
+# 3. Verify
+lexq auth whoami
+```
+
+## Skills
+
+Detailed documentation lives in the `skills/` directory. **Read the relevant skill before executing commands.**
+
+| Skill | File | What it covers |
+|---|---|---|
+| **Shared** | `skills/lexq-shared/SKILL.md` | Core concepts, auth, workflow, error codes. **Read first.** |
+| **Groups** | `skills/lexq-groups/SKILL.md` | Policy groups, conflict resolution, A/B testing |
+| **Rules** | `skills/lexq-rules/SKILL.md` | Condition syntax, action types, mutex, examples |
+| **Simulation** | `skills/lexq-simulation/SKILL.md` | Dry run, batch simulation, compare |
+| **Execution** | `skills/lexq-execution/SKILL.md` | History, stats, failure logs, integrations |
+| **Recipes** | `skills/lexq-recipes/SKILL.md` | 10 end-to-end workflows (copy-paste ready) |
+
+## Agent Rules
+
+1. **Always read `lexq-shared/SKILL.md` before any task.** It contains ordering constraints you must follow.
+2. **Always dry-run before publishing.** Run `lexq analytics dry-run` to validate.
+3. **Never modify a non-DRAFT version.** Check version status first. Clone if needed.
+4. **Always check facts before creating rules.** Run `lexq facts list` to know available keys and types.
+5. **Use `--format json` for parsing.** This is the default. Don't change it.
+6. **Copy full UUIDs from output.** Never guess or truncate IDs.
+7. **Handle errors gracefully.** Check the error code and follow the action table in `lexq-shared/SKILL.md`.
+
+## Complete Command Inventory (61 commands)
+
+```
+lexq auth login|logout|whoami
+lexq status
+lexq groups list|get|create|update|delete
+lexq groups ab-test start|stop|adjust
+lexq versions list|get|create|update|delete|clone
+lexq rules list|get|create|update|delete|reorder|toggle
+lexq facts list|create|update|delete
+lexq deploy publish|live|rollback|undeploy|history|detail|overview
+lexq analytics dry-run|dry-run-compare|requirements
+lexq analytics simulation start|status|list|cancel|export
+lexq history list|get|stats
+lexq integrations list|get|save|delete|config-spec
+lexq logs list|get|action|bulk-action
+```
+
+## Example: Create and Deploy a Policy (Minimal)
+
+```bash
+# 1. Create group
+GROUP=$(lexq groups create --json '{"name":"my-policy","priority":0}')
+GID=$(echo $GROUP | jq -r '.id')
+
+# 2. Create version
+VERSION=$(lexq versions create --group-id $GID --json '{"commitMessage":"v1"}')
+VID=$(echo $VERSION | jq -r '.id')
+
+# 3. Register fact
+lexq facts create --key age --name "User Age" --type NUMBER
+
+# 4. Add rule
+lexq rules create --group-id $GID --version-id $VID --json '{
+  "name": "Adult Check",
+  "priority": 0,
+  "condition": {"type":"SINGLE","field":"age","operator":"GREATER_THAN_OR_EQUAL","value":18,"valueType":"NUMBER"},
+  "actions": [{"type":"SET_FACT","parameters":{"key":"is_adult","value":"true"}}]
+}'
+
+# 5. Test
+lexq analytics dry-run --version-id $VID --debug --mock --json '{"facts":{"age":25}}'
+
+# 6. Deploy
+lexq deploy publish --group-id $GID --version-id $VID --memo "v1"
+lexq deploy live --group-id $GID --version-id $VID --memo "Initial deploy"
+```
+
+## IDE-Specific Notes
+
+### Cursor / Windsurf / Cline
+Place this file in the project root. The IDE will auto-discover it.
+
+### Claude Code
+See `.claude/CLAUDE.md` for additional project-specific context (code structure, build commands, architecture principles).
+
+### Gemini CLI
+Read this file and the skills directory. All commands are documented with full examples.
+
+## Troubleshooting
+
+| Problem | Solution |
+|---|---|
+| `Not authenticated` | Run `lexq auth login` |
+| `ENTITY_NOT_FOUND` | Verify the ID exists via the corresponding `list` command |
+| `CANNOT_MODIFY` | Version is not DRAFT. Clone it: `lexq versions clone` |
+| `EMPTY_RULES` | Add at least one rule before publishing |
+| `ACTIVATION_CONFIG_MISMATCH` | All groups in the same activationGroup must share the same mode/strategy |
+| Network error | Check `lexq status` for API health |

package/CONTEXT.md

@@ -0,0 +1,158 @@
+# CONTEXT.md — LexQ Platform Architecture
+
+## What is LexQ?
+
+LexQ is a **B2B SaaS policy execution engine**. Customers define business rules (conditions → actions), test them via simulation, deploy to production, and execute via REST API — all without modifying application code.
+
+**Core differentiators:**
+- Pre-deploy simulation against real data
+- A/B testing for rule versions
+- Git-style versioning with full audit trail
+
+## Platform Components
+
+```
+┌─────────────┐     ┌──────────────┐     ┌──────────────┐
+│  lexq-web   │     │ lexq-console │     │   lexq-cli   │
+│  (Next.js)  │     │  (React 18)  │     │ (TypeScript) │
+│  Marketing  │     │   Admin UI   │     │  Agent Tool  │
+└──────┬──────┘     └──────┬───────┘     └──────┬───────┘
+       │                   │                    │
+       │           ┌───────▼────────┐           │
+       │           │  lexq-engine   │◄──────────┘
+       │           │ (Spring Boot)  │
+       │           ├────────────────┤
+       │           │ module-admin   │ :8081 ── Console API (JWT)
+       │           │ module-partner │ :8080 ── Partner API (API Key) ◄── CLI
+       │           │ module-engine  │ :8082 ── Execution API (API Key)
+       │           │ module-batch   │ :8083 ── Background Jobs
+       │           │ module-core    │        ── Shared domain
+       │           └───────┬────────┘
+       │                   │
+       │           ┌───────▼────────┐
+       │           │   PostgreSQL   │   Aurora Serverless v2
+       │           │     Redis      │   ElastiCache Serverless
+       │           └────────────────┘
+       │
+┌──────▼──────┐
+│  lexq-docs  │
+│ (Mintlify)  │
+└─────────────┘
+```
+
+## CLI ↔ Engine Relationship
+
+The CLI exclusively calls `module-partner-api` (port 8080) via API Key authentication.
+
+**Base URL:** `https://api.lexq.io/api/v1/partners`
+
+The CLI does NOT call:
+- `module-admin-api` (JWT auth, console only)
+- `module-engine-api` (runtime execution, application code only)
+- `module-batch` (internal scheduler)
+
+## Domain Model
+
+```
+Tenant
+ └── PolicyGroup (ACTIVE | DISABLED | ARCHIVED)
+      ├── PolicyVersion (DRAFT → ACTIVE → ARCHIVED | EXPIRED)
+      │    └── PolicyRule (condition + actions, priority-ordered)
+      ├── PolicyDeployment (PUBLISH | DEPLOY | ROLLBACK | UNDEPLOY)
+      └── A/B Test (testVersionId + trafficRate)
+
+Tenant
+ └── FactDefinition (key, type, displayName — shared across all groups)
+
+Tenant
+ └── Integration (WEBHOOK | COUPON | POINT | NOTIFICATION | CRM | MESSENGER)
+```
+
+## Key Enums
+
+### Policy Group Status
+| Value | Description |
+|---|---|
+| `ACTIVE` | Normal operation |
+| `DISABLED` | Execution blocked (emergency stop) |
+| `ARCHIVED` | Permanently removed |
+
+### Policy Version Status
+| Value | Description |
+|---|---|
+| `DRAFT` | Editable. Rules can be added/modified. |
+| `ACTIVE` | Published. Locked — no modifications allowed. |
+| `ARCHIVED` | Superseded by a newer version. |
+| `EXPIRED` | Past `effectiveTo` date. Auto-transitioned by scheduler. |
+
+### Condition Operators
+`EQUALS`, `NOT_EQUALS`, `GREATER_THAN`, `GREATER_THAN_OR_EQUAL`, `LESS_THAN`, `LESS_THAN_OR_EQUAL`, `CONTAINS`, `IN`, `NOT_IN`
+
+### Value Types
+`STRING`, `NUMBER`, `BOOLEAN`, `LIST_STRING`, `LIST_NUMBER`
+
+### Action Types
+`DISCOUNT`, `POINT`, `COUPON_ISSUE`, `BLOCK`, `NOTIFICATION`, `WEBHOOK`, `SET_FACT`, `ADD_TAG`
+
+### Conflict Resolution Modes
+`NONE` (all fire), `EXCLUSIVE` (one winner), `MAX_N` (up to N winners)
+
+### Conflict Resolution Strategies
+`FIRST_MATCH`, `HIGHEST_PRIORITY`, `MAX_BENEFIT`
+
+### Deployment Types
+`PUBLISH` (DRAFT → ACTIVE), `DEPLOY` (ACTIVE → live traffic), `ROLLBACK` (revert to previous), `UNDEPLOY` (remove from live)
+
+### Execution Statuses
+`SUCCESS`, `NO_MATCH`, `ERROR`, `TIMEOUT`
+
+### Simulation Statuses
+`PENDING`, `RUNNING`, `COMPLETED`, `FAILED`, `CANCELLED`
+
+### Decision Statuses
+`SELECTED`, `NO_MATCH`, `NOT_SELECTED`, `BLOCKED_MUTEX`, `LOST_PRIORITY`, `DROPPED_LIMIT`, `ERROR`
+
+## Glossary
+
+| Term | Definition |
+|---|---|
+| **Policy Group** | Top-level container for rule versions. Controls deployment lifecycle, conflict resolution, and A/B testing. |
+| **Policy Version** | An immutable snapshot of rules. Only DRAFT versions can be modified. |
+| **Policy Rule** | A condition → actions pair. Evaluated in priority order within a version. |
+| **Fact** | An input variable passed during execution. Declared via Fact Definitions with key, type, and name. |
+| **Fact Definition** | Schema declaration for a fact — its key (snake_case), value type, display name, and description. |
+| **Dry Run** | Single-input test execution. Returns which rules matched, what actions would fire, and decision traces. |
+| **Simulation** | Batch test replaying historical executions against a version. Compares with a baseline. |
+| **Activation Group** | A logical grouping of Policy Groups for cross-group conflict resolution. |
+| **Mutex Group** | A logical grouping of Policy Rules within a version for intra-version conflict resolution. |
+| **Deployment** | The act of putting an ACTIVE version into production to receive traffic. |
+| **Rollback** | Reverting to the previously deployed version. Creates a new deployment record. |
+| **Undeploy** | Removing a group from live traffic. No version serves requests until re-deployed. |
+| **A/B Test** | Splitting traffic between the current live version and a test version by percentage. |
+| **Execution Trace** | Per-rule evaluation result showing whether the condition matched and what actions were generated. |
+| **Decision Trace** | Final disposition of a rule after conflict resolution (SELECTED, BLOCKED_MUTEX, etc.). |
+| **Snapshot Hash** | SHA-256 hash of a version's rule snapshot at deployment time. Used to verify integrity. |
+| **Traffic Rate** | Percentage (0–100) of traffic routed to the A/B test version. |
+
+## Infrastructure
+
+| Component | Service | Region |
+|---|---|---|
+| Compute | AWS ECS Fargate | us-east-1 |
+| Database | Aurora PostgreSQL Serverless v2 | us-east-1 |
+| Cache | ElastiCache Redis Serverless | us-east-1 |
+| CDN | CloudFront + S3 | Global |
+| DNS | Cloudflare | — |
+| Email | AWS SES | us-east-1 |
+| Docs | Mintlify | — |
+| IaC | Terraform | — |
+| CI/CD | GitHub Actions (OIDC) | — |
+
+## Domains
+
+| Domain | Target |
+|---|---|
+| `lexq.io` | Vercel (marketing site) |
+| `console.lexq.io` | CloudFront → S3 (React SPA) |
+| `api.lexq.io` | ALB → ECS (all backend modules) |
+| `docs.lexq.io` | Mintlify |

package/README.md

@@ -0,0 +1,153 @@
+# LexQ CLI
+
+> Manage policies, simulate rules, and deploy from the terminal. Built for humans and AI agents.
+
+[![npm](https://img.shields.io/npm/v/@lexq/cli)](https://www.npmjs.com/package/@lexq/cli)
+[![License](https://img.shields.io/github/license/lexq-io/lexq-cli)](LICENSE)
+
+## Install
+
+```bash
+npm install -g @lexq/cli
+```
+
+Or run without installing:
+
+```bash
+npx @lexq/cli
+```
+
+Requires **Node.js 18+**.
+
+## Quick Start
+
+```bash
+# 1. Authenticate
+lexq auth login
+# Enter your API key (create one at console.lexq.io → Management → API Keys)
+
+# 2. Verify
+lexq auth whoami
+
+# 3. Create a policy group
+lexq groups create --json '{"name":"my-policy","priority":0}'
+
+# 4. Create a draft version
+lexq versions create --group-id <GROUP_ID> --json '{"commitMessage":"v1"}'
+
+# 5. Add a rule
+lexq rules create --group-id <GROUP_ID> --version-id <VERSION_ID> --json '{
+  "name": "VIP Discount",
+  "priority": 0,
+  "condition": {
+    "type": "SINGLE",
+    "field": "customer_tier",
+    "operator": "EQUALS",
+    "value": "VIP",
+    "valueType": "STRING"
+  },
+  "actions": [{
+    "type": "DISCOUNT",
+    "parameters": {"method":"PERCENTAGE","rate":10,"referenceFactKey":"payment_amount"}
+  }]
+}'
+
+# 6. Test
+lexq analytics dry-run --version-id <VERSION_ID> --debug --mock \
+  --json '{"facts":{"customer_tier":"VIP","payment_amount":100000}}'
+
+# 7. Deploy
+lexq deploy publish --group-id <GROUP_ID> --version-id <VERSION_ID> --memo "v1"
+lexq deploy live --group-id <GROUP_ID> --version-id <VERSION_ID> --memo "Initial deploy"
+```
+
+## Commands
+
+```
+lexq auth            login | logout | whoami
+lexq status          API health check
+lexq groups          list | get | create | update | delete
+lexq groups ab-test  start | stop | adjust
+lexq versions        list | get | create | update | delete | clone
+lexq rules           list | get | create | update | delete | reorder | toggle
+lexq facts           list | create | update | delete
+lexq deploy          publish | live | rollback | undeploy | history | detail | overview
+lexq analytics       dry-run | dry-run-compare | requirements
+lexq analytics simulation  start | status | list | cancel | export
+lexq history         list | get | stats
+lexq integrations    list | get | save | delete | config-spec
+lexq logs            list | get | action | bulk-action
+```
+
+## Global Options
+
+| Flag | Description |
+|---|---|
+| `--format <json\|table>` | Output format (default: `json`) |
+| `--api-key <key>` | Override stored API key |
+| `--base-url <url>` | Override API base URL |
+| `--dry-run` | Preview the HTTP request without executing |
+| `--verbose` | Show request/response details |
+| `--no-color` | Disable colored output |
+
+## AI Agent Skills
+
+LexQ CLI ships with **AI Agent Skills** — structured documentation that AI coding agents can read to autonomously manage policies.
+
+```
+skills/
+├── lexq-shared/SKILL.md       Core concepts, auth, workflow
+├── lexq-groups/SKILL.md       Policy groups, conflict resolution, A/B testing
+├── lexq-rules/SKILL.md        Condition syntax, action types, mutex
+├── lexq-simulation/SKILL.md   Dry run, batch simulation, compare
+├── lexq-execution/SKILL.md    Execution history, stats, failure logs
+└── lexq-recipes/SKILL.md      10 end-to-end recipes
+
+.claude/CLAUDE.md              Claude Code project context
+AGENTS.md                      Universal agent guide (Cursor, Windsurf, Gemini CLI, Cline)
+CONTEXT.md                     Platform architecture & glossary
+```
+
+### For AI Agent Developers
+
+Skills are included in the npm package. After installing `@lexq/cli`, agents can read skills from:
+
+```
+node_modules/@lexq/cli/skills/
+node_modules/@lexq/cli/AGENTS.md
+node_modules/@lexq/cli/CONTEXT.md
+```
+
+Or reference them directly in your project by copying the `skills/` directory.
+
+## Configuration
+
+Config is stored at `~/.lexq/config.json`:
+
+```json
+{
+  "apiKey": "lxk_xxxxxxxxxxxxx",
+  "baseUrl": "https://api.lexq.io/api/v1/partners",
+  "format": "json"
+}
+```
+
+## Development
+
+```bash
+git clone https://github.com/sanghyunp-dev/lexq-cli.git
+cd lexq-cli
+pnpm install
+pnpm build
+pnpm start -- groups list
+```
+
+```bash
+pnpm typecheck     # Type check
+pnpm lint          # ESLint
+bash tests/e2e.sh  # E2E tests (requires API key)
+```
+
+## License
+
+[Apache-2.0](LICENSE)