@isummation/kasauti-cli 0.2.0

package/README.md

@@ -0,0 +1,12 @@
+# @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.
+
+```bash
+npm install -g @isummation/kasauti-cli      # needs access to the @isummation npm org
+kasauti login https://<kasauti-api> --token <token>
+kasauti map SHOP
+kasauti --help
+```
+
+`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

@@ -0,0 +1,208 @@
+#!/usr/bin/env node
+// Kasauti CLI: a thin client over the REST API. Zero dependencies (Node >= 20).
+// Output is Markdown by default (easy for humans and LLMs); pass --json for JSON.
+import { parseArgs } from 'node:util';
+import { readFileSync, writeFileSync, existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { basename, join, extname } from 'node:path';
+
+const CONFIG = process.env.KASAUTI_CONFIG ?? join(homedir(), '.kasauti.json');
+const HELP = `kasauti <command> [args] [--json]
+
+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
+
+Explore
+  map <PROJECT>                          area tree with coverage and open defects
+  get <KEY>                              any entity: DEMO-12, DEMO-A3, DEMO-SC1, DEMO-R5, DEMO-D7
+  search <PROJECT> [text] [--type case|scenario|area|defect|run] [--status S] [--area KEY] [--tag T]
+  activity <PROJECT>
+
+Author (idempotent: same --ref updates)
+  area <PROJECT> --title T [--route /path] [--kind screen|endpoint|module] [--parent KEY] [--notes N] [--ref R] [--key KEY]
+  scenario <PROJECT> --title T [--area KEY] [--narrative N] [--ref R] [--key KEY]
+  cases <PROJECT> <file.json|->          JSON array of cases (or {"cases": [...]})
+  edit <KEY> '<json>'                    partial update of any entity
+  approve <KEY...>                       promote draft cases to actual (humans only)
+
+Execute
+  run start <PROJECT> --title T [--plan KEY] [--area KEY] [--scenario KEY] [--cases K1,K2] [--env E]
+  run next|complete|abort <RUN>
+  result <RUN> <CASE> <passed|failed|blocked|skipped|invalid> [-m comment] [--attach FILE]... [--duration MS]
+
+Defects
+  defects <PROJECT> [--status unresolved|open|in_progress|fixed|verified|invalid] [--mine]
+  defect report <PROJECT> --title T [--case KEY --run KEY] [--area KEY] [--url U] [--actual A] [--expected E] [--steps S] [--severity S] [--attach FILE]...
+  defect claim|release <KEY>
+  defect resolve <KEY> -m NOTES [--commit SHA] [--pr URL]
+  defect verify|reopen|invalid <KEY> [-m COMMENT]
+  verification <PROJECT>                 fixed defects awaiting a tester
+
+Other
+  comment <KEY> -m TEXT | attach <KEY> <FILE> [--kind screenshot]
+  import openapi|csv <PROJECT> <FILE> | export csv <PROJECT>
+  api <METHOD> <PATH> [JSON]             raw call
+
+Env: KASAUTI_URL, KASAUTI_TOKEN override the config file.`;
+
+const { values: o, positionals: args } = parseArgs({
+  allowPositionals: true,
+  options: {
+    json: { type: 'boolean' }, help: { type: 'boolean', short: 'h' },
+    token: { type: 'string' }, agent: { type: 'string' },
+    title: { type: 'string' }, route: { type: 'string' }, kind: { type: 'string' }, parent: { type: 'string' }, notes: { type: 'string' },
+    ref: { type: 'string' }, key: { type: 'string' }, area: { type: 'string' }, scenario: { type: 'string' }, narrative: { type: 'string' },
+    type: { type: 'string' }, status: { type: 'string' }, tag: { type: 'string' }, plan: { type: 'string' }, cases: { type: 'string' },
+    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' },
+  },
+});
+
+const config = () => {
+  const f = existsSync(CONFIG) ? JSON.parse(readFileSync(CONFIG, 'utf8')) : {};
+  return { url: (process.env.KASAUTI_URL ?? f.url ?? 'http://localhost:3001').replace(/\/$/, ''), token: process.env.KASAUTI_TOKEN ?? f.token };
+};
+
+const die = (msg) => {
+  console.error(msg);
+  process.exit(1);
+};
+
+async function api(method, path, body, { md = !o.json, raw = false } = {}) {
+  const { url, token } = config();
+  const sep = path.includes('?') ? '&' : '?';
+  const res = await fetch(`${url}${path}${md ? `${sep}format=md` : ''}`, {
+    method,
+    headers: { ...(token ? { authorization: `Bearer ${token}` } : {}), ...(body ? { 'content-type': 'application/json' } : {}) },
+    body: body ? JSON.stringify(body) : undefined,
+  }).catch((e) => die(`Cannot reach ${url}: ${e.message}`));
+  const text = await res.text();
+  if (!res.ok) {
+    let msg = text;
+    try {
+      const j = JSON.parse(text);
+      msg = [j.message].flat().join('\n');
+    } catch {}
+    die(`Error ${res.status}: ${msg}`);
+  }
+  if (raw) return text;
+  try {
+    return JSON.parse(text);
+  } catch {
+    return text;
+  }
+}
+
+const print = (x) => console.log(typeof x === 'string' ? x.trimEnd() : JSON.stringify(x, null, 2));
+const need = (v, what) => v ?? die(`Missing ${what}. Run "kasauti --help".`);
+const file = (path, kind) => ({
+  kind: kind ?? (/\.(png|jpe?g|gif|webp)$/i.test(path) ? 'screenshot' : /\.zip$/i.test(path) ? 'trace' : 'file'),
+  filename: basename(path),
+  mime: { '.png': 'image/png', '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg', '.gif': 'image/gif', '.webp': 'image/webp', '.json': 'application/json', '.txt': 'text/plain', '.log': 'text/plain', '.html': 'text/html', '.zip': 'application/zip', '.har': 'application/json' }[extname(path).toLowerCase()] ?? 'application/octet-stream',
+  base64: readFileSync(path).toString('base64'),
+});
+const readInput = (f) => readFileSync(f === '-' ? 0 : f, 'utf8');
+const clean = (obj) => Object.fromEntries(Object.entries(obj).filter(([, v]) => v !== undefined));
+
+const [cmd, sub, ...rest] = args;
+if (o.help || !cmd) print(HELP), process.exit(0);
+
+switch (cmd) {
+  case 'login': {
+    const url = need(sub, '<url>').replace(/\/$/, '');
+    process.env.KASAUTI_URL = url;
+    // Sign-in is Microsoft-only, so the CLI uses a token created in the web app instead of a password.
+    process.env.KASAUTI_TOKEN = need(o.token, '--token');
+    const me = await api('GET', '/me', undefined, { md: false });
+    writeFileSync(CONFIG, JSON.stringify({ url, token: o.token }, null, 2), { mode: 0o600 });
+    print(`Logged in as ${me.name} <${me.email}> (${me.role}). Saved to ${CONFIG}`);
+    break;
+  }
+  case 'token': {
+    const r = await api('POST', '/tokens', clean({ name: need(sub, '<name>'), kind: o.agent ? 'agent' : 'user', agentName: o.agent }), { md: false });
+    print(o.json ? r : `Token (shown once): ${r.token}\nUse: export KASAUTI_TOKEN=${r.token}`);
+    break;
+  }
+  case 'whoami': print(await api('GET', '/me', undefined, { md: false })); break;
+  case 'projects': print(await api('GET', '/projects')); break;
+  case 'mcp-config': {
+    const { url } = config();
+    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 '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;
+  case 'search': {
+    const q = new URLSearchParams(clean({ project: need(sub, '<PROJECT>'), q: rest.join(' ') || undefined, type: o.type, status: o.status, area: o.area, tag: o.tag }));
+    print(await api('GET', `/search?${q}`));
+    break;
+  }
+  case 'area':
+    print(await api('POST', '/areas', clean({ project: need(sub, '<PROJECT>'), title: need(o.title, '--title'), route: o.route, kind: o.kind, parent: o.parent, notes: o.notes, ref: o.ref, key: o.key })));
+    break;
+  case 'scenario':
+    print(await api('POST', '/scenarios', clean({ project: need(sub, '<PROJECT>'), title: need(o.title, '--title'), area: o.area, narrative: o.narrative, ref: o.ref, key: o.key })));
+    break;
+  case 'cases': {
+    const data = JSON.parse(readInput(need(rest[0], '<file.json|->')));
+    print(await api('POST', '/cases', { project: need(sub, '<PROJECT>'), cases: Array.isArray(data) ? data : data.cases }));
+    break;
+  }
+  case 'edit': print(await api('PATCH', `/k/${need(sub, '<KEY>')}`, JSON.parse(need(rest[0], "'<json>'")))); break;
+  case 'approve': {
+    const keys = [sub, ...rest].filter(Boolean);
+    print(await api('POST', '/cases/bulk', { project: need(keys[0], '<KEY>').split('-')[0], keys, set: { status: 'actual' } }));
+    break;
+  }
+  case 'run': {
+    if (sub === 'start') {
+      print(await api('POST', '/runs', clean({ project: need(rest[0], '<PROJECT>'), title: need(o.title, '--title'), plan: o.plan, area: o.area, scenario: o.scenario, cases: o.cases?.split(','), environment: o.env })));
+    } else if (sub === 'next') print(await api('GET', `/k/${need(rest[0], '<RUN>')}/next`));
+    else if (sub === 'complete' || sub === 'abort') print(await api('POST', `/k/${need(rest[0], '<RUN>')}/${sub}`));
+    else die('run start|next|complete|abort');
+    break;
+  }
+  case 'result': {
+    const [kase, status] = rest;
+    print(await api('POST', `/k/${need(sub, '<RUN>')}/results`, clean({
+      case: need(kase, '<CASE>'), status: need(status, '<status>'), comment: o.message, durationMs: o.duration ? Number(o.duration) : undefined,
+      attachments: o.attach?.map((f) => file(f)),
+    })));
+    break;
+  }
+  case 'defects':
+    print(await api('GET', `/defects?${new URLSearchParams(clean({ project: need(sub, '<PROJECT>'), status: o.status, assignee: o.mine ? 'me' : undefined }))}`));
+    break;
+  case 'verification': print(await api('GET', `/projects/${need(sub, '<PROJECT>')}/verification`)); break;
+  case 'defect': {
+    const key = need(rest[0], '<KEY>');
+    if (sub === 'report') {
+      print(await api('POST', '/defects', clean({
+        project: key, title: need(o.title, '--title'), case: o.case, run: o.run, area: o.area, url: o.url, actualResult: o.actual, expected: o.expected,
+        reproSteps: o.steps, severity: o.severity, attachments: o.attach?.map((f) => file(f)),
+      })));
+    } else if (sub === 'claim') print(await api('POST', `/k/${key}/claim${o.force ? '?force=1' : ''}`));
+    else if (sub === 'release') print(await api('POST', `/k/${key}/release`));
+    else if (sub === 'resolve') print(await api('POST', `/k/${key}/resolve`, clean({ notes: need(o.message, '-m NOTES'), commit: o.commit, prUrl: o.pr })));
+    else if (['verify', 'reopen', 'invalid'].includes(sub)) print(await api('POST', `/k/${key}/${sub}`, clean({ comment: o.message })));
+    else die('defect report|claim|release|resolve|verify|reopen|invalid');
+    break;
+  }
+  case 'comment': print(await api('POST', `/k/${need(sub, '<KEY>')}/comments`, { body: need(o.message, '-m TEXT') })); break;
+  case 'attach': print(await api('POST', `/k/${need(sub, '<KEY>')}/attachments`, file(need(rest[0], '<FILE>'), o.kind), { md: false })); break;
+  case 'import': {
+    const [code, path] = rest;
+    const text = readInput(need(path, '<FILE>'));
+    if (sub === 'openapi') print(await api('POST', `/projects/${need(code, '<PROJECT>')}/import/openapi`, { text }));
+    else if (sub === 'csv') print(await api('POST', `/projects/${need(code, '<PROJECT>')}/import/csv`, { csv: text }));
+    else die('import openapi|csv <PROJECT> <FILE>');
+    break;
+  }
+  case 'export': print(await api('GET', `/projects/${need(rest[0], '<PROJECT>')}/export/csv`, undefined, { md: false, raw: true })); break;
+  case 'api': print(await api(need(sub, '<METHOD>').toUpperCase(), need(rest[0], '<PATH>'), rest[1] ? JSON.parse(rest[1]) : undefined)); break;
+  default: die(`Unknown command "${cmd}". Run "kasauti --help".`);
+}

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@isummation/kasauti-cli",
+  "version": "0.2.0",
+  "description": "Kasauti test management CLI for humans, CI and AI agents",
+  "type": "module",
+  "bin": {
+    "kasauti": "./kasauti.mjs"
+  },
+  "files": [
+    "kasauti.mjs",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git@gitlab.isummation.com:isummation-product/kasauti.git",
+    "directory": "packages/cli"
+  },
+  "publishConfig": {
+    "access": "restricted",
+    "registry": "https://registry.npmjs.org/"
+  }
+}