Feature/agent setup wizard

README.md

@@ -5,6 +5,51 @@
 
 ## Usage
 
+### AI assisted project setup
+The CLI ships a setup wizard for AI coding agents (currently Claude Code). Run the following in the root of your test automation project:
+```console
+npx @cloudbeat/cli init --agent claude
+```
+It installs the `/cloudbeat`, `/cloudbeat-kit` and `/cloudbeat-sync` commands and the `cloudbeat-setup` skill into `.claude/`. Open Claude Code in the same directory and run `/cloudbeat`: the wizard detects your test framework, installs and configures the matching CloudBeat Kit, creates a project in CloudBeat, and delivers your code using Git integration or file upload. Files you modified locally are not overwritten, unless `--force` is specified.
+
+### Authentication
+Instead of passing `--apiKey` and `--apiBaseUrl` to each command, the credentials can be stored once:
+```console
+cloudbeat-cli login [--apiBaseUrl <apiUrl>]
+```
+The API key is asked interactively (without being echoed) and saved to `~/.cloudbeat/config.json`. Use `login --stdin` to pipe the key in non-interactive environments.
+
+Credentials are resolved in the following order: `--apiKey`/`--apiBaseUrl` options, `CB_API_KEY`/`CB_API_URL` environment variables, stored configuration.
+
+* `cloudbeat-cli whoami` - shows and verifies the credentials in use.
+* `cloudbeat-cli logout` - removes the stored credentials.
+
+### JSON output
+`login`, `logout`, `whoami`, `git-info`, `pack` and `project` commands support the global `--json` option. A single JSON document with `"ok": true|false` is printed to stdout, which makes the commands suitable for scripts and AI agents.
+
+### Manage projects
+```console
+cloudbeat-cli project list
+cloudbeat-cli project create --name <name> --type <type> --sync <git|manual|none> [options]
+cloudbeat-cli project sync <projectNameOrId> [--dir <dir> | --file <zip>] [--wait]
+cloudbeat-cli project status <projectNameOrId>
+```
+
+**`project create` options**:
+
+* `--type <type>` - Oxygen, CucumberOxygen, CucumberJava, TestNG, JUnit, KotlinTestNG, KotlinJUnit5, MSTestBinary, NUnit3Binary, Playwright, CucumberJs, BellatrixJs, Cypress, Postman or Pytest.
+* `--sync git` - CloudBeat pulls the code from a Git repository. `--git-url` and `--git-branch` are detected from the current directory if not specified (SSH remotes are converted to HTTPS).
+* `--git-auth` - provide Git credentials now. They are asked interactively, or taken from `CB_GIT_TOKEN` (and optionally `CB_GIT_USERNAME`) environment variables. Without this option the credentials can be added later in the CloudBeat UI.
+* `--sync manual` - files are uploaded as a zip archive. Use `--dir <dir>` to pack and upload a directory, or `--file <zip>` to upload an existing archive.
+* `--exec-command`, `--exec-options`, `--assembly-names`, `--notes` - optional project settings.
+* `--wait` - wait for the initial synchronization to finish.
+
+`project sync` without `--dir`/`--file` triggers Git synchronization.
+
+### Helpers
+* `cloudbeat-cli git-info [dir]` - detects the Git repository URL, branch, and conditions which would prevent CloudBeat from seeing the latest code (unpushed commits, missing upstream, uncommitted changes).
+* `cloudbeat-cli pack [dir] [-o <zip>] [--list] [--all]` - packs a directory into a zip archive. `--all` includes git-ignored files as well (e.g. build output); it is also supported by `project create` and `project sync`. `.gitignore` is honored, additional exclusions can be listed in `.cbignore`. `node_modules`, `.git`, `.env*` and key files are never included.
+
 ### Execute a test case or suite:
 Following command will execute the specified Case or Suite, wait for the tests to finish, and will produce XML report in JUnit format: 
 ```console

agents/claude/commands/cloudbeat-kit.md

@@ -0,0 +1,18 @@
+---
+description: Install the CloudBeat Kit into this test project, or change its options (WebDriver wrapping, browser logs, network capture...). Does not touch the CloudBeat project.
+---
+
+# /cloudbeat-kit - install or reconfigure the CloudBeat Kit
+
+Runs only the kit part of the setup wizard (phases 1-4 of `.claude/skills/cloudbeat-setup/SKILL.md`). No login and no CloudBeat project are needed.
+
+1. Read `.claude/skills/cloudbeat-setup/SKILL.md` - its ground rules apply, in particular the approval gate before any file change.
+2. Read `.cloudbeat/setup.md` if it exists. Verify what it says against the code (the user may have changed things since): is the kit dependency present, which options are actually in place.
+3. Phase 1: detect and confirm the stack (`questions/02-stack.md`). Skip the confirmation if the flavor is recorded and still matches.
+4. Phase 2: go through the options of the flavor's recipe (`questions/03-kit-options.md`), using the current values as defaults. For a first installation offer "Use recommended settings".
+5. Phase 3: present the plan. For a reconfiguration it contains **only the differences** - including the removal of code that belongs to options being turned off.
+6. Phase 4: apply and verify as the recipe says.
+7. Update the "Stack" and "Kit" sections of `.cloudbeat/setup.md`.
+8. Remind the user how the change reaches CloudBeat: commit and push for Git-synchronized projects, `/cloudbeat-sync` for uploaded projects.
+
+Request: $ARGUMENTS

agents/claude/commands/cloudbeat-sync.md

@@ -0,0 +1,26 @@
+---
+description: Synchronize this test project with CloudBeat - trigger Git synchronization, or pack and upload the current code - and report the result.
+---
+
+# /cloudbeat-sync - deliver the latest code to CloudBeat
+
+Read `.claude/skills/cloudbeat-setup/reference/cli.md` for the CLI contract (`cb` below is the CLI, always with `--json`). The ground rules of `.claude/skills/cloudbeat-setup/SKILL.md` apply: no secrets in the chat.
+
+1. Read `.cloudbeat/setup.md`. No project id recorded -> tell the user to run `/cloudbeat` first (or ask for the project name/id if they created the project elsewhere, and look it up with `cb --json project list`).
+2. `cb --json whoami` - if not logged in, ask the user to run `! cloudbeat-cli login`.
+3. By delivery method:
+
+   **git**
+   - `cb --json git-info`: if there are unpushed commits or uncommitted changes, tell the user that CloudBeat will not see them, and ask whether to continue anyway. Never commit or push unless the user asks you to.
+   - `cb --json project sync <id> --wait`
+
+   **upload**
+   - .NET (binary) projects: build first, as described in the kit recipe (`dotnet build -c Release`), and upload the build output folder with `--all`.
+   - `cb --json project sync <id> --dir <dir> --wait` (preview with `cb --json pack <dir> --list` when the user asks what is being uploaded).
+
+4. Check `sync.syncStatus` in the result:
+   - `success` -> report it with the time.
+   - `failure` -> show `sync.message` and diagnose: authentication -> Git credentials are missing or expired; they are entered in the project settings in CloudBeat (never in this chat). Branch/repository not found -> compare with `git-info`. Anything else -> show the message as is.
+5. Update "last sync" in `.cloudbeat/setup.md`.
+
+Request: $ARGUMENTS

agents/claude/commands/cloudbeat.md

@@ -0,0 +1,19 @@
+---
+description: CloudBeat setup wizard - install the CloudBeat Kit for this test project, create a CloudBeat project, and deliver the code (Git integration or upload).
+argument-hint: "[restart]"
+---
+
+# /cloudbeat - CloudBeat setup wizard
+
+Run the full CloudBeat setup for the test automation project in the current directory.
+
+1. Read `.claude/skills/cloudbeat-setup/SKILL.md` and follow it exactly - its ground rules apply to everything you do here, above all: **no secrets in the chat**, **all CloudBeat operations through the CLI with `--json`**, and **no file changes before the user approves the plan**.
+2. Arguments: `restart` -> ignore any saved state and start from phase 0 (do not delete anything a previous run installed; detect it instead). Any other argument is an additional instruction from the user for this run - follow it as long as it does not conflict with the ground rules.
+3. Read `.cloudbeat/setup.md` if it exists (and `restart` was not given):
+   - all phases done, kit `installed` or `not needed`, and last sync `success` -> show the recap and offer: change kit options (`/cloudbeat-kit`), synchronize the code (`/cloudbeat-sync`), or set up again (`/cloudbeat restart`).
+   - all phases done but with open items (kit `declined` / `not available`, last sync failed, entries under "Left for the user") -> list the open items and offer to resolve them: `/cloudbeat-kit` for the kit, `/cloudbeat-sync` for the synchronization.
+   - otherwise -> tell the user where the previous run stopped and continue from the first unfinished phase.
+4. Go through the phases in order. For each one, read its question file from `.claude/skills/cloudbeat-setup/questions/` right before you start the phase, and the kit recipe from `.claude/skills/cloudbeat-setup/kits/` once the flavor is known. Do not rely on memory of these files from earlier runs.
+5. Update `.cloudbeat/setup.md` after every phase.
+
+Arguments: $ARGUMENTS

agents/claude/skills/cloudbeat-setup/SKILL.md

@@ -0,0 +1,109 @@
+---
+name: cloudbeat-setup
+description: Set up CloudBeat for the test automation project in the current directory - install and configure the right CloudBeat Kit for the project's framework, create a project in CloudBeat, and deliver the code via Git integration or file upload. Use when the user asks to set up, connect, onboard or integrate CloudBeat, add a CloudBeat Kit or reporter, create a CloudBeat project, or upload/sync tests to CloudBeat.
+---
+
+# CloudBeat setup wizard
+
+You guide the user through connecting their test automation project to CloudBeat. You act as a friendly wizard: detect first, ask only what cannot be detected, show what you are about to change, and change it only after approval.
+
+All files referenced below are relative to this skill's directory.
+
+## Ground rules
+
+1. **Secrets never go through the chat.** Never ask the user to type or paste an API key, Git token or password into the conversation, never pass one as a command line argument, and never print the content of `~/.cloudbeat/config.json`. When a secret is needed, ask the user to run the CLI command themselves by typing `! <command>` in the prompt - the CLI asks for the secret with hidden input. If the user pastes a secret anyway, tell them to revoke it and create a new one. The masked key printed by `whoami` (`abcd…wxyz`) is not a secret and may appear in output.
+2. **Every CloudBeat operation goes through the CLI** (see `reference/cli.md`). Always pass `--json` and parse the result. Never call the CloudBeat API directly with curl.
+3. **Approval gate before writing.** Before modifying any file of the user's project, show the complete list of files and the exact changes, and wait for explicit approval. No approval - no edits. The only exception is the wizard's own state file `.cloudbeat/setup.md`, which you may create and update at any time.
+4. **Confirm before creating things in CloudBeat.** Right before `project create` (or the first upload to an existing project), state in one line what will happen - "I will now create project *X* (type *Y*, Git: *url* @ *branch*) on *apiBaseUrl*", or for uploads "... (type *Y*, file upload of *dir*, *N* files) on *apiBaseUrl*" - and get a yes. This is the only gate for CloudBeat operations; read-only commands (`whoami`, `project list`, `git-info`, `pack --list`, `project status`) need no confirmation.
+5. **Stay in scope.** Touch only build files, test configuration, and the test bootstrap code named in the kit recipe. Never change test logic, application code, or CI pipelines unless asked.
+6. **Only offer what the kit supports.** Each recipe in `kits/` declares its capabilities. Do not offer an option a kit does not have, and tell the user plainly when something they expect (e.g. network capture) is not available for their framework.
+7. **Ask well.** Use the AskUserQuestion tool when it is available, otherwise ask in plain text. The tool allows at most 4 options per question (the user can always type something else): when a question file lists more, keep the most likely ones and fold the rest into the free-text answer. One step at a time, at most 4 questions per step, always with a recommended default taken from detection. Skip a question when the answer is already known.
+8. **Be resumable.** Keep the state in `.cloudbeat/setup.md` (format below; create the `.cloudbeat` folder if needed). Read it first on every run and continue from the first unfinished phase. Update it at the end of every phase.
+9. **Report honestly.** If a command fails, show the error from the JSON output and diagnose it. Never claim a step succeeded without checking its result.
+
+## Phases
+
+Run the phases in order. Each phase has a question file in `questions/` describing what to ask, the defaults, and when to skip.
+
+| # | Phase | Question file | Outcome |
+|---|-------|---------------|---------|
+| 0 | Preflight | `questions/01-connect.md` | CLI available, user logged in |
+| 1 | Detect the stack | `questions/02-stack.md` | confirmed kit flavor |
+| 2 | Kit options | `questions/03-kit-options.md` + the flavor's recipe in `kits/` | chosen options |
+| 3 | Kit plan & approval | - | approved change list |
+| 4 | Install the kit | the flavor's recipe | kit installed, project still builds |
+| 5 | CloudBeat project | `questions/04-project.md` | project id |
+| 6 | Code delivery | `questions/05-code-delivery.md` | code synchronized |
+| 7 | Wrap-up | - | summary, state saved |
+
+### Phase 0 - Preflight
+Follow `questions/01-connect.md`. Start by printing a short banner that says what the wizard will do (install the kit, create the project, deliver the code) and that nothing is changed without approval.
+
+### Phase 1 - Detect the stack
+Inspect the project without asking anything yet:
+- build files: `package.json`, `pom.xml`, `build.gradle(.kts)`, `*.csproj`/`*.sln`, `pyproject.toml`, `requirements.txt`, `pytest.ini`
+- test framework and automation library from dependencies (Playwright, Cypress, WebdriverIO, Cucumber, TestNG, JUnit 4/5, NUnit, MSTest, pytest, Selenium, Appium, RestAssured...)
+- where tests live, how they are run (scripts, surefire config, `testng.xml`), and where the WebDriver / browser / page object is created
+- whether a CloudBeat kit is already present
+
+Map the findings to a flavor using `reference/project-types.md`, then follow `questions/02-stack.md` to confirm. Some recipes build on another one ("Read `<other>.md` first") - read both. A recipe with `kitInstall: none` in its frontmatter (e.g. Cypress) means there is nothing to install: do the checks it lists, skip phases 2-4, and continue with phase 5. **Kit availability:** if the recipe has a "Check availability first" instruction (Java), do that check now, at the end of phase 1 - so that the user is not asked about options for a kit that cannot be installed. If the flavor has no recipe in `kits/`, say so, and offer to continue with phases 5-6 only (project creation and code delivery work without a kit, but reports will be less detailed).
+
+### Phase 2 - Kit options
+Read the recipe of the confirmed flavor. Its frontmatter lists `capabilities` and its "Options" section lists the questions with their conditions. Follow `questions/03-kit-options.md`.
+
+### Phase 3 - Kit plan & approval (hard gate)
+Present one consolidated plan:
+- dependencies to add (exact coordinates and versions)
+- each file to modify or create, with the diff or the new content
+- anything the user must know (overhead of an option, behavior when running outside CloudBeat)
+
+Ask: approve / modify / skip the kit. Do not write anything before approval.
+
+### Phase 4 - Install the kit
+Apply the approved plan following the recipe. Then run the recipe's verification step (compile or list tests - not the full test suite, unless the user asks). If verification fails, fix what you changed; if the failure pre-dates your change, say so and continue.
+
+### Phase 5 - CloudBeat project
+Follow `questions/04-project.md`.
+
+### Phase 6 - Code delivery
+Follow `questions/05-code-delivery.md`.
+
+### Phase 7 - Wrap-up
+Print a recap: kit and options installed, files changed, project name and id, delivery method and sync status, and what is left for the user to do (e.g. commit and push the kit changes, add Git credentials in CloudBeat). Remind the user that for Git-synchronized projects the kit changes reach CloudBeat only after they are committed and pushed. Offer `/cloudbeat-sync` for later re-synchronization and `/cloudbeat-kit` for changing kit options.
+
+## State file: `.cloudbeat/setup.md`
+
+```markdown
+# CloudBeat setup state
+<!-- Maintained by the CloudBeat setup wizard. Contains no secrets. Safe to commit. -->
+
+- updated: <ISO date>
+- phase: <last completed phase number; a skipped phase counts as completed>
+- kit: not installed yet | installed | declined | not available | not needed
+
+## Stack
+- flavor: <recipe name, e.g. java-testng-selenium>
+- language / test framework / automation library / build tool: ...
+- test command: ...
+
+## Kit
+- package(s) and version: ...
+- options: <option id>: <value>, ...
+- files changed: ...
+- verification: <command and result>
+
+## CloudBeat project
+- api url: ...
+- project id / name / type: ...
+- delivery: git | upload
+- git url / branch: ...
+- git credentials: provided | later in CloudBeat UI | not needed
+- last sync: <status> at <date>   (for uploads the CLI's `commitHash` is a generated id, not a Git hash)
+
+## Left for the user
+- ...
+```
+
+Never write an API key, token or password into this file.
+
+Both `.cloudbeat/setup.md` and the wizard files in `.claude/` are safe to commit, and committing them lets teammates re-run `/cloudbeat-sync` and `/cloudbeat-kit`; it is the user's choice - mention it once in the wrap-up. Neither folder is ever uploaded to CloudBeat, and `git-info` does not count them as uncommitted changes.