@cloudbeat/atlas-cli 0.3.0 → 0.4.1

package/dist/commands/plan.js

@@ -0,0 +1,100 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerPlan = registerPlan;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const chalk_1 = __importDefault(require("chalk"));
+const api_1 = require("../api");
+const config_1 = require("../config");
+const ui_1 = require("../ui");
+const plan_1 = require("../plan");
+/** Project comes from --project, ATLAS_PROJECT, or the saved default. */
+function projectName(flag) {
+    return (0, config_1.loadConfig)({ project: flag }).project;
+}
+function printReport(name, report) {
+    ui_1.log.info(chalk_1.default.bold(name));
+    for (const g of report.threadGroups) {
+        const state = g.enabled ? '' : chalk_1.default.dim(' (disabled)');
+        const size = [g.threads && `${g.threads} users`, g.loops && `${g.loops} loops`]
+            .filter(Boolean)
+            .join(', ');
+        console.log(`  ${chalk_1.default.cyan('group')}  ${g.name}${state}${size ? chalk_1.default.dim(`  ${size}`) : ''}`);
+    }
+    for (const f of report.dataFiles) {
+        const mark = f.uploaded === false ? chalk_1.default.red('missing') : f.uploaded ? chalk_1.default.green('uploaded') : chalk_1.default.dim('?');
+        console.log(`  ${chalk_1.default.cyan('data ')}  ${f.filename}  ${mark}`);
+    }
+    if (report.issues.length)
+        console.log();
+    for (const issue of report.issues) {
+        const line = `${issue.message}${issue.fix ? chalk_1.default.dim(`  → ${issue.fix}`) : ''}`;
+        if (issue.severity === 'error')
+            ui_1.log.error(line);
+        else if (issue.severity === 'warning')
+            ui_1.log.warn(line);
+        else
+            ui_1.log.dim(`  ${issue.message}`);
+    }
+    console.log();
+    if (report.ok)
+        ui_1.log.ok('This plan can run.');
+    else
+        ui_1.log.error('This plan would not produce results as it stands.');
+}
+function registerPlan(program) {
+    const plan = program.command('plan').description('Work with a test plan file');
+    plan
+        .command('check [file]')
+        .description('Check a plan will actually run and report — locally, or one in a project')
+        .option('-p, --project <name>', 'project to check the plan against (and to fetch it from)')
+        .option('--jmx <filename>', 'which plan in the project (default: the project\'s)')
+        .option('--json', 'machine-readable output')
+        .action(async (file, opts) => {
+        const name = projectName(opts.project);
+        let content;
+        let label;
+        let uploaded;
+        if (file) {
+            if (!fs_1.default.existsSync(file))
+                throw new ui_1.CliError(`No such file: ${file}`, ui_1.EXIT.USAGE);
+            content = fs_1.default.readFileSync(file, 'utf8');
+            label = path_1.default.basename(file);
+            // A local file can still be checked against a project's uploads — that
+            // is the interesting question before uploading it.
+            if (name) {
+                const api = api_1.AtlasApi.fromConfig();
+                const project = await api.projectByName(name);
+                uploaded = (await api.files(project.id)).map(f => f.filename);
+            }
+        }
+        else {
+            if (!name) {
+                throw new ui_1.CliError('Pass a file to check, or -p <project> to check the project\'s plan.', ui_1.EXIT.USAGE);
+            }
+            const api = api_1.AtlasApi.fromConfig();
+            const project = await api.projectByName(name);
+            const files = await api.files(project.id);
+            uploaded = files.map(f => f.filename);
+            const jmx = opts.jmx ?? project.jmx_filename ?? undefined;
+            if (!jmx) {
+                throw new ui_1.CliError(`Project "${project.name}" has no test plan. Upload one first.`, ui_1.EXIT.USAGE);
+            }
+            content = (await api.downloadFile(project.id, jmx)).toString('utf8');
+            label = jmx;
+        }
+        const report = (0, plan_1.checkPlan)(content, uploaded);
+        if (opts.json)
+            (0, ui_1.json)({ plan: label, project: name ?? null, ...report });
+        else
+            printReport(label, report);
+        // An unrunnable plan is a usage problem the caller must fix, and CI should
+        // stop on it rather than proceed to a run that reports nothing.
+        if (!report.ok)
+            throw new ui_1.CliError(`${label} would not produce results.`, ui_1.EXIT.USAGE);
+    });
+}
+//# sourceMappingURL=plan.js.map

package/dist/commands/record.js

@@ -58,6 +58,7 @@ function registerRecord(program) {
         .option('--profile <dir>', 'browser profile directory for a persistent session')
         .option('--upload', 'upload the recorded .jmx into the project when done')
         .option('-p, --project <name>', 'project to upload into (with --upload)')
+        .option('--json', 'machine-readable output')
         .action(async (url, opts) => {
         // Fail on an unusable --upload before spending a recording session on it.
         let project = null;
@@ -94,9 +95,18 @@ function registerRecord(program) {
         if (!fs_1.default.existsSync(opts.out)) {
             throw new ui_1.CliError(`Recorder finished but ${opts.out} was not written.`, ui_1.EXIT.ERROR);
         }
+        if (project)
+            await api_1.AtlasApi.fromConfig().uploadFiles(project.id, [opts.out]);
+        if (opts.json) {
+            (0, ui_1.json)({
+                out: path_1.default.resolve(opts.out),
+                filename: path_1.default.basename(opts.out),
+                uploaded: project ? project.name : null,
+            });
+            return;
+        }
         ui_1.log.ok(`Recorded ${chalk_1.default.bold(opts.out)}`);
         if (project) {
-            await api_1.AtlasApi.fromConfig().uploadFiles(project.id, [opts.out]);
             ui_1.log.ok(`Uploaded ${path_1.default.basename(opts.out)} → ${project.name}`);
             ui_1.log.dim(`run it with: atlas run --project ${project.name} --jmx ${path_1.default.basename(opts.out)}`);
         }

package/dist/commands/results.js

@@ -108,20 +108,26 @@ function registerResults(program) {
     program
         .command('stop <testId>')
         .description('Stop a running test')
-        .action(async (testId) => {
+        .option('--json', 'machine-readable output')
+        .action(async (testId, opts) => {
         const api = api_1.AtlasApi.fromConfig();
         const res = await api.stop(testId);
+        if (opts.json)
+            (0, ui_1.json)({ testId, ...res });
         if (res.unreachable?.length || res.stillRunning?.length) {
             // The API only marks a server stopped once it confirms the process is
             // gone; anything else must be surfaced, not rounded up to success.
-            ui_1.log.warn(`Stopped on ${res.ok} server(s), but could not confirm all of them.`);
-            if (res.unreachable?.length)
-                ui_1.log.warn(`unreachable: ${res.unreachable.join(', ')}`);
-            if (res.stillRunning?.length)
-                ui_1.log.warn(`still running: ${res.stillRunning.join(', ')}`);
+            if (!opts.json) {
+                ui_1.log.warn(`Stopped on ${res.ok} server(s), but could not confirm all of them.`);
+                if (res.unreachable?.length)
+                    ui_1.log.warn(`unreachable: ${res.unreachable.join(', ')}`);
+                if (res.stillRunning?.length)
+                    ui_1.log.warn(`still running: ${res.stillRunning.join(', ')}`);
+            }
             throw new ui_1.CliError('Run not fully stopped — retry when those servers are reachable.', ui_1.EXIT.ERROR);
         }
-        ui_1.log.ok(`Stopped ${testId} on ${res.ok} server(s).`);
+        if (!opts.json)
+            ui_1.log.ok(`Stopped ${testId} on ${res.ok} server(s).`);
     });
 }
 //# sourceMappingURL=results.js.map

package/dist/commands/schema.js

@@ -0,0 +1,86 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerSchema = registerSchema;
+const chalk_1 = __importDefault(require("chalk"));
+const ui_1 = require("../ui");
+function optionSchema(o) {
+    // Commander's `required`/`optional` describe the option's VALUE, not whether
+    // the option itself must be passed — name them so an agent can't read them
+    // as "this flag is mandatory" and start passing --json <something>.
+    return {
+        flags: o.flags,
+        description: o.description,
+        takesValue: !!o.required || !!o.optional,
+        valueOptional: !!o.optional,
+        variadic: !!o.variadic,
+        ...(o.defaultValue !== undefined ? { default: o.defaultValue } : {}),
+    };
+}
+function argumentSchema(a) {
+    return {
+        name: typeof a.name === 'function' ? a.name() : String(a.name ?? ''),
+        description: a.description ?? '',
+        required: !!a.required,
+        variadic: !!a.variadic,
+    };
+}
+function commandSchema(cmd) {
+    // registeredArguments is Commander 11+; keep the older private field as a
+    // fallback so a dependency bump can't silently empty the argument list.
+    const args = cmd.registeredArguments ?? cmd._args ?? [];
+    return {
+        name: cmd.name(),
+        description: cmd.description(),
+        aliases: cmd.aliases(),
+        arguments: args.map(argumentSchema),
+        options: cmd.options.map(optionSchema),
+        commands: cmd.commands.map(c => commandSchema(c)),
+    };
+}
+function printTree(cmds, prefix) {
+    for (const c of cmds) {
+        const args = c.arguments.map(a => (a.required ? `<${a.name}>` : `[${a.name}]`)).join(' ');
+        console.log(`${prefix}${chalk_1.default.bold(c.name)}${args ? ' ' + args : ''}  ${chalk_1.default.dim(c.description)}`);
+        for (const o of c.options)
+            console.log(`${prefix}  ${o.flags}  ${chalk_1.default.dim(o.description)}`);
+        printTree(c.commands, prefix + '  ');
+    }
+}
+function registerSchema(program) {
+    program
+        .command('schema')
+        .description('Describe every command, argument and option — for scripts and AI agents')
+        .option('--json', 'machine-readable output')
+        .action((opts) => {
+        const { version } = require('../../package.json');
+        const schema = {
+            name: program.name(),
+            version,
+            description: program.description(),
+            exitCodes: {
+                [ui_1.EXIT.OK]: 'success',
+                [ui_1.EXIT.GATE_FAILED]: 'a --gate threshold was breached',
+                [ui_1.EXIT.USAGE]: 'usage error: bad flags, unknown project, not authenticated',
+                [ui_1.EXIT.ERROR]: 'the run failed, timed out, or the API was unreachable',
+            },
+            env: {
+                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',
+                ATLAS_DEBUG: 'print stack traces for unexpected failures',
+            },
+            commands: program.commands.map(c => commandSchema(c)),
+        };
+        if (opts.json) {
+            (0, ui_1.json)(schema);
+            return;
+        }
+        ui_1.log.info(`${chalk_1.default.bold(schema.name)} ${schema.version}`);
+        printTree(schema.commands, '');
+        ui_1.log.dim('Use --json for the machine-readable form.');
+    });
+}
+//# sourceMappingURL=schema.js.map

package/dist/commands/skills.js

@@ -0,0 +1,111 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerSkills = registerSkills;
+const fs_1 = __importDefault(require("fs"));
+const os_1 = __importDefault(require("os"));
+const path_1 = __importDefault(require("path"));
+const chalk_1 = __importDefault(require("chalk"));
+const ui_1 = require("../ui");
+/**
+ * Installing the guidance an AI assistant needs to drive Atlas properly.
+ *
+ * The content is written once, vendor-neutral, and shipped in the package. This
+ * copies it where a given assistant looks: skills under .claude/skills for
+ * Claude Code, AGENTS.md for everything that reads that convention.
+ */
+/** Bundled by scripts/bundle-skills.js at build time. */
+const SKILLS_DIR = path_1.default.join(__dirname, '..', 'skills');
+function bundledSkills() {
+    if (!fs_1.default.existsSync(SKILLS_DIR))
+        return [];
+    return fs_1.default
+        .readdirSync(SKILLS_DIR, { withFileTypes: true })
+        .filter(e => e.isDirectory() && fs_1.default.existsSync(path_1.default.join(SKILLS_DIR, e.name, 'SKILL.md')))
+        .map(e => e.name)
+        .sort();
+}
+/** Copy one file. An existing file is left alone unless --force: it may have
+ *  been edited for the project, and silently replacing that is worse than
+ *  leaving it slightly out of date. */
+function place(from, to, force) {
+    if (fs_1.default.existsSync(to) && !force)
+        return 'skipped';
+    fs_1.default.mkdirSync(path_1.default.dirname(to), { recursive: true });
+    fs_1.default.copyFileSync(from, to);
+    return 'written';
+}
+function registerSkills(program) {
+    const skills = program
+        .command('skills')
+        .description('Install the Atlas guidance for AI coding assistants');
+    skills
+        .command('list')
+        .description('Show the skills bundled with this CLI')
+        .option('--json', 'machine-readable output')
+        .action((opts) => {
+        const names = bundledSkills();
+        if (opts.json) {
+            (0, ui_1.json)({ skills: names.map(name => ({ name, source: path_1.default.join(SKILLS_DIR, name, 'SKILL.md') })) });
+            return;
+        }
+        if (names.length === 0) {
+            ui_1.log.warn('No skills are bundled with this build.');
+            return;
+        }
+        for (const name of names)
+            console.log(`  ${chalk_1.default.cyan(name)}`);
+    });
+    skills
+        .command('install')
+        .description('Copy the skills into this project (or your home directory)')
+        .option('--user', 'install for every project, under your home directory')
+        .option('--project', 'install into the current project (default)')
+        .option('--dir <path>', 'install somewhere else entirely')
+        .option('--force', 'overwrite files that are already there')
+        .option('--json', 'machine-readable output')
+        .action((opts) => {
+        const names = bundledSkills();
+        if (names.length === 0) {
+            throw new ui_1.CliError('No skills are bundled with this build.', ui_1.EXIT.ERROR);
+        }
+        const base = opts.dir
+            ? path_1.default.resolve(opts.dir)
+            : opts.user
+                ? path_1.default.join(os_1.default.homedir(), '.claude')
+                : path_1.default.join(process.cwd(), '.claude');
+        const installed = [];
+        for (const name of names) {
+            const to = path_1.default.join(base, 'skills', name, 'SKILL.md');
+            installed.push({
+                name,
+                path: to,
+                status: place(path_1.default.join(SKILLS_DIR, name, 'SKILL.md'), to, !!opts.force),
+            });
+        }
+        // AGENTS.md is the vendor-neutral half: Copilot, Cursor and others read it
+        // even though they know nothing about skills. Project scope only — a home
+        // directory is not a project root.
+        let agents;
+        const agentsSource = path_1.default.join(SKILLS_DIR, 'AGENTS.md');
+        if (!opts.user && fs_1.default.existsSync(agentsSource)) {
+            const to = path_1.default.join(opts.dir ? base : process.cwd(), 'AGENTS.md');
+            agents = { name: 'AGENTS.md', path: to, status: place(agentsSource, to, !!opts.force) };
+            installed.push(agents);
+        }
+        if (opts.json) {
+            (0, ui_1.json)({ base, installed });
+            return;
+        }
+        for (const item of installed) {
+            if (item.status === 'written')
+                ui_1.log.ok(`${item.name} → ${item.path}`);
+            else
+                ui_1.log.dim(`${item.name} already present — left alone (use --force to replace)`);
+        }
+        ui_1.log.dim('Start a new assistant session to pick them up.');
+    });
+}
+//# sourceMappingURL=skills.js.map

package/dist/commands/tests.js

@@ -0,0 +1,73 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerTests = registerTests;
+const cli_table3_1 = __importDefault(require("cli-table3"));
+const chalk_1 = __importDefault(require("chalk"));
+const api_1 = require("../api");
+const config_1 = require("../config");
+const ui_1 = require("../ui");
+/** Project comes from --project, ATLAS_PROJECT, or the saved default. */
+function projectName(flag) {
+    const name = (0, config_1.loadConfig)({ project: flag }).project;
+    if (!name) {
+        throw new ui_1.CliError('No project. Pass --project <name>, set ATLAS_PROJECT, or run `atlas config set project <name>`.', ui_1.EXIT.USAGE);
+    }
+    return name;
+}
+/** "Jun 7, 08:19 PM" — the same stamp the dashboard's test list shows. */
+function started(iso) {
+    return new Date(iso).toLocaleString(undefined, {
+        month: 'short', day: 'numeric', hour: '2-digit', minute: '2-digit',
+    });
+}
+function printTests(tests) {
+    const table = new cli_table3_1.default({
+        head: ['TEST ID', 'STATUS', 'STARTED', 'USERS', 'REQUESTS', 'ERR%'].map(h => chalk_1.default.dim(h)),
+        colAligns: ['left', 'left', 'left', 'right', 'right', 'right'],
+        style: { head: [], border: [] },
+    });
+    for (const t of tests) {
+        table.push([
+            t.testId,
+            t.status === 'running' ? chalk_1.default.green('● running') : chalk_1.default.dim('completed'),
+            started(t.startedAt),
+            String(t.maxUsers),
+            String(t.totalRequests),
+            t.errorPct === 0 ? chalk_1.default.green('0%') : chalk_1.default.yellow(`${t.errorPct}%`),
+        ]);
+    }
+    console.log(table.toString());
+}
+function registerTests(program) {
+    program
+        .command('tests')
+        .description('List a project\'s recent runs, most recent first')
+        .option('-p, --project <name>', 'project name')
+        .option('--limit <n>', 'show at most this many runs')
+        .option('--json', 'machine-readable output')
+        .action(async (opts) => {
+        const api = api_1.AtlasApi.fromConfig();
+        const project = projectName(opts.project);
+        const { tests } = await api.tests(project);
+        const limit = opts.limit ? parseInt(opts.limit, 10) : undefined;
+        if (opts.limit && (!Number.isFinite(limit) || limit < 1)) {
+            throw new ui_1.CliError('--limit must be a positive integer', ui_1.EXIT.USAGE);
+        }
+        const shown = limit ? tests.slice(0, limit) : tests;
+        if (opts.json) {
+            (0, ui_1.json)({ project, tests: shown });
+            return;
+        }
+        if (shown.length === 0) {
+            // The dashboard's list only reaches back a week, so an empty result is
+            // "nothing recent", not "this project has never run".
+            ui_1.log.warn(`No runs reported for "${project}" in the last 7 days.`);
+            return;
+        }
+        printTests(shown);
+    });
+}
+//# sourceMappingURL=tests.js.map

package/dist/docs/agent-setup.md

@@ -0,0 +1,109 @@
+# Setting It Up
+
+Two commands to install, one to sign in. The guidance is bundled with the CLI,
+so there is nothing to download separately and nothing to keep in sync by hand.
+
+## Install
+
+```sh
+npm install -g @cloudbeat/atlas-cli @cloudbeat/atlas-recorder
+atlas login --token <your API token>
+atlas skills install
+```
+
+Create the token on your **Profile** page in Atlas. A token acts as you, in one
+account, so the agent can never reach further than you can.
+
+`atlas skills install` arrived in 0.4.0. Check with `atlas --version`, and
+upgrade with `npm install -g @cloudbeat/atlas-cli@latest`.
+
+The recorder is a separate package because it downloads its own browser. Install
+it when you want an agent to record scenarios; skip it in CI, where nothing
+opens a browser.
+
+## What gets installed
+
+`atlas skills install` writes into the current project:
+
+```
+.claude/skills/
+  atlas-load-test/SKILL.md     the end-to-end flow
+  atlas-record/SKILL.md        recording a scenario from a browser
+  atlas-test-plan/SKILL.md     plans, data files, local debugging
+  atlas-correlate/SKILL.md     per-session values: tokens, session ids
+  atlas-run/SKILL.md           sizing, thresholds, CI
+  atlas-analyze/SKILL.md       reading results, and spotting a broken test
+AGENTS.md                      the same guidance, vendor-neutral
+```
+
+See [The Skills](/agents/skills) for what each one covers and when it loads.
+
+**Start a new assistant session afterwards.** Skills and `AGENTS.md` are read
+when a session starts, so an open session will not see them.
+
+## Where to install it
+
+| Command | Installs into | Use when |
+|---|---|---|
+| `atlas skills install` | the current project | The repository whose performance you are testing — the usual choice, and it can be committed so your team shares it |
+| `atlas skills install --user` | your home directory | You want every project on your machine to have it |
+| `atlas skills install --dir <path>` | anywhere | Unusual layouts, or a shared checkout |
+
+Existing files are **left alone**, because you may have edited them for your
+project. Pass `--force` to replace them:
+
+```sh
+atlas skills install --force
+```
+
+To see what a build carries before installing anything:
+
+```sh
+atlas skills list
+```
+
+## Claude Code
+
+Nothing else to do. Open Claude Code in the project and ask for a load test —
+the relevant skill loads by itself when the request calls for it. You can
+confirm they are there with `/skills`.
+
+Committing `.claude/skills/` to your repository means everyone on the team gets
+the same behaviour, and reviews changes to it like any other file.
+
+## Copilot, Cursor, Codex and friends
+
+These read `AGENTS.md` from the project root, which `atlas skills install` writes
+for you. No configuration, no extension. Commit it alongside your code.
+
+If your assistant reads a differently named file, copy it:
+
+```sh
+cp AGENTS.md CLAUDE.md          # or .cursorrules, .github/copilot-instructions.md
+```
+
+## Keeping it current
+
+The guidance ships inside the CLI, so upgrading the CLI brings new guidance with
+it:
+
+```sh
+npm install -g @cloudbeat/atlas-cli@latest
+atlas skills install --force
+```
+
+Worth doing when you upgrade, because the guidance tracks the commands. If you
+have edited a skill for your own project, diff before overwriting.
+
+## Check it works
+
+Ask your assistant something that needs Atlas but changes nothing:
+
+> What can I load test here, and how much capacity do I have?
+
+You should see it run `atlas projects` and `atlas capacity`, then answer with
+your real projects and machine count. If it improvises shell commands or asks
+you for infrastructure credentials, the guidance has not loaded — start a new
+session and check `.claude/skills/` or `AGENTS.md` is present.
+
+[What it can do →](/agents/capabilities)