@isummation/kasauti-cli 0.3.0 → 0.4.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md
CHANGED
|
@@ -1,15 +1,157 @@
|
|
|
1
1
|
# @isummation/kasauti-cli
|
|
2
2
|
|
|
3
|
-
Command line for Kasauti test management
|
|
3
|
+
Command line for **Kasauti** test management, and the **Kasauti plugin for Claude Code**.
|
|
4
|
+
|
|
5
|
+
- People and scripts use the `kasauti` command to explore, write and run test cases and to report and fix defects.
|
|
6
|
+
- Claude Code gets the Kasauti tools (MCP) and three playbooks: explore a screen into test cases, run tests, fix defects.
|
|
7
|
+
|
|
8
|
+
Output is Markdown, which people and AI agents both read easily; add `--json` for scripts. Needs Node.js 20 or later; no dependencies.
|
|
9
|
+
|
|
10
|
+
## Install
|
|
4
11
|
|
|
5
12
|
```bash
|
|
6
13
|
npm install -g @isummation/kasauti-cli
|
|
7
|
-
kasauti login https://<kasauti-api> --token <token>
|
|
8
|
-
kasauti map SHOP
|
|
9
|
-
kasauti plugin install # Claude Code plugin: Kasauti MCP tools + explore / run / fix playbooks
|
|
10
|
-
kasauti --help
|
|
11
14
|
```
|
|
12
15
|
|
|
13
|
-
|
|
16
|
+
Or run it once without installing: `npx @isummation/kasauti-cli --help`.
|
|
17
|
+
|
|
18
|
+
## What you need from Kasauti
|
|
19
|
+
|
|
20
|
+
- **The API URL**, for example `https://kasauti-api.your-company.com`. It's the API's address, not the web app's; your Kasauti admin can tell you, and the web app shows it under **Settings → API tokens & agents**.
|
|
21
|
+
- **A token**, created in the web app under **Settings → API tokens & agents**. It is shown once, so copy it then.
|
|
22
|
+
- **Personal** token: for the `kasauti` command as yourself, and for CI.
|
|
23
|
+
- **Agent** token: for Claude Code. Everything it writes is marked as the agent, its test cases start as drafts for a person to approve, and it can't verify fixes.
|
|
24
|
+
- A token works only on the Kasauti server it was created on, and has your role there (tester or developer).
|
|
25
|
+
|
|
26
|
+
## Use the CLI
|
|
27
|
+
|
|
28
|
+
```bash
|
|
29
|
+
kasauti login https://kasauti-api.your-company.com --token <personal token> # saved to ~/.kasauti.json, readable only by you
|
|
30
|
+
kasauti whoami
|
|
31
|
+
kasauti projects
|
|
32
|
+
kasauti map SHOP # screens / endpoints with coverage and open defects
|
|
33
|
+
kasauti get SHOP-D7 # anything by key, with full context
|
|
34
|
+
kasauti defects SHOP --mine
|
|
35
|
+
kasauti result SHOP-R5 SHOP-12 failed -m "Total shows twice" --attach shot.png
|
|
36
|
+
kasauti --help # every command
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
Keys name everything. The letter after the project code says what a key is:
|
|
40
|
+
|
|
41
|
+
| Key | What it is |
|
|
42
|
+
|---|---|
|
|
43
|
+
| `SHOP-12` | test case (no letter) |
|
|
44
|
+
| `SHOP-A3` | area: a screen, endpoint or module |
|
|
45
|
+
| `SHOP-SC4` | scenario: a user goal |
|
|
46
|
+
| `SHOP-R5` | run: cases being executed |
|
|
47
|
+
| `SHOP-P2` | plan: a saved set of cases |
|
|
48
|
+
| `SHOP-M1` | milestone |
|
|
49
|
+
| `SHOP-D7` | defect |
|
|
50
|
+
|
|
51
|
+
`KASAUTI_URL` and `KASAUTI_TOKEN` in the environment take precedence over the saved login. CI uses them: store both as secret CI variables and no login step is needed.
|
|
52
|
+
|
|
53
|
+
## Connect Claude Code
|
|
54
|
+
|
|
55
|
+
**1. Install the plugin**
|
|
56
|
+
|
|
57
|
+
```bash
|
|
58
|
+
kasauti plugin install # for all your projects; --scope local for the current project only
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
This runs `claude plugin marketplace add` and `claude plugin install` for the copy of the plugin inside this package. If the `claude` command isn't on your PATH, it prints the two commands to run yourself.
|
|
62
|
+
|
|
63
|
+
**2. Give Claude Code the URL and an agent token.** The plugin reads them from two environment variables, `KASAUTI_URL` and `KASAUTI_TOKEN`. `kasauti login` does **not** set them: it only configures the `kasauti` command. Without them, the plugin calls `http://localhost:3001` with no token.
|
|
64
|
+
|
|
65
|
+
Set them where Claude Code starts. The commands below ask for the token without showing it, so it stays out of your shell history.
|
|
66
|
+
|
|
67
|
+
- **Linux, WSL, macOS with bash**: add them to `~/.bashrc`:
|
|
68
|
+
|
|
69
|
+
```bash
|
|
70
|
+
read -rsp "Kasauti agent token: " T && printf '\nexport KASAUTI_URL=https://kasauti-api.your-company.com\nexport KASAUTI_TOKEN=%s\n' "$T" >> ~/.bashrc && unset T && echo
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
- **macOS with zsh (the default)**: the same command with `~/.zshrc` instead of `~/.bashrc`.
|
|
74
|
+
|
|
75
|
+
- **fish**:
|
|
76
|
+
|
|
77
|
+
```fish
|
|
78
|
+
set -Ux KASAUTI_URL https://kasauti-api.your-company.com
|
|
79
|
+
read -s -P "Kasauti agent token: " T; and set -Ux KASAUTI_TOKEN $T; and set -e T
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
- **Windows (Claude Code running on Windows itself, in PowerShell)**:
|
|
83
|
+
|
|
84
|
+
```powershell
|
|
85
|
+
[Environment]::SetEnvironmentVariable('KASAUTI_URL', 'https://kasauti-api.your-company.com', 'User')
|
|
86
|
+
$t = Read-Host 'Kasauti agent token' -AsSecureString
|
|
87
|
+
[Environment]::SetEnvironmentVariable('KASAUTI_TOKEN', [Net.NetworkCredential]::new('', $t).Password, 'User'); Remove-Variable t
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
If you use Claude Code inside **WSL** (including VS Code connected to WSL), use the bash setup above instead: Windows variables don't reach it.
|
|
91
|
+
|
|
92
|
+
To change a value later, edit the line in that file rather than running the command again, which would add a second copy.
|
|
93
|
+
|
|
94
|
+
**3. Restart Claude Code.** It reads the variables only when it starts. In a terminal, open a new one. In **VS Code** (and other editors), close every window and reopen the editor; reloading a window isn't enough. For VS Code with WSL, if it still shows the old state, run `wsl --shutdown` in Windows and reopen.
|
|
95
|
+
|
|
96
|
+
**4. Check.** In Claude Code, run `/mcp`: `kasauti` should show as connected. Then ask *"List my Kasauti projects"*. In a terminal, `echo $KASAUTI_URL` should print your URL.
|
|
97
|
+
|
|
98
|
+
### Keep an agent to one project
|
|
99
|
+
|
|
100
|
+
If you're on several projects, give each repository its own token **limited to that project**. The agent then can't read or change any other project, even by mistake: other projects don't exist for that token, and it can't create tokens or do admin work.
|
|
101
|
+
|
|
102
|
+
1. Create the token in the web app (**Settings → API tokens & agents**, pick the project), or with the CLI:
|
|
103
|
+
|
|
104
|
+
```bash
|
|
105
|
+
kasauti token claude-code-shop --agent claude-code --project SHOP
|
|
106
|
+
```
|
|
107
|
+
|
|
108
|
+
2. Put it in the repository's `.claude/settings.local.json`. Claude Code applies its `env` only in this repository, over the variables from your shell, so your other repositories keep their own tokens:
|
|
109
|
+
|
|
110
|
+
```json
|
|
111
|
+
{
|
|
112
|
+
"env": {
|
|
113
|
+
"KASAUTI_URL": "https://kasauti-api.your-company.com",
|
|
114
|
+
"KASAUTI_TOKEN": "kst_…"
|
|
115
|
+
}
|
|
116
|
+
}
|
|
117
|
+
```
|
|
118
|
+
|
|
119
|
+
`settings.local.json` is for you alone: Claude Code adds it to the repository's `.gitignore` when it creates the file. Check it is ignored before you save a token in it; never put a token in the shared `.claude/settings.json`.
|
|
120
|
+
|
|
121
|
+
3. Restart Claude Code in that repository and run `/mcp`. Asking *"List my Kasauti projects"* should show only that project.
|
|
122
|
+
|
|
123
|
+
Deleting the project deletes its tokens. Revoke a token under **Settings → API tokens & agents**.
|
|
124
|
+
|
|
125
|
+
### Update
|
|
126
|
+
|
|
127
|
+
```bash
|
|
128
|
+
npm update -g @isummation/kasauti-cli
|
|
129
|
+
kasauti plugin update
|
|
130
|
+
```
|
|
131
|
+
|
|
132
|
+
Claude Code loads the plugin from the npm install folder, so the next session uses the new version. Switching Node.js versions (nvm, fnm, volta) moves that folder: install the CLI for the new version and run `kasauti plugin install` again.
|
|
133
|
+
|
|
134
|
+
### Remove
|
|
135
|
+
|
|
136
|
+
```bash
|
|
137
|
+
claude plugin uninstall kasauti@kasauti
|
|
138
|
+
claude plugin marketplace remove kasauti
|
|
139
|
+
npm uninstall -g @isummation/kasauti-cli
|
|
140
|
+
```
|
|
141
|
+
|
|
142
|
+
### Without the plugin (Cursor and other MCP clients)
|
|
143
|
+
|
|
144
|
+
Kasauti is a standard MCP server over HTTP: URL `<KASAUTI_URL>/mcp`, header `Authorization: Bearer <agent token>`. `kasauti mcp-config` prints the Claude Code command for your settings. You get the tools, without the playbooks.
|
|
145
|
+
|
|
146
|
+
## Troubleshooting
|
|
14
147
|
|
|
15
|
-
|
|
148
|
+
| What you see | Fix |
|
|
149
|
+
|---|---|
|
|
150
|
+
| `/mcp`: kasauti failed, `HTTP 401` or `Invalid or expired token` | `KASAUTI_TOKEN` isn't set where Claude Code started, was created on a different Kasauti server, or was revoked. Set it (step 2) and restart Claude Code fully. |
|
|
151
|
+
| `/mcp` shows `http://localhost:3001/mcp` | `KASAUTI_URL` isn't set where Claude Code started. Set it and restart Claude Code fully. |
|
|
152
|
+
| `Error 401` from `kasauti` | Log in again with a valid token, or check the `KASAUTI_TOKEN` you exported. |
|
|
153
|
+
| `Error 404` for a project that exists | You aren't assigned to it; ask a Kasauti admin. |
|
|
154
|
+
| `Error 403 … needs the tester role` or `needs a human` | Your role can't do that; agent tokens can't verify fixes or approve drafts. |
|
|
155
|
+
| `Cannot reach …` | Wrong `KASAUTI_URL` (use the API address), or no network route to it. |
|
|
156
|
+
| `kasauti plugin install`: `No bundled plugin here` | The `kasauti` on your PATH isn't this npm package. Run `npm install -g @isummation/kasauti-cli`. |
|
|
157
|
+
| The plugin vanished after switching Node.js versions | Run `kasauti plugin install` again. |
|
package/kasauti.mjs
CHANGED
|
@@ -13,7 +13,7 @@ const HELP = `kasauti <command> [args] [--json]
|
|
|
13
13
|
|
|
14
14
|
Setup
|
|
15
15
|
login <url> --token T save URL + a personal token (Settings → API tokens) to ~/.kasauti.json
|
|
16
|
-
token <name> [--agent NAME]
|
|
16
|
+
token <name> [--agent NAME] [--project CODE] create a personal (or agent) API token, optionally limited to one project
|
|
17
17
|
whoami | projects | mcp-config
|
|
18
18
|
plugin install|update [--scope user|local] add the bundled Claude Code plugin (skills + MCP) to Claude Code
|
|
19
19
|
plugin path where the bundled plugin is, for manual setup
|
|
@@ -55,7 +55,7 @@ const { values: o, positionals: args } = parseArgs({
|
|
|
55
55
|
allowPositionals: true,
|
|
56
56
|
options: {
|
|
57
57
|
json: { type: 'boolean' }, help: { type: 'boolean', short: 'h' },
|
|
58
|
-
token: { type: 'string' }, agent: { type: 'string' },
|
|
58
|
+
token: { type: 'string' }, agent: { type: 'string' }, project: { type: 'string' },
|
|
59
59
|
title: { type: 'string' }, route: { type: 'string' }, kind: { type: 'string' }, parent: { type: 'string' }, notes: { type: 'string' },
|
|
60
60
|
ref: { type: 'string' }, key: { type: 'string' }, area: { type: 'string' }, scenario: { type: 'string' }, narrative: { type: 'string' },
|
|
61
61
|
type: { type: 'string' }, status: { type: 'string' }, tag: { type: 'string' }, plan: { type: 'string' }, cases: { type: 'string' },
|
|
@@ -127,7 +127,7 @@ switch (cmd) {
|
|
|
127
127
|
break;
|
|
128
128
|
}
|
|
129
129
|
case 'token': {
|
|
130
|
-
const r = await api('POST', '/tokens', clean({ name: need(sub, '<name>'), kind: o.agent ? 'agent' : 'user', agentName: o.agent }), { md: false });
|
|
130
|
+
const r = await api('POST', '/tokens', clean({ name: need(sub, '<name>'), kind: o.agent ? 'agent' : 'user', agentName: o.agent, project: o.project }), { md: false });
|
|
131
131
|
print(o.json ? r : `Token (shown once): ${r.token}\nUse: export KASAUTI_TOKEN=${r.token}`);
|
|
132
132
|
break;
|
|
133
133
|
}
|
|
@@ -165,7 +165,14 @@ switch (cmd) {
|
|
|
165
165
|
if (r.status && i === 0 && sub === 'install') r = claude(['plugin', 'marketplace', 'update', 'kasauti']);
|
|
166
166
|
if (r.status) die(`Failed: ${show(a)}`);
|
|
167
167
|
}
|
|
168
|
-
|
|
168
|
+
// The plugin's MCP server only sees environment variables, not ~/.kasauti.json: say so when they're missing.
|
|
169
|
+
const missing = ['KASAUTI_URL', 'KASAUTI_TOKEN'].filter((v) => !process.env[v]);
|
|
170
|
+
if (missing.length)
|
|
171
|
+
console.log(`\nNot set yet: ${missing.join(', ')}. The plugin reads both from the environment (kasauti login only configures this CLI),\n` +
|
|
172
|
+
`so until then it calls http://localhost:3001 without a token. Set them, e.g. in ~/.bashrc:\n` +
|
|
173
|
+
` export KASAUTI_URL=${config().url}\n export KASAUTI_TOKEN=<an agent token from Settings → API tokens & agents>\n` +
|
|
174
|
+
`Details: https://www.npmjs.com/package/@isummation/kasauti-cli#connect-claude-code`);
|
|
175
|
+
print(`\nDone. Restart Claude Code (in VS Code: close every window), then check /mcp lists kasauti as connected.\nAfter upgrading the CLI (npm update -g @isummation/kasauti-cli), run: kasauti plugin update`);
|
|
169
176
|
break;
|
|
170
177
|
}
|
|
171
178
|
case 'map': print(await api('GET', `/projects/${need(sub, '<PROJECT>')}/map`)); break;
|
package/package.json
CHANGED