qactl 0.1.0-alpha.1

package/README.md

@@ -0,0 +1,11 @@
+# qactl (alpha)
+
+Agentic QA CLI for the private pilot. This release supports the commands printed by `qa --help`; the full v1 command catalog is still in development.
+
+Requires Node.js 22 or newer. Install a pinned version with `npm install --global qactl@0.1.0-alpha.1`, then run `qactl --help` or `qa --help`. Both names run the same executable.
+
+Set `QA_API_URL` to the Agentic QA API and `QA_API_TOKEN` to a token created in your web account. Run `qa doctor --json` to check connectivity and authentication. Tokens are never passed as command arguments.
+
+The current GKE pilot has no public endpoint. You can use the private port-forward described in the repository's `HANDOFF.md` while authorized to access that environment.
+
+Package source: `https://github.com/SicoseSA/agentic-qa` (private repository). Package contents are the compiled CLI and this README; no browser or runner is installed.

package/dist/index.js

@@ -0,0 +1,161 @@
+#!/usr/bin/env node
+import { readFileSync } from 'node:fs';
+const base = process.env.QA_API_URL || 'http://127.0.0.1:5010';
+const token = process.env.QA_API_TOKEN;
+const args = process.argv.slice(2);
+const json = args.includes('--json');
+const cliVersion = '0.1.0-alpha.1';
+const schemaVersion = '1.0';
+function value(flag) { const i = args.indexOf(flag); return i >= 0 ? args[i + 1] : undefined; }
+function output(data) { process.stdout.write(JSON.stringify(data) + '\n'); }
+function error(code, message, exit = 2) { output({ schema_version: '1.0', error: { code, message } }); process.exit(exit); }
+async function request(route, options = {}) {
+    if (!token)
+        error('AUTH_REQUIRED', 'Set QA_API_TOKEN from the web account screen', 3);
+    const response = await fetch(base + route, { ...options, headers: { Authorization: `Bearer ${token}`, ...options.headers } });
+    const body = await response.json();
+    if (body.schema_version !== schemaVersion)
+        error('API_SCHEMA_INCOMPATIBLE', `This CLI supports API schema ${schemaVersion}; the server returned ${String(body.schema_version ?? 'none')}`, 5);
+    if (!response.ok)
+        error(body.error?.code || 'HTTP_ERROR', body.error?.message || `HTTP ${response.status}`, response.status === 401 || response.status === 403 ? 3 : response.status === 409 ? 8 : 2);
+    return body;
+}
+function input() {
+    const file = value('--file');
+    if (!file)
+        error('FILE_REQUIRED', 'Use --file path.json or --file -');
+    return JSON.parse(readFileSync(file === '-' ? 0 : file, 'utf8'));
+}
+async function main() {
+    const [group, action] = args;
+    if (!group || args.includes('--help') || group === 'help') {
+        const commands = ['qa version --json', 'qa doctor --json', 'qa schema --json', 'qa auth whoami --json', 'qa project list --json', 'qa deployment register --project ID --file deployment.json --json', 'qa verify --project ID --deployment ID --scenario SCN-FIXTURE-TOAST --idempotency-key KEY --deadline-seconds 1800 --wait --json', 'qa run get ID --json', 'qa run cancel ID --json', 'qa operation get ID --json', 'qa operation wait ID --timeout-ms 120000 --json', 'qa operation cancel ID --json', 'qa finding list --project ID --json'];
+        if (json)
+            output({ schema_version: '1.0', data: { commands } });
+        else
+            process.stdout.write(commands.join('\n') + '\n');
+        return;
+    }
+    if (group === 'version')
+        return output({ schema_version: schemaVersion, data: { version: cliVersion, api: 'v1', package: 'qactl' } });
+    if (group === 'doctor') {
+        const checks = [];
+        checks.push({ name: 'node', status: Number(process.versions.node.split('.')[0]) >= 22 ? 'ok' : 'fail', detail: `Node ${process.versions.node}; required >=22` });
+        let endpoint;
+        try {
+            endpoint = new URL(base);
+            if (!['https:', 'http:'].includes(endpoint.protocol) || endpoint.username || endpoint.password || endpoint.search || endpoint.hash)
+                throw new Error();
+            checks.push({ name: 'api_url', status: 'ok' });
+        }
+        catch {
+            checks.push({ name: 'api_url', status: 'fail', detail: 'Set QA_API_URL to an HTTP(S) API origin without embedded credentials' });
+        }
+        if (endpoint) {
+            try {
+                const response = await fetch(new URL('/healthz', endpoint), { signal: AbortSignal.timeout(5000) });
+                checks.push({ name: 'api_health', status: response.ok ? 'ok' : 'fail', detail: response.ok ? undefined : `HTTP ${response.status}` });
+            }
+            catch {
+                checks.push({ name: 'api_health', status: 'fail', detail: 'API health endpoint unavailable' });
+            }
+        }
+        checks.push({ name: 'api_token', status: token ? 'ok' : 'fail', detail: token ? undefined : 'Set QA_API_TOKEN from the web account screen' });
+        if (endpoint && token) {
+            try {
+                const response = await fetch(new URL('/v1/me', endpoint), { headers: { Authorization: `Bearer ${token}` }, signal: AbortSignal.timeout(5000) });
+                const body = await response.json();
+                checks.push({ name: 'api_auth', status: response.ok && body.schema_version === schemaVersion ? 'ok' : 'fail',
+                    detail: response.ok && body.schema_version === schemaVersion ? undefined : body.schema_version !== schemaVersion ? 'API schema incompatible' : `HTTP ${response.status}` });
+            }
+            catch {
+                checks.push({ name: 'api_auth', status: 'fail', detail: 'Token could not be verified' });
+            }
+        }
+        const ok = checks.every(check => check.status === 'ok');
+        output({ schema_version: schemaVersion, data: { status: ok ? 'ok' : 'needs_configuration', checks } });
+        if (!ok)
+            process.exitCode = 5;
+        return;
+    }
+    if (group === 'schema')
+        return output({ schema_version: schemaVersion, data: { commands: ['auth whoami', 'project list', 'deployment register', 'verify', 'run get', 'run cancel', 'operation get', 'operation wait', 'operation cancel', 'finding list'], scenarioIds: ['SCN-FIXTURE-TOAST', 'SCN-FIXTURE-PERSISTENCE'] } });
+    if (group === 'auth' && action === 'whoami')
+        return output(await request('/v1/me'));
+    if (group === 'project' && action === 'list')
+        return output(await request('/v1/projects'));
+    if (group === 'deployment' && action === 'register') {
+        const project = value('--project');
+        if (!project)
+            error('PROJECT_REQUIRED', 'Use --project ID');
+        return output(await request(`/v1/projects/${encodeURIComponent(project)}/deployments`, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify(input()) }));
+    }
+    if (group === 'run' && action === 'get') {
+        if (!args[2])
+            error('RUN_REQUIRED', 'Use qa run get ID');
+        return output(await request(`/v1/runs/${encodeURIComponent(args[2])}`));
+    }
+    if (group === 'run' && action === 'cancel') {
+        if (!args[2])
+            error('RUN_REQUIRED', 'Use qa run cancel ID');
+        return output(await request(`/v1/runs/${encodeURIComponent(args[2])}/cancel`, { method: 'POST' }));
+    }
+    if (group === 'operation' && action === 'get') {
+        if (!args[2])
+            error('OPERATION_REQUIRED', 'Use qa operation get ID');
+        return output(await request(`/v1/operations/${encodeURIComponent(args[2])}`));
+    }
+    if (group === 'operation' && action === 'cancel') {
+        if (!args[2])
+            error('OPERATION_REQUIRED', 'Use qa operation cancel ID');
+        return output(await request(`/v1/operations/${encodeURIComponent(args[2])}/cancel`, { method: 'POST' }));
+    }
+    if (group === 'operation' && action === 'wait') {
+        if (!args[2])
+            error('OPERATION_REQUIRED', 'Use qa operation wait ID');
+        const deadline = Date.now() + Number(value('--timeout-ms') || 120000);
+        while (Date.now() < deadline) {
+            const current = await request(`/v1/operations/${encodeURIComponent(args[2])}`);
+            if (['succeeded', 'failed', 'cancelled', 'timed_out'].includes(current.data.status)) {
+                output(current);
+                process.exit(current.data.status === 'succeeded' ? 0 : current.data.status === 'cancelled' || current.data.status === 'timed_out' ? 6 : 5);
+            }
+            await new Promise(resolve => setTimeout(resolve, 1500));
+        }
+        error('WAIT_TIMEOUT', `Operation ${args[2]} may still be running`, 6);
+    }
+    if (group === 'finding' && action === 'list') {
+        const project = value('--project');
+        if (!project)
+            error('PROJECT_REQUIRED', 'Use --project ID');
+        return output(await request(`/v1/projects/${encodeURIComponent(project)}/findings`));
+    }
+    if (group === 'verify') {
+        const project = value('--project'), deployment = value('--deployment'), scenario = value('--scenario') || 'SCN-FIXTURE-TOAST';
+        if (!project || !deployment)
+            error('INPUT_REQUIRED', 'Use --project and --deployment');
+        const key = value('--idempotency-key');
+        const deadlineSeconds = value('--deadline-seconds');
+        const queued = await request('/v1/runs', { method: 'POST', headers: { 'content-type': 'application/json', ...(key ? { 'Idempotency-Key': key } : {}) }, body: JSON.stringify({ projectId: project, deploymentId: deployment, scenarioId: scenario, ...(deadlineSeconds ? { deadlineSeconds: Number(deadlineSeconds) } : {}) }) });
+        if (!args.includes('--wait'))
+            return output(queued);
+        const runId = queued.data.runId;
+        const deadline = Date.now() + Number(value('--timeout-ms') || 120000);
+        while (Date.now() < deadline) {
+            const current = await request(`/v1/runs/${runId}`);
+            if (current.data.run.status === 'aborted') {
+                output(current);
+                process.exit(6);
+            }
+            if (current.data.run.status === 'completed') {
+                output(current);
+                const gate = current.data.run.gate_status;
+                process.exit(gate === 'pass' ? 0 : gate === 'needs_review' ? 7 : current.data.run.automatic_verdict === 'failed' ? 1 : 5);
+            }
+            await new Promise(resolve => setTimeout(resolve, 1500));
+        }
+        error('WAIT_TIMEOUT', `Run ${runId} may still be running`, 6);
+    }
+    error('UNKNOWN_COMMAND', 'Run qa --help');
+}
+main().catch(e => error('CLI_ERROR', e instanceof Error ? e.message : String(e), 5));

package/package.json

@@ -0,0 +1,11 @@
+{
+  "name": "qactl",
+  "version": "0.1.0-alpha.1",
+  "description": "Agentic QA command-line client (early private-pilot alpha)",
+  "type": "module",
+  "license": "UNLICENSED",
+  "repository": {"type":"git","url":"git+https://github.com/SicoseSA/agentic-qa.git","directory":"packages/cli"},
+  "engines": {"node": ">=22"},
+  "bin": { "qa": "dist/index.js", "qactl": "dist/index.js" },
+  "files": ["dist", "README.md"]
+}