@atrahasis/cli 1.0.0

package/README.md

@@ -0,0 +1,389 @@
+# atra
+
+**Atrahasis CLI** - atra
+
+A fast, modern HTTP client CLI built with Rust. Supports HTTP/1.1, HTTP/2, and HTTP/3 (QUIC) with built-in load testing, flow runner, assertions, and detailed request tracing.
+
+## Installation
+
+**npm**
+
+```bash
+npm install -g @atrahasis/cli
+```
+
+**Homebrew**
+
+```bash
+brew install atrahasisdev/tap/atra
+```
+
+**curl**
+
+```bash
+curl -sSL https://cli.atrahasis.dev | sh
+```
+
+**wget**
+
+```bash
+wget -qO- https://cli.atrahasis.dev | sh
+```
+
+**PowerShell (Windows)**
+
+```powershell
+irm https://cli.atrahasis.dev | iex
+```
+
+Verify your installation:
+
+```bash
+atra --version
+```
+
+## Quick Start
+
+```bash
+# Simple GET request
+atra GET https://api.example.com/users
+
+# POST with JSON body
+atra POST https://api.example.com/users name:John age:25
+
+# POST with raw JSON
+atra POST https://api.example.com/users \
+  -H "Content-Type: application/json" \
+  -d '{"name": "John", "age": 25}'
+
+# Headers and auth
+atra GET https://api.example.com/users -H "Accept: application/json" --bearer my-token
+
+# Form data
+atra POST https://api.example.com/upload -F "file=@photo.jpg" -F "caption=Hello"
+```
+
+## Request Tracing (`--trace`)
+
+Get a full timing breakdown of every phase in the request lifecycle:
+
+```bash
+atra GET https://api.example.com --trace
+```
+
+```
+  Response Time                                          652.27 ms
+
+  Prepare             █                                       6 µs
+  DNS Lookup           █                                   3.47 ms
+  TCP Handshake         ██████                           160.91 ms
+  TLS Handshake               ██████████████             326.10 ms
+  Request Send                              █               710 µs
+  Server Response                            ███████     164.51 ms
+  Download                                                   31 µs
+  Processing                                                  1 µs
+```
+
+Use `-t` as shorthand:
+
+```bash
+atra GET https://api.example.com -t
+```
+
+Combine with verbose mode to see full request/response details alongside timing:
+
+```bash
+atra GET https://api.example.com -t -v
+```
+
+## HTTP/3 (QUIC)
+
+atra has native HTTP/3 support via QUIC - no extra configuration needed:
+
+```bash
+# Force HTTP/3
+atra GET https://api.example.com --http3
+
+# Force HTTP/2
+atra GET https://api.example.com --http2
+
+# Force HTTP/1.1
+atra GET https://api.example.com --http1.1
+```
+
+When no protocol is forced, atra automatically negotiates the best available protocol and pools connections for reuse.
+
+## Assertions
+
+Validate responses directly from the command line. Exit code 1 on failure - perfect for CI/CD:
+
+```bash
+# Status code
+atra GET https://api.example.com --assert "status equals 200"
+
+# Response time
+atra GET https://api.example.com -a "response_time less_than 500"
+
+# Body content
+atra GET https://api.example.com -a "body contains success"
+
+# JSON path
+atra GET https://api.example.com -a "$.data.id exists"
+atra GET https://api.example.com -a "$.users[0].name equals John"
+
+# Headers
+atra GET https://api.example.com -a "header Content-Type contains json"
+
+# Multiple assertions
+atra GET https://api.example.com \
+  -a "status equals 200" \
+  -a "response_time less_than 1000" \
+  -a "body contains users"
+```
+
+**Assertion Targets**
+
+| Target | Syntax | Description |
+|--------|--------|-------------|
+| `status` | `status operator value` | HTTP status code (e.g., 200, 404, 500) |
+| `response_time` | `response_time operator ms` | Response time in milliseconds |
+| `header` | `header name operator value` | Response header value (case-insensitive name) |
+| `body` | `body operator value` | Full response body as string |
+| `$.` | `$.path operator value` | JSON path - dot notation with array indexing (e.g., `$.users[0].name`) |
+
+**Operators**
+
+Each operator has short and long forms. Use whichever feels more natural.
+
+| Short | Long | Description |
+|-------|------|-------------|
+| `eq` | `equals` | Exact match |
+| `neq` | `not_equals` | Not equal |
+| `gt` | `greater_than` | Numeric greater than |
+| `lt` | `less_than` | Numeric less than |
+| | `contains` | String contains |
+| | `not_contains` | String does not contain |
+| | `exists` | Value exists (not null) |
+| | `not_exists` | Value is null or missing |
+| | `is_empty` | Empty string, array, or object |
+| | `is_not_empty` | Non-empty value |
+| | `matches_regex` | Regex pattern match |
+| | `is_type` | Check JSON type (string, number, boolean, array, object, null) |
+
+**Short form examples:**
+
+```bash
+atra GET https://api.example.com -a "status eq 200"
+atra GET https://api.example.com -a "response_time lt 500"
+atra GET https://api.example.com -a "$.data.count gt 0"
+```
+
+## Random Data Generation
+
+Generate dynamic test data with 25+ built-in generators:
+
+```bash
+# Random email and UUID
+atra POST https://api.example.com/users \
+  '{"email": "{{random.email}}", "id": "{{random.uuid}}"}'
+
+# Random string with length
+atra POST https://api.example.com/data name:"{{random.string(20)}}"
+
+# Random number in range
+atra POST https://api.example.com/data score:"{{random.number(1,100)}}"
+
+# Pick from a list
+atra POST https://api.example.com/data color:"{{random.enum(red,green,blue)}}"
+
+# Custom pattern
+atra POST https://api.example.com/data code:"{{random.custom([A-Z]{3}-\d{4})}}"
+```
+
+Available generators: `uuid`, `email`, `name`, `string`, `number`, `boolean`, `date`, `ip`, `slug`, `url`, `phone`, and more.
+
+## Flow Runner
+
+Execute sequential API call chains defined in `.flow.json` files. Supports variable extraction, pre/post scripts, assertions, and retry logic.
+
+```bash
+# Run all flows in a directory
+atra run api-tests
+
+# Run a specific flow
+atra run api-tests -f user-registration
+
+# Run with environment
+atra run api-tests -f user-registration -e dev
+
+# Sequential iterations (5 times)
+atra run api-tests -f user-registration -i 5
+
+# Parallel execution (3 workers)
+atra run api-tests -f user-registration -p 3
+
+# Stop on first failure
+atra run api-tests -f user-registration -c
+```
+
+If you are already inside the flow directory:
+
+```bash
+atra run
+atra run -f flow-name
+```
+
+**Flow Runner Flags**
+
+| Flag | Alias | Description |
+|------|-------|-------------|
+| `-f` | `--flow` | Flow names (comma-separated) |
+| `-e` | `--env` | Environment name |
+| `-i` | `--iterations` | Iteration count (default: 1) |
+| `-p` | `--parallel` | Parallel worker count (default: 1) |
+| `-c` | `--stop-on-failure` | Stop on first failure |
+
+**Variable Types**
+
+- `{{flow.varName}}` - Flow variables - carry data between steps
+- `{{varName}}` - Environment variables
+- `{{random.type}}` - Random value generated on each use
+
+**Exit Codes:** `0` = all steps and assertions passed, `1` = failure
+
+Features a live terminal dashboard with step-by-step progress, response times, assertion results, and anomaly detection.
+
+## Load Testing
+
+Run load tests from `.spec.json` files with virtual users, stages, and thresholds.
+
+```bash
+# Run all specs in a directory
+atra run spec-folder
+
+# Run specific specs
+atra run spec-folder -s user-api,auth-api
+
+# Run with environment
+atra run spec-folder -s user-api -e staging
+
+# Stress test
+atra run spec-folder -s user-api -t stress
+
+# Spike test
+atra run spec-folder -s user-api -t spike
+
+# Soak test
+atra run spec-folder -s user-api -t soak
+```
+
+**Test Types**
+
+| Type | VUs | Ramp | Duration | Purpose |
+|------|-----|------|----------|---------|
+| `load` (default) | 50 | 30s | 60s | Gradual ramp up, sustained load, gradual ramp down |
+| `stress` | 200 | 10s | 60s | Aggressive increase to find breaking points |
+| `spike` | 300 | 2s | 30s | Sudden spike to high load |
+| `soak` | 30 | 30s | 300s | Long duration with low, steady load |
+| `custom` | Custom | Custom | Custom | User-defined stages |
+
+**Load Test Flags**
+
+| Flag | Alias | Description |
+|------|-------|-------------|
+| `-s` | `--spec` | Spec names (comma-separated) |
+| `-t` | `--type` | Test type |
+| `-e` | `--env` | Environment name |
+
+Includes a real-time terminal dashboard with live charts, response time percentiles, error tracking, and threshold monitoring.
+
+**Report Formats:** HTML, PDF, OpenTelemetry JSON
+
+## CI/CD
+
+atra works in any CI/CD pipeline. Assertions return exit code 1 on failure.
+
+**GitHub Actions**
+
+```yaml
+- name: API Health Check
+  run: |
+    curl -sSL https://cli.atrahasis.dev | sh
+    atra GET https://api.example.com \
+      -a "status eq 200" \
+      -a "response_time lt 2000"
+```
+
+**With npm/npx (no install needed)**
+
+```yaml
+- name: API Health Check
+  run: npx --yes @atrahasis/cli GET https://api.example.com -a "status eq 200"
+```
+
+**GitHub Actions (Windows)**
+
+```yaml
+- name: API Health Check
+  shell: pwsh
+  run: |
+    irm https://cli.atrahasis.dev | iex
+    atra GET https://api.example.com -a "status eq 200"
+```
+
+**GitLab CI**
+
+```yaml
+api-test:
+  script:
+    - curl -sSL https://cli.atrahasis.dev | sh
+    - atra GET https://api.example.com -a "status eq 200"
+```
+
+**Run flow tests in CI**
+
+```yaml
+- name: Run API Flow Tests
+  run: |
+    curl -sSL https://cli.atrahasis.dev | sh
+    atra run ./tests -f smoke-test -e ci
+```
+
+## Additional Features
+
+| Feature | Flag |
+|---------|------|
+| Follow redirects | `-L` |
+| Timeout | `-m 30` |
+| Retry on failure | `--retry 3` |
+| Skip TLS verification | `-k` |
+| Basic auth | `-u user:pass` |
+| Bearer token | `--bearer token` |
+| OAuth 2.0 | `--oauth2 flow:url:id:secret` |
+| Download file | `-D output.zip` |
+| Cookie support | `-b "key=value"` |
+| Named sessions | `-N my-session` |
+| Verbose output | `-v` |
+| JSON output | `--json` |
+| Dry run | `-r` |
+| Certificate info | `-C` |
+| Silent mode | `-s` |
+
+## Platform Support
+
+| Platform | Architecture | Status |
+|----------|-------------|--------|
+| macOS | Apple Silicon (arm64) | Available |
+| macOS | Intel (x86_64) | Available |
+| Linux | arm64 | Available |
+| Linux | x86_64 | Available |
+| Windows | x86_64 | Available |
+
+## Links
+
+- [Atrahasis](https://atrahasis.dev)
+- [atra Documentation](https://atrahasis.dev/cli)
+
+## License
+
+Proprietary - Atrahasis

package/bin/atra.js

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+
+const { execFileSync } = require("child_process");
+const path = require("path");
+const fs = require("fs");
+
+const ext = process.platform === "win32" ? ".exe" : "";
+const binPath = path.join(__dirname, "atra-native" + ext);
+
+if (!fs.existsSync(binPath)) {
+  console.error("atra binary not found. Try reinstalling: npm install -g @atrahasis/cli");
+  process.exit(1);
+}
+
+try {
+  execFileSync(binPath, process.argv.slice(2), { stdio: "inherit" });
+} catch (err) {
+  process.exit(err.status || 1);
+}

package/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "@atrahasis/cli",
+  "version": "1.0.0",
+  "description": "A fast, modern HTTP client CLI with load testing and flow runner",
+  "bin": {
+    "atra": "bin/atra.js"
+  },
+  "scripts": {
+    "postinstall": "node scripts/install.js"
+  },
+  "os": ["darwin", "linux", "win32"],
+  "keywords": ["http", "http-client", "rest-client", "cli", "api", "api-testing", "load-testing", "stress-test", "flow-runner", "http3", "quic", "assertions", "workflow", "runner"],
+  "author": "Atrahasis",
+  "license": "Proprietary",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/atrahasisdev/cli-releases.git"
+  },
+  "homepage": "https://atrahasis.dev/cli"
+}

package/scripts/install.js

@@ -0,0 +1,99 @@
+const { execFileSync } = require("child_process");
+const os = require("os");
+const fs = require("fs");
+const path = require("path");
+const https = require("https");
+
+const REPO = "atrahasisdev/cli-releases";
+const BIN_DIR = path.join(__dirname, "..", "bin");
+const IS_WIN = os.platform() === "win32";
+const BIN_NAME = IS_WIN ? "atra-native.exe" : "atra-native";
+const BIN_PATH = path.join(BIN_DIR, BIN_NAME);
+
+function getPlatform() {
+  const platform = os.platform();
+  const arch = os.arch();
+
+  const platformMap = {
+    darwin: "apple-darwin",
+    linux: "unknown-linux-gnu",
+    win32: "pc-windows-msvc",
+  };
+
+  const archMap = {
+    x64: "x86_64",
+    arm64: "aarch64",
+  };
+
+  const osTarget = platformMap[platform];
+  const archTarget = archMap[arch];
+
+  if (!osTarget || !archTarget) {
+    console.error(`Unsupported platform: ${platform}-${arch}`);
+    process.exit(1);
+  }
+
+  return { osTarget, archTarget, isWindows: IS_WIN };
+}
+
+function httpsGet(url) {
+  return new Promise((resolve, reject) => {
+    https.get(url, { headers: { "User-Agent": "atrahasis-npm" } }, (res) => {
+      if (res.statusCode >= 300 && res.statusCode < 400 && res.headers.location) {
+        return httpsGet(res.headers.location).then(resolve).catch(reject);
+      }
+      const chunks = [];
+      res.on("data", (chunk) => chunks.push(chunk));
+      res.on("end", () => resolve({ statusCode: res.statusCode, body: Buffer.concat(chunks) }));
+      res.on("error", reject);
+    }).on("error", reject);
+  });
+}
+
+async function getLatestVersion() {
+  const res = await httpsGet(`https://api.github.com/repos/${REPO}/releases/latest`);
+  const data = JSON.parse(res.body.toString());
+  return data.tag_name;
+}
+
+async function downloadBinary(version, archTarget, osTarget, isWindows) {
+  const ext = isWindows ? "zip" : "tar.gz";
+  const filename = `atra-${archTarget}-${osTarget}.${ext}`;
+  const url = `https://github.com/${REPO}/releases/download/${version}/${filename}`;
+
+  console.log(`Downloading atra ${version} for ${archTarget}-${osTarget}...`);
+
+  const res = await httpsGet(url);
+  if (res.statusCode !== 200) {
+    console.error(`Download failed with status ${res.statusCode}`);
+    process.exit(1);
+  }
+
+  const tmpFile = path.join(os.tmpdir(), filename);
+  fs.writeFileSync(tmpFile, res.body);
+
+  fs.mkdirSync(BIN_DIR, { recursive: true });
+
+  if (isWindows) {
+    execFileSync("powershell", ["-Command", `Expand-Archive -Path '${tmpFile}' -DestinationPath '${BIN_DIR}' -Force`], { stdio: "pipe" });
+    fs.renameSync(path.join(BIN_DIR, "atra.exe"), BIN_PATH);
+  } else {
+    execFileSync("tar", ["-xzf", tmpFile, "-C", BIN_DIR], { stdio: "pipe" });
+    fs.renameSync(path.join(BIN_DIR, "atra"), BIN_PATH);
+    fs.chmodSync(BIN_PATH, 0o755);
+  }
+
+  fs.unlinkSync(tmpFile);
+  console.log(`Successfully installed atra ${version}!`);
+}
+
+async function main() {
+  const { osTarget, archTarget, isWindows } = getPlatform();
+  const version = await getLatestVersion();
+  await downloadBinary(version, archTarget, osTarget, isWindows);
+}
+
+main().catch((err) => {
+  console.error("Installation failed:", err.message);
+  process.exit(1);
+});