@isummation/kasauti-cli 0.2.0 → 0.3.0

package/README.md

@@ -1,12 +1,15 @@
 # @isummation/kasauti-cli
 
-Command line for [Kasauti](https://gitlab.isummation.com/isummation-product/kasauti) test management: explore, author, run, and report and fix defects. Used by people, CI and AI agents. Output is Markdown; add `--json` for scripts. Node 20+, no dependencies.
+Command line for Kasauti test management: explore, author, run, and report and fix defects. Used by people, CI and AI agents. Output is Markdown; add `--json` for scripts. Node 20+, no dependencies. Also carries the Kasauti plugin for Claude Code.
 
 ```bash
-npm install -g @isummation/kasauti-cli      # needs access to the @isummation npm org
+npm install -g @isummation/kasauti-cli
 kasauti login https://<kasauti-api> --token <token>
 kasauti map SHOP
+kasauti plugin install      # Claude Code plugin: Kasauti MCP tools + explore / run / fix playbooks
 kasauti --help
 ```
 
+After `npm update -g @isummation/kasauti-cli`, run `kasauti plugin update`.
+
 `KASAUTI_URL` and `KASAUTI_TOKEN` override the saved login (that is how CI uses it). Full guide: `docs/using-kasauti-in-your-project.md` in the Kasauti repository.

package/kasauti.mjs

@@ -5,6 +5,8 @@ import { parseArgs } from 'node:util';
 import { readFileSync, writeFileSync, existsSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { basename, join, extname } from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
 
 const CONFIG = process.env.KASAUTI_CONFIG ?? join(homedir(), '.kasauti.json');
 const HELP = `kasauti <command> [args] [--json]
@@ -13,6 +15,8 @@ Setup
   login <url> --token T                  save URL + a personal token (Settings → API tokens) to ~/.kasauti.json
   token <name> [--agent NAME]            create a personal (or agent) API token
   whoami | projects | mcp-config
+  plugin install|update [--scope user|local]   add the bundled Claude Code plugin (skills + MCP) to Claude Code
+  plugin path                            where the bundled plugin is, for manual setup
 
 Explore
   map <PROJECT>                          area tree with coverage and open defects
@@ -58,6 +62,7 @@ const { values: o, positionals: args } = parseArgs({
     env: { type: 'string' }, message: { type: 'string', short: 'm' }, attach: { type: 'string', multiple: true }, duration: { type: 'string' },
     case: { type: 'string' }, run: { type: 'string' }, url: { type: 'string' }, actual: { type: 'string' }, expected: { type: 'string' },
     steps: { type: 'string' }, severity: { type: 'string' }, commit: { type: 'string' }, pr: { type: 'string' }, mine: { type: 'boolean' }, force: { type: 'boolean' },
+    scope: { type: 'string' },
   },
 });
 
@@ -133,6 +138,36 @@ switch (cmd) {
     print(`claude mcp add --transport http kasauti ${url}/mcp --header "Authorization: Bearer <agent token>"\n\nCreate an agent token with: kasauti token claude-code --agent claude-code`);
     break;
   }
+  case 'plugin': {
+    // The npm package ships the plugin as a one-plugin marketplace (see bundle-plugin.mjs), so installing it
+    // needs no access to the Kasauti git repository.
+    const dir = fileURLToPath(new URL('./plugin', import.meta.url));
+    if (!existsSync(join(dir, '.claude-plugin', 'marketplace.json'))) die('No bundled plugin here (running from a git checkout?). Install the CLI from npm: npm install -g @isummation/kasauti-cli');
+    if (sub === 'path') { print(dir); break; }
+    if (sub !== 'install' && sub !== 'update') die('Usage: kasauti plugin install|update|path [--scope user|local]');
+    // Not 'project': that would commit this machine's npm path into the repo's .claude/settings.json.
+    const scope = o.scope ?? 'user';
+    if (!['user', 'local'].includes(scope)) die('--scope must be user (all your projects) or local (this project, not committed)');
+    const steps = sub === 'install'
+      ? [['plugin', 'marketplace', 'add', dir, '--scope', scope], ['plugin', 'install', 'kasauti@kasauti', '--scope', scope]]
+      : [['plugin', 'marketplace', 'update', 'kasauti'], ['plugin', 'update', 'kasauti@kasauti']];
+    const quote = (x) => (/\s/.test(x) ? `"${x}"` : x);
+    const show = (a) => `claude ${a.map(quote).join(' ')}`;
+    // claude is a .cmd shim on Windows, which only runs through a shell (so paths with spaces get quoted)
+    const win = process.platform === 'win32';
+    const claude = (a) => spawnSync('claude', win ? a.map(quote) : a, { stdio: 'inherit', shell: win });
+    const probe = spawnSync('claude', ['--version'], { stdio: 'ignore', shell: win });
+    if (probe.error || probe.status) die(`Claude Code isn't on the PATH. Install it, or run these yourself:\n${steps.map(show).join('\n')}`);
+    for (const [i, a] of steps.entries()) {
+      console.log(`$ ${show(a)}`);
+      let r = claude(a);
+      // already added (e.g. a reinstall): refresh it from the folder instead
+      if (r.status && i === 0 && sub === 'install') r = claude(['plugin', 'marketplace', 'update', 'kasauti']);
+      if (r.status) die(`Failed: ${show(a)}`);
+    }
+    print(`\nDone. Restart Claude Code, then check /mcp lists kasauti. It reads KASAUTI_URL and KASAUTI_TOKEN (an agent token) from your environment.\nAfter upgrading the CLI (npm update -g @isummation/kasauti-cli), run: kasauti plugin update`);
+    break;
+  }
   case 'map': print(await api('GET', `/projects/${need(sub, '<PROJECT>')}/map`)); break;
   case 'get': print(await api('GET', `/k/${need(sub, '<KEY>')}`)); break;
   case 'activity': print(await api('GET', `/projects/${need(sub, '<PROJECT>')}/activity`)); break;

package/package.json

@@ -1,15 +1,19 @@
 {
   "name": "@isummation/kasauti-cli",
-  "version": "0.2.0",
-  "description": "Kasauti test management CLI for humans, CI and AI agents",
+  "version": "0.3.0",
+  "description": "Kasauti test management CLI for humans, CI and AI agents, with the Claude Code plugin",
   "type": "module",
   "bin": {
     "kasauti": "./kasauti.mjs"
   },
   "files": [
     "kasauti.mjs",
+    "plugin",
     "README.md"
   ],
+  "scripts": {
+    "prepack": "node bundle-plugin.mjs"
+  },
   "engines": {
     "node": ">=20"
   },
@@ -19,7 +23,7 @@
     "directory": "packages/cli"
   },
   "publishConfig": {
-    "access": "restricted",
+    "access": "public",
     "registry": "https://registry.npmjs.org/"
   }
 }

package/plugin/.claude-plugin/marketplace.json

@@ -0,0 +1,15 @@
+{
+  "name": "kasauti",
+  "owner": {
+    "name": "iSummation"
+  },
+  "plugins": [
+    {
+      "name": "kasauti",
+      "source": "./kasauti",
+      "description": "Kasauti test management for AI agents",
+      "version": "0.3.0"
+    }
+  ],
+  "description": "Kasauti test management plugin for Claude Code"
+}

package/plugin/kasauti/.claude-plugin/plugin.json

@@ -0,0 +1,8 @@
+{
+  "name": "kasauti",
+  "version": "0.3.0",
+  "description": "Kasauti test management: explore screens into test cases, run them, file defects with evidence, and fix defects for tester verification.",
+  "author": {
+    "name": "iSummation"
+  }
+}

package/plugin/kasauti/.mcp.json

@@ -0,0 +1,9 @@
+{
+  "mcpServers": {
+    "kasauti": {
+      "type": "http",
+      "url": "${KASAUTI_URL:-http://localhost:3001}/mcp",
+      "headers": { "Authorization": "Bearer ${KASAUTI_TOKEN}" }
+    }
+  }
+}

package/plugin/kasauti/AGENTS.md

@@ -0,0 +1,19 @@
+# Kasauti (test management) — instructions for AI agents
+
+Copy this section into a product repo's `AGENTS.md` / `CLAUDE.md` / Cursor rules so any agent harness can use Kasauti.
+
+Kasauti tracks this project's test cases, runs and defects. Use the `kasauti` MCP server (`$KASAUTI_URL/mcp`, bearer `$KASAUTI_TOKEN`)
+or the `kasauti` CLI (`npm install -g @isummation/kasauti-cli`, then `kasauti --help`; output is Markdown, add `--json` for JSON). The project code is **DEMO** <!-- change me -->.
+
+Keys: `DEMO-12` case · `DEMO-A3` area (screen/endpoint) · `DEMO-SC4` scenario · `DEMO-R5` run · `DEMO-D7` defect.
+
+- **Start** with `kasauti map DEMO` (MCP `project_map`), then `kasauti get <KEY>`.
+- **Fixing bugs:** `kasauti defects DEMO` → `kasauti defect claim DEMO-D7` → `kasauti get DEMO-D7` (repro steps, evidence, linked case)
+  → reproduce → fix + test → commit mentioning the key → `kasauti defect resolve DEMO-D7 -m "<root cause and change>" --commit <sha>`.
+  Reopened defects first; read their comments. Can't reproduce? Comment and `kasauti defect release DEMO-D7`.
+- **Testing a screen:** create or update the area (`kasauti area DEMO --title … --route /path`), scenarios and cases (use stable `ref`s),
+  `kasauti run start DEMO --title … --area DEMO-A3`, then `kasauti run next DEMO-R5` / `kasauti result DEMO-R5 DEMO-12 failed -m "…" --attach shot.png`,
+  and `kasauti defect report DEMO --title … --case DEMO-12 --run DEMO-R5` for failures.
+- Long text fields are **Markdown**: numbered repro steps, `code` for values, fenced blocks for logs and stack traces. Raw HTML is not rendered. Screenshots testers paste appear as `![name](<KASAUTI_URL>/attachments/<id>)`: download them with your token to see what they saw.
+- **Never** mark results you didn't observe. You can't verify fixes or approve draft cases; humans do that.
+- Your token carries its owner's role. A developer's token can claim, resolve and comment on defects; exploring and running tests needs a tester's token.

package/plugin/kasauti/skills/explore-screen/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: explore-screen
+description: Explore a web app screen in a browser, record its scenarios and test cases in Kasauti, execute them, and report results and defects with evidence. Use when asked to "explore", "test", "find scenarios for" or "write test cases for" a page/screen/URL, or to run exploratory testing on a frontend project.
+---
+
+# Explore a screen into Kasauti
+
+You need two tools: a **browser** (Claude in Chrome, Playwright MCP, or `playwright-cli`) and **Kasauti** (the `kasauti` MCP tools, or the `kasauti` CLI with the same verbs). Keys look like `DEMO-A3` (area), `DEMO-SC4` (scenario), `DEMO-12` (case), `DEMO-R5` (run), `DEMO-D7` (defect).
+
+## 1. Orient
+1. `project_map` for the project. It returns the base URL and the areas that already exist, with their coverage. Don't re-create what's there.
+2. If the target screen is already an area, `get` it. Read the **Agent notes** (login, test data, selectors) and the existing scenarios and cases.
+
+## 2. Map the screen
+3. Open the screen in the browser. If you're redirected to login, follow the area notes or ask the user.
+4. `upsert_area` with:
+   - `title`: a human name.
+   - `route`: the URL pattern with params generalized, e.g. `/orders/:id`.
+   - `kind: screen`.
+   - `parent`: set it for nested screens.
+   - `notes`: anything the next agent needs (how to get there, required data, flaky bits).
+5. Identify the **user goals** the screen supports, not individual widgets. Typical set: the happy path, validation and errors, empty and loading states, permissions, and navigation out. `upsert_scenario` once per goal, with a short Given/When/Then `narrative`.
+
+## 3. Write concrete cases
+6. `upsert_cases` in one batch per scenario. Each case should have:
+   - a `ref` that's stable across sessions, e.g. `orders-detail/cancel-confirm`;
+   - a specific `title` that states the expected behaviour;
+   - `steps` with `action`, optional `data`, and an `expected` on every step that checks something;
+   - `behavior` (positive/negative), `severity` and `layer: e2e`.
+
+   Keep cases independent and repeatable. Put setup in `preconditions`.
+7. Your cases land as **drafts**. That's expected: a human approves them. Don't try to set `status: actual`.
+
+## 4. Execute
+8. `start_run` with `area` set to this screen (or `scenario`) and a descriptive title, e.g. "Exploratory: Orders detail (Chrome)".
+9. Loop: `next_case` → do the steps in the browser → `report_result` with:
+   - `status`: passed / failed / blocked (blocked when you can't reach the precondition);
+   - `steps`: the 1-based step results, at least for the failing step;
+   - `comment`: actual vs expected, the exact error text, the URL;
+   - `attachments`: for failures, a screenshot (base64 PNG) plus console errors and failing network calls as text files.
+10. For each failure, `report_defect` with:
+    - `case` and `run`, so the failing result and its evidence are linked;
+    - a symptom-style `title`;
+    - `actualResult`, `expected`, numbered `reproSteps`, `url`, and `environment` (browser and build).
+
+    Re-reporting the same problem is safe: it adds an occurrence, and it reopens the defect if it had been marked fixed.
+11. Bugs you notice outside any case (console errors, broken links): file them as defects with `area` set.
+12. `complete_run`, then summarise for the user: the area key, the scenarios and cases created, pass/fail counts, the defect keys, and anything you couldn't test.
+
+## Rules
+- Never guess results. If you didn't observe it, mark the case `blocked` and explain why.
+- Don't create accounts, payments or other irreversible actions on shared environments unless the area notes say it's safe.
+- Prefer updating existing areas, scenarios and cases (same `ref` or `key`) over creating near-duplicates.

package/plugin/kasauti/skills/fix-defects/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: fix-defects
+description: Pick up open defects from Kasauti, reproduce them, fix the code in this repository, and mark them fixed for tester verification. Use when asked to "fix open bugs/defects/issues", "work the Kasauti queue", fix a specific defect key like DEMO-D7, or handle reopened defects.
+---
+
+# Fix Kasauti defects
+
+Kasauti holds the bug; this repo holds the code. You move a defect from `open` to `in_progress` (claimed), then to `fixed`. A **human tester** moves it to `verified`, or reopens it. You can't verify.
+
+## 1. Choose work
+1. `list_defects` for the project (the default is unresolved). If the user named a key, use that one.
+   - Do reopened defects first (`reopened > 0`). Their comments say why the last fix wasn't enough.
+   - Then go by severity (blocker → critical → major).
+2. `claim_defect` before you touch code. If it says someone else is working on it, pick another. Don't use `force` unless the user tells you to.
+
+## 2. Understand
+3. `get <defect key>` returns the full bundle: actual vs expected, repro steps, URL, environment, the linked case's steps, failing results with stack traces, evidence links (screenshots and logs, fetch them with the same token), and the comment thread.
+4. Find the code behind the area/route: `get <area key>` gives the route or endpoint. Search the repo for it.
+
+## 3. Reproduce, then fix
+5. Reproduce first. Use a browser (Playwright MCP / `playwright-cli`) for UI bugs, or a request or failing test for APIs. If it doesn't reproduce, `comment` with what you tried and `release_defect` it. Don't mark it fixed.
+6. Fix the root cause. Add or adjust an automated test that fails before the fix and passes after.
+   - If the project uses the Kasauti Playwright reporter, tag the test with the case key, e.g. `test('… @DEMO-12')`.
+7. Run the relevant tests. Commit with the defect key in the message, e.g. `fix(profile): persist display name (DEMO-D7)`.
+
+## 4. Hand back
+8. `resolve_defect` with:
+   - `notes`: the root cause, what changed, and how to check it (one short paragraph a tester can follow);
+   - `commit`: the SHA; `prUrl` if you opened a PR.
+
+   This queues a retest of the linked case in the project's **Defect verification** run.
+9. Tell the user which defects you moved to fixed and which you released, and why.
+
+## Rules
+- One defect, one focused change. Don't bundle unrelated fixes under one defect.
+- If the "defect" is actually expected behaviour, `comment` your reasoning and leave the status for a human (they can mark it invalid).
+- Never mark a defect fixed without running the code path.

package/plugin/kasauti/skills/run-tests/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: run-tests
+description: Report automated test results (Playwright, or any framework, or API checks) into Kasauti, and design API test cases from endpoints. Use for backend/API projects, CI reporting, importing an OpenAPI spec, or "run the suite and record results in Kasauti".
+---
+
+# Automated and API testing with Kasauti
+
+## Playwright projects
+Add the reporter once:
+```ts
+// playwright.config.ts
+reporter: [['list'], ['@isummation/kasauti-playwright-reporter', { project: 'DEMO' }]],
+```
+Then run with `KASAUTI_URL` and `KASAUTI_TOKEN` set (in CI, use an agent token stored as a secret).
+- Tests tagged with a case key (`test('login works @DEMO-12', …)`) report into that case.
+- Untagged tests are matched by file/describe path + title. The first time they run, they're created as **draft automated cases**.
+- Each run creates a run (`source: automation`) and completes it. Set `KASAUTI_RUN=DEMO-R5` to report into an existing run instead.
+
+## Other frameworks
+Post results directly, in batches of up to 1000:
+```
+POST /runs                       {"project":"DEMO","title":"CI #123","source":"automation"}
+POST /k/DEMO-R5/results/bulk     {"results":[{"case":"DEMO-12","status":"passed","durationMs":120},
+                                             {"title":"refund > partial","suite":"API/Refunds","status":"failed","stacktrace":"..."}]}
+POST /k/DEMO-R5/complete
+```
+Statuses: passed, failed, blocked, skipped, invalid.
+
+## Backend / API projects
+1. Import the API surface once, and re-import when it changes (it's idempotent):
+   - `kasauti import openapi DEMO openapi.yaml`
+
+   This creates one **endpoint area** per operation (`route: "POST /orders"`), grouped under a module area per tag.
+2. `project_map` to see the endpoints with no cases.
+3. Per endpoint, `upsert_scenario` for the behaviours (create succeeds, validation, auth, not found, idempotency, pagination…). Then `upsert_cases` with `layer: api`. Steps are the request (`action: "POST /orders"`, `data`: the body) and `expected` is the status and key fields.
+4. Execute with an agent run:
+   - `start_run` with `area` set to the module area;
+   - for each case, call the API (curl/fetch against the project base URL);
+   - `report_result` with the response status/body excerpt in `comment`;
+   - `report_defect` on failure (put the request/response in `actualResult`).
+5. If you write automated tests for these cases, tag them with the case keys so CI results land on the same cases.