@cloudbeat/atlas-cli 0.1.0

package/README.md

@@ -0,0 +1,247 @@
+# @cloudbeat/atlas-cli
+
+Run Atlas load tests from your terminal or a CI pipeline, and record browser
+sessions into JMeter test plans.
+
+```bash
+npm install -g @cloudbeat/atlas-cli
+atlas --help
+```
+
+Requires Node.js 18 or newer.
+
+## Getting started
+
+Point the CLI at your Atlas instance and sign in.
+
+For everyday use:
+
+```bash
+atlas login --url https://atlas.cloudbeat.io -u you@company.com
+```
+
+You'll be prompted for your password. The session lasts 8 hours.
+
+For CI, create an **API token** on the Profile page of your Atlas instance and
+use that instead — it doesn't expire on its own and can be revoked at any time:
+
+```bash
+atlas login --token atlas_pat_...
+```
+
+Credentials are stored in `~/.atlas/config.json`, readable only by you.
+
+An API token acts as the person who created it and has the same permissions.
+It cannot be used to create more tokens or to change a password, so it is safe
+to hand to a build pipeline. Revoking it on the Profile page stops it working
+immediately.
+
+## Uploading files
+
+A project holds your test plan and any data files it reads. Upload them
+whenever they change — this is independent of running a test, and uploaded
+files stay in the project until you replace or delete them.
+
+```bash
+atlas files upload -p SKT ./SKT-2026.jmx ./data/mosdot.csv ./data/rashut.csv
+atlas files list -p SKT
+```
+
+Uploading a file with a name that already exists replaces it.
+
+```bash
+atlas files download -p SKT SKT-2026.jmx      # fetch a copy back
+atlas files rm -p SKT old-data.csv            # delete one
+```
+
+### How files are laid out — and how to reference them
+
+**All of a project's files live together in one flat folder.** There are no
+subdirectories: whatever you upload lands side by side, and when a test runs,
+the test plan and its data files sit in the same directory on every load
+generator.
+
+So in your test plan, reference data files by a plain relative path:
+
+```
+./mosdot.csv          ✅  recommended
+mosdot.csv            ✅  also works
+```
+
+Not by an absolute path, and not through a folder:
+
+```
+C:\Users\me\Data\mosdot.csv      ❌  a Windows path cannot be found on a Linux generator
+/home/me/data/mosdot.csv         ❌  absolute paths won't exist there either
+./data/mosdot.csv                ❌  the folder structure is not preserved
+```
+
+This catches people out most often with test plans authored in JMeter on
+Windows, where **CSV Data Set Config** entries usually hold a full `C:\…` path.
+Open each one and reduce it to `./filename`. If a path can't be resolved at run
+time, every thread in that thread group stops immediately — the test appears to
+run but that group reports no results at all.
+
+Two related things worth checking before your first run:
+
+- Every file the plan references must actually be uploaded. Upload the plan and
+  its data files together.
+- Disable GUI listeners left switched on in the plan — **View Results Tree**,
+  **Aggregate Report**, **Simple Data Writer**. They consume a lot of memory
+  during a headless run, and Atlas collects its results separately.
+
+## Running a test
+
+```bash
+atlas run -p SKT --jmx SKT-2026.jmx --servers 5 --wait
+```
+
+`--wait` follows the run to completion and prints the aggregation report.
+Without it, the command returns as soon as the test has been submitted, and you
+can check on it later:
+
+```bash
+atlas status SKT-20260818-194201
+atlas results SKT-20260818-194201
+atlas stop SKT-20260818-194201
+```
+
+`--jmx` is only needed when a project holds more than one test plan.
+
+Load generators that are switched off are started for you and shut down again
+when the test finishes.
+
+### Choosing where it runs
+
+| | |
+|---|---|
+| `--servers 5` | use any 5 available load generators |
+| `--server gen-01 --server gen-02` | pick specific ones by name |
+| `--cluster my-cluster --units 10` | run on 10 containers in an elastic cluster |
+
+### Other run options
+
+| | |
+|---|---|
+| `--jmx <filename>` | which uploaded plan to run (defaults to the project's) |
+| `--args "<jmeter args>"` | extra JMeter arguments |
+| `--no-split` | send whole data files to every generator instead of dividing them up |
+| `--timeout 30m` | how long `--wait` will wait before giving up (default `2h`) |
+| `--json` | machine-readable output |
+
+## Using it in CI
+
+Set the connection details as environment variables and let the exit code fail
+the build:
+
+```bash
+export ATLAS_URL=https://atlas.cloudbeat.io
+export ATLAS_TOKEN=atlas_pat_...
+
+# Only if the plan or its data live in this repository and may have changed.
+atlas files upload -p SKT ./SKT-2026.jmx ./data/mosdot.csv
+
+atlas run -p SKT --jmx SKT-2026.jmx --servers 5 \
+          --gate "error_rate<1,p95<2000" \
+          --junit results.xml
+```
+
+If your test plan is maintained in Atlas rather than in the repository, drop the
+upload step — the run command works on its own.
+
+### Pass/fail thresholds
+
+`--gate` fails the command when a threshold is breached. Thresholds are checked
+against the run's overall totals:
+
+| metric | meaning |
+|--------|---------|
+| `error_rate` | percentage of failed requests |
+| `avg` | average response time, ms |
+| `p90`, `p95`, `p99` | percentile response times, ms |
+| `max` | slowest response, ms |
+| `throughput` | requests per second |
+| `requests` | total requests |
+
+Use `<`, `<=`, `>` or `>=`. Separate several with commas, or repeat `--gate`.
+Setting a gate implies `--wait`, since there is nothing to check until the test
+has finished.
+
+### Exit codes
+
+| code | meaning |
+|------|---------|
+| `0` | the test ran and every threshold passed |
+| `1` | the test ran but a `--gate` threshold was breached |
+| `2` | something was wrong with the request — bad option, unknown project, not signed in |
+| `3` | the test failed or timed out, or the server could not be reached |
+
+### JUnit report
+
+`--junit results.xml` writes a standard JUnit file with one test case per
+threshold, so CI shows each one as its own pass or fail. The run's headline
+numbers are included as properties.
+
+## Recording a scenario
+
+`atlas record` opens a browser, records what you do, and writes a JMeter test
+plan:
+
+```bash
+atlas record https://example.com -o flow.jmx
+```
+
+Add `--upload -p SKT` to put the finished plan straight into a project, ready
+to run.
+
+| | |
+|---|---|
+| `-o, --out <file>` | output file (an existing plan is added to, not replaced) |
+| `-n, --name <name>` | name for the recorded scenario |
+| `--cookies <file>` | preload cookies to skip a login step |
+| `--profile <dir>` | reuse a browser profile for a persistent session |
+
+The recorder is distributed separately because it downloads its own browser,
+which most CI machines don't need. `atlas record` will tell you how to install
+it if it isn't present.
+
+## Command reference
+
+| | |
+|---|---|
+| `atlas login` | sign in with a password or an API token |
+| `atlas logout` | forget the stored credential |
+| `atlas whoami` | show who you're signed in as |
+| `atlas projects` | list the projects you can access |
+| `atlas files list` | list a project's files |
+| `atlas files upload <files...>` | upload test plans and data files |
+| `atlas files download <filename>` | download one file |
+| `atlas files rm <filename>` | delete a file (`--yes` to skip the prompt) |
+| `atlas run` | start a test |
+| `atlas status <testId>` | check whether a test is still running |
+| `atlas results <testId>` | show the aggregation report for a test |
+| `atlas stop <testId>` | stop a running test |
+| `atlas record [url]` | record a browser session |
+| `atlas config get` / `set` | default instance URL and project |
+
+Most commands take `-p, --project <name>` and `--json`. Run
+`atlas <command> --help` for the full list of options.
+
+## Settings
+
+Command-line options win over environment variables, which win over the saved
+configuration file.
+
+| variable | meaning |
+|----------|---------|
+| `ATLAS_URL` | your Atlas instance |
+| `ATLAS_TOKEN` | API token |
+| `ATLAS_PROJECT` | project to use when `--project` is omitted |
+| `ATLAS_DEBUG` | set to any value to print full error details |
+
+To avoid repeating yourself:
+
+```bash
+atlas config set project SKT
+atlas config set url https://atlas.cloudbeat.io
+```

package/dist/api.js

@@ -0,0 +1,159 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AtlasApi = void 0;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const config_1 = require("./config");
+const ui_1 = require("./ui");
+// ── Client ───────────────────────────────────────────────────────────────────
+class AtlasApi {
+    url;
+    token;
+    constructor(cfg) {
+        this.url = (cfg.url ?? '').replace(/\/+$/, '');
+        this.token = cfg.token;
+    }
+    static fromConfig(flags = {}) {
+        return new AtlasApi((0, config_1.loadConfig)(flags));
+    }
+    get baseUrl() {
+        return this.url;
+    }
+    authHeaders() {
+        if (!this.token) {
+            throw new ui_1.CliError('Not authenticated. Run `atlas login`, or set ATLAS_TOKEN to an API token.', ui_1.EXIT.USAGE);
+        }
+        return { Authorization: `Bearer ${this.token}` };
+    }
+    /** Any request against the control plane; `auth: false` for the public API. */
+    async request(method, routePath, opts = {}) {
+        const auth = opts.auth !== false;
+        const headers = auth ? this.authHeaders() : {};
+        if (opts.body !== undefined)
+            headers['Content-Type'] = 'application/json';
+        let res;
+        try {
+            res = await fetch(`${this.url}${routePath}`, {
+                method,
+                headers,
+                body: opts.body !== undefined ? JSON.stringify(opts.body) : undefined,
+            });
+        }
+        catch (err) {
+            throw new ui_1.CliError(`Cannot reach ${this.url}: ${err.message}`, ui_1.EXIT.ERROR);
+        }
+        return this.parse(method, routePath, res);
+    }
+    async parse(method, routePath, res) {
+        const text = await res.text();
+        let payload;
+        try {
+            payload = text ? JSON.parse(text) : {};
+        }
+        catch {
+            payload = { error: text.slice(0, 200) };
+        }
+        if (!res.ok) {
+            const message = payload.error ?? res.statusText;
+            // 401/403 are almost always a credential problem the user must fix, not a
+            // transient failure worth retrying — surface them as usage errors.
+            const code = res.status === 401 || res.status === 403 ? ui_1.EXIT.USAGE : ui_1.EXIT.ERROR;
+            throw new ui_1.CliError(`${method} ${routePath} → ${res.status}: ${message}`, code);
+        }
+        return payload;
+    }
+    // ── auth ──────────────────────────────────────────────────────────────────
+    async login(username, password) {
+        let res;
+        try {
+            res = await fetch(`${this.url}/admin/api/auth/login`, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({ username, password }),
+            });
+        }
+        catch (err) {
+            throw new ui_1.CliError(`Cannot reach ${this.url}: ${err.message}`, ui_1.EXIT.ERROR);
+        }
+        return this.parse('POST', '/admin/api/auth/login', res);
+    }
+    async me() {
+        return this.request('GET', '/admin/api/auth/me');
+    }
+    // ── projects & files ──────────────────────────────────────────────────────
+    async projects() {
+        return this.request('GET', '/admin/api/projects');
+    }
+    /** Projects are addressed by name on the CLI; the API wants the id. */
+    async projectByName(name) {
+        const all = await this.projects();
+        const hit = all.find(p => p.name.toLowerCase() === name.toLowerCase());
+        if (!hit) {
+            const known = all.map(p => p.name).join(', ') || '(none visible to this token)';
+            throw new ui_1.CliError(`No project named "${name}". Available: ${known}`, ui_1.EXIT.USAGE);
+        }
+        return hit;
+    }
+    async files(projectId) {
+        return this.request('GET', `/admin/api/projects/${projectId}/files`);
+    }
+    async uploadFiles(projectId, paths) {
+        const form = new FormData();
+        for (const p of paths) {
+            if (!fs_1.default.existsSync(p))
+                throw new ui_1.CliError(`File not found: ${p}`, ui_1.EXIT.USAGE);
+            const buf = fs_1.default.readFileSync(p);
+            form.append('files', new Blob([buf]), path_1.default.basename(p));
+        }
+        let res;
+        try {
+            res = await fetch(`${this.url}/admin/api/projects/${projectId}/files`, {
+                method: 'POST',
+                headers: this.authHeaders(), // no Content-Type: fetch sets the multipart boundary
+                body: form,
+            });
+        }
+        catch (err) {
+            throw new ui_1.CliError(`Upload failed: ${err.message}`, ui_1.EXIT.ERROR);
+        }
+        return this.parse('POST', `/admin/api/projects/${projectId}/files`, res);
+    }
+    async downloadFile(projectId, filename) {
+        const res = await fetch(`${this.url}/admin/api/projects/${projectId}/files/${encodeURIComponent(filename)}/download`, { headers: this.authHeaders() });
+        if (!res.ok)
+            throw new ui_1.CliError(`Download failed: ${res.status} ${res.statusText}`, ui_1.EXIT.ERROR);
+        return Buffer.from(await res.arrayBuffer());
+    }
+    async deleteFile(projectId, filename) {
+        await this.request('DELETE', `/admin/api/projects/${projectId}/files/${encodeURIComponent(filename)}`);
+    }
+    // ── fleet ─────────────────────────────────────────────────────────────────
+    async servers() {
+        return this.request('GET', '/admin/api/servers');
+    }
+    async clusters() {
+        return this.request('GET', '/admin/api/clusters');
+    }
+    // ── runs ──────────────────────────────────────────────────────────────────
+    async run(projectId, body) {
+        return this.request('POST', `/admin/api/projects/${projectId}/run`, { body });
+    }
+    async queueEntry(queueId) {
+        return this.request('GET', `/admin/api/tests/queue/${queueId}`);
+    }
+    async stop(testId) {
+        return this.request('POST', `/admin/api/tests/${encodeURIComponent(testId)}/stop`, { body: {} });
+    }
+    // ── results (public dashboard API) ─────────────────────────────────────────
+    async summary(testId) {
+        return this.request('GET', `/api/tests/${encodeURIComponent(testId)}/summary`, { auth: false });
+    }
+    async testStatus(testId) {
+        return this.request('GET', `/api/tests/${encodeURIComponent(testId)}/status`, { auth: false });
+    }
+}
+exports.AtlasApi = AtlasApi;
+//# sourceMappingURL=api.js.map

package/dist/cli.js

@@ -0,0 +1,83 @@
+#!/usr/bin/env node
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const commander_1 = require("commander");
+const chalk_1 = __importDefault(require("chalk"));
+const ui_1 = require("./ui");
+const config_1 = require("./config");
+const auth_1 = require("./commands/auth");
+const projects_1 = require("./commands/projects");
+const files_1 = require("./commands/files");
+const run_1 = require("./commands/run");
+const results_1 = require("./commands/results");
+const record_1 = require("./commands/record");
+// eslint-disable-next-line @typescript-eslint/no-var-requires
+const { version } = require('../package.json');
+const program = new commander_1.Command();
+program
+    .name('atlas')
+    .description('Atlas — run JMeter load tests from CI and record scenarios')
+    .version(version)
+    .addHelpText('after', `
+Environment:
+  ATLAS_URL      control plane URL (default https://atlas.cloudbeat.io)
+  ATLAS_TOKEN    API token — create one on the Profile page
+  ATLAS_PROJECT  default project for --project
+
+Exit codes:
+  0  success        1  a --gate threshold was breached
+  2  usage error    3  the run failed, timed out, or the API was unreachable
+
+Examples:
+  atlas login --token atlas_pat_...
+  atlas files upload -p SKT ./SKT-2026.jmx ./data/*.txt
+  atlas run -p SKT --jmx SKT-2026.jmx --servers 5 --wait \\
+            --gate "error_rate<1,p95<2000" --junit results.xml
+  atlas record https://example.com -o flow.jmx --upload -p SKT
+`);
+(0, auth_1.registerAuth)(program);
+(0, projects_1.registerProjects)(program);
+(0, files_1.registerFiles)(program);
+(0, run_1.registerRun)(program);
+(0, results_1.registerResults)(program);
+(0, record_1.registerRecord)(program);
+// Small config helper so CI/dev can pin a default project or URL without env.
+const config = program.command('config').description('Read or write CLI settings');
+config
+    .command('get')
+    .description('Show the effective settings')
+    .action(() => {
+    const cfg = (0, config_1.loadConfig)();
+    ui_1.log.info(`url     ${cfg.url}`);
+    ui_1.log.info(`project ${cfg.project ?? chalk_1.default.dim('(unset)')}`);
+    ui_1.log.info(`token   ${cfg.token ? chalk_1.default.dim(cfg.token.slice(0, 16) + '…') : chalk_1.default.dim('(unset)')}`);
+    ui_1.log.dim((0, config_1.configPath)());
+});
+config
+    .command('set <key> <value>')
+    .description('Persist a setting (url | project)')
+    .action((key, value) => {
+    if (key !== 'url' && key !== 'project') {
+        throw new ui_1.CliError('Only "url" and "project" can be set. Use `atlas login` for credentials.', ui_1.EXIT.USAGE);
+    }
+    (0, config_1.saveConfig)({ [key]: value });
+    ui_1.log.ok(`${key} = ${value}`);
+});
+async function main() {
+    await program.parseAsync(process.argv);
+}
+main().catch((err) => {
+    // Expected failures print a message; anything else is a bug and keeps its stack.
+    if (err instanceof ui_1.CliError) {
+        ui_1.log.error(err.message);
+        process.exit(err.code);
+    }
+    ui_1.log.error(err.message ?? String(err));
+    if (process.env.ATLAS_DEBUG)
+        console.error(err);
+    process.exit(ui_1.EXIT.ERROR);
+});
+//# sourceMappingURL=cli.js.map

package/dist/commands/auth.js

@@ -0,0 +1,89 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerAuth = registerAuth;
+const readline_1 = __importDefault(require("readline"));
+const chalk_1 = __importDefault(require("chalk"));
+const api_1 = require("../api");
+const config_1 = require("../config");
+const ui_1 = require("../ui");
+function ask(question, { hidden = false } = {}) {
+    const rl = readline_1.default.createInterface({ input: process.stdin, output: process.stdout });
+    return new Promise(resolve => {
+        if (!hidden) {
+            rl.question(question, answer => { rl.close(); resolve(answer.trim()); });
+            return;
+        }
+        // Suppress echo for the password: intercept the output stream while typing.
+        const rlAny = rl;
+        process.stdout.write(question);
+        rlAny._writeToOutput = () => { };
+        rl.question('', answer => {
+            rl.close();
+            process.stdout.write('\n');
+            resolve(answer.trim());
+        });
+    });
+}
+function registerAuth(program) {
+    program
+        .command('login')
+        .description('Authenticate against an Atlas control plane')
+        .option('--url <url>', `control plane URL (default: ${config_1.DEFAULT_URL})`)
+        .option('--token <token>', 'API token (atlas_pat_…) — preferred for CI')
+        .option('-u, --user <email>', 'email address, for interactive login')
+        .action(async (opts) => {
+        const cfg = (0, config_1.loadConfig)({ url: opts.url });
+        const url = cfg.url;
+        if (opts.token) {
+            // Prove the token works before writing it — a saved bad token is worse
+            // than a failed login, because every later command fails obscurely.
+            const api = new api_1.AtlasApi({ url, token: opts.token });
+            const me = await api.me();
+            (0, config_1.saveConfig)({ url, token: opts.token });
+            ui_1.log.ok(`Authenticated as ${chalk_1.default.bold(me.user.username)} (${me.user.role}) at ${url}`);
+            ui_1.log.dim(`Token saved to ${(0, config_1.configPath)()}`);
+            return;
+        }
+        const username = opts.user ?? (await ask('Email: '));
+        if (!username)
+            throw new ui_1.CliError('Email required', ui_1.EXIT.USAGE);
+        const password = await ask('Password: ', { hidden: true });
+        if (!password)
+            throw new ui_1.CliError('Password required', ui_1.EXIT.USAGE);
+        const api = new api_1.AtlasApi({ url });
+        const res = await api.login(username, password);
+        (0, config_1.saveConfig)({ url, token: res.token });
+        ui_1.log.ok(`Signed in as ${chalk_1.default.bold(res.user.username)} (${res.user.role}) at ${url}`);
+        ui_1.log.dim(`Session saved to ${(0, config_1.configPath)()}`);
+        ui_1.log.warn('This session expires in 8 hours. For CI, create an API token on the Profile page and use `atlas login --token`.');
+    });
+    program
+        .command('logout')
+        .description('Forget the stored credential')
+        .action(() => {
+        (0, config_1.clearCredentials)();
+        ui_1.log.ok('Credential removed.');
+    });
+    program
+        .command('whoami')
+        .description('Show the authenticated identity')
+        .option('--json', 'machine-readable output')
+        .action(async (opts) => {
+        const api = api_1.AtlasApi.fromConfig();
+        const me = await api.me();
+        if (opts.json) {
+            console.log(JSON.stringify(me, null, 2));
+            return;
+        }
+        const active = me.activeAccountId != null
+            ? me.accounts.find(a => a.id === me.activeAccountId)?.name ?? String(me.activeAccountId)
+            : (me.superAdmin ? 'all accounts' : '—');
+        ui_1.log.info(`${chalk_1.default.bold(me.user.username)}  ${chalk_1.default.dim(me.user.role + (me.superAdmin ? ' · super-admin' : ''))}`);
+        ui_1.log.info(`account: ${active}`);
+        ui_1.log.info(`server : ${api.baseUrl}`);
+    });
+}
+//# sourceMappingURL=auth.js.map