@levr-one/cli 0.1.0

package/README.md

@@ -0,0 +1,172 @@
+# @levr-one/cli
+
+The command-line interface for [Levr](https://www.levr.one). Push test results
+from any CI pipeline, manage authentication, and select workspaces. The binary
+is `levr`.
+
+## Install
+
+```bash
+npm install -g @levr-one/cli    # global install for daily use
+# or run once, no install:
+npx @levr-one/cli --help
+```
+
+The package is self-contained — no peer setup required.
+
+### Shell completion (optional)
+
+Tab-completion is an explicit opt-in step (it is not installed automatically):
+
+```bash
+levr install       # add shell completion for the current shell
+levr uninstall     # remove it
+```
+
+## Authentication
+
+The CLI supports three authentication modes.
+
+### Interactive (browser) — default
+
+```bash
+levr auth login
+```
+
+Opens a browser for PKCE-based OAuth login.
+
+### Device code (SSH / headless)
+
+```bash
+levr auth login --device-code
+```
+
+A code is displayed in the terminal. Open the provided URL on any device, enter
+the code, and approve.
+
+### Personal Access Token (CI/CD)
+
+Set the `LEVR_TOKEN` environment variable and the CLI uses it automatically —
+no interactive login:
+
+```bash
+export LEVR_TOKEN=<your-personal-access-token>
+levr push ./results.xml
+```
+
+### Other auth commands
+
+```bash
+levr auth status     # show current authentication state
+levr auth logout     # clear stored credentials
+```
+
+## Workspaces
+
+```bash
+levr workspace list       # list the workspaces you belong to
+levr workspace select     # choose the active workspace
+levr workspace current    # show the active workspace
+```
+
+## Push test results
+
+```bash
+levr push <file> [options]
+```
+
+The backend auto-detects the file format. In CI, the automation source name and
+run metadata are auto-detected. Team ID is optional — when omitted, the server
+resolves the team from the automation source (if `--source` matches a known
+source) or the workspace's default team.
+
+**Examples:**
+
+```bash
+# Basic push (server resolves the default team)
+levr push ./test-results.xml
+
+# With an explicit team
+levr push ./test-results.xml --team-id <uuid>
+
+# With a custom source name and run name
+levr push ./results.xml --source "backend-unit-tests" --run-name "nightly"
+```
+
+**Flags:**
+
+| Flag                        | Alias | Description                                                                                |
+| --------------------------- | ----- | ------------------------------------------------------------------------------------------ |
+| `--team-id <uuid>`          | `-t`  | Team ID (optional; server resolves default if omitted. Or set `LEVR_TEAM_ID`)              |
+| `--source <name>`           | `-s`  | Automation source name — groups recurring imports and remembers team (auto-detected in CI) |
+| `--run-name <name>`         | `-r`  | Name for the test run                                                                      |
+| `--format <type>`           | `-f`  | File format: `junit`, `gherkin`, `cucumber-json` (auto-detected if omitted)                |
+| `--parent-folder-id <uuid>` |       | Destination folder ID                                                                      |
+| `--create-run`              |       | Force run creation for structure-only imports                                              |
+| `--update-mode <mode>`      |       | `update` (default) or `create_new`                                                         |
+| `--verbose`                 | `-v`  | Show detailed output                                                                       |
+
+### Automation sources
+
+An automation source groups recurring imports from the same CI pipeline or test
+suite. When you pass `--source`, the server creates the source on first use and
+remembers which team it belongs to. On the first push, omit `--team-id` to link
+the source to the workspace's default team, or pass `--team-id` to link it to a
+specific team. Subsequent pushes with the same `--source` route to that team
+automatically. Source names are normalized (lowercased, trimmed).
+
+## CI/CD integration
+
+### GitHub Actions
+
+```yaml
+- name: Push test results to Levr
+  env:
+    LEVR_TOKEN: ${{ secrets.LEVR_TOKEN }}
+    # LEVR_TEAM_ID is optional — server resolves from automation source or workspace default
+  run: npx @levr-one/cli push ./test-results.xml
+```
+
+### GitLab CI
+
+```yaml
+push-results:
+  script:
+    - npx @levr-one/cli push ./test-results.xml
+  variables:
+    LEVR_TOKEN: $LEVR_TOKEN
+```
+
+### Jenkins
+
+```groovy
+withEnv(["LEVR_TOKEN=${LEVR_TOKEN}"]) {
+  sh 'npx @levr-one/cli push ./test-results.xml'
+}
+```
+
+## Configuration
+
+All configuration is via environment variables. Flags take precedence.
+
+| Variable        | Description                                                                              | Default                 |
+| --------------- | ---------------------------------------------------------------------------------------- | ----------------------- |
+| `LEVR_TOKEN`    | Personal Access Token (for CI / headless)                                                |                         |
+| `LEVR_URL`      | API base URL                                                                             | `https://api.levr.one`  |
+| `LEVR_AUTH_URL` | Auth server URL                                                                          | `https://auth.levr.one` |
+| `LEVR_TEAM_ID`  | Default team ID (optional; server resolves from automation source or workspace default)  |                         |
+| `LEVR_SOURCE`   | Automation source name override (groups imports, remembers team)                         |                         |
+
+## Troubleshooting
+
+**`Authentication required. Run: levr auth login`** — No valid credentials
+found. Run `levr auth login` or set `LEVR_TOKEN`.
+
+**`Token expired`** — Run `levr auth login` to re-authenticate.
+
+**Browser doesn't open during `levr auth login`** — Use
+`levr auth login --device-code` for headless environments.
+
+## License
+
+MIT

package/dist/app-0F0Zyyt7.js

@@ -0,0 +1,350 @@
+import { buildApplication, buildCommand, buildRouteMap, text_en } from "@stricli/core";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import chalk from "chalk";
+import { buildInstallCommand, buildUninstallCommand } from "@stricli/auto-complete";
+
+//#region src/utils/logger.ts
+var Logger = class {
+	verbose;
+	stdout;
+	stderr;
+	constructor(options) {
+		this.verbose = options.verbose ?? false;
+		this.stdout = options.stdout ?? process.stdout;
+		this.stderr = options.stderr ?? process.stderr;
+	}
+	info(message) {
+		this.stdout.write(`${chalk.blue("info")}  ${message}\n`);
+	}
+	success(message) {
+		this.stdout.write(`${chalk.green("ok")}    ${message}\n`);
+	}
+	error(message) {
+		this.stderr.write(`${chalk.red("error")} ${message}\n`);
+	}
+	warning(message) {
+		this.stdout.write(`${chalk.yellow("warn")}  ${message}\n`);
+	}
+	debug(message) {
+		if (this.verbose) this.stdout.write(`${chalk.gray("debug")} ${message}\n`);
+	}
+	setVerbose(verbose) {
+		this.verbose = verbose;
+	}
+};
+
+//#endregion
+//#region src/context.ts
+function buildContext(process$1) {
+	return {
+		process: process$1,
+		os,
+		fs,
+		path,
+		logger: new Logger({
+			verbose: false,
+			stdout: process$1.stdout,
+			stderr: process$1.stderr
+		})
+	};
+}
+
+//#endregion
+//#region src/commands/auth/login.ts
+const loginCommand = buildCommand({
+	docs: {
+		brief: "Authenticate with Levr",
+		fullDescription: `Authenticate with Levr using OAuth.
+
+By default, opens a browser for PKCE-based authentication.
+For headless environments (SSH, containers), use --device-code
+to authenticate via a code displayed in the terminal.
+
+Examples:
+  levr auth login                 # Browser-based PKCE login
+  levr auth login --device-code   # Device flow for SSH/headless`
+	},
+	parameters: {
+		flags: { "device-code": {
+			kind: "boolean",
+			default: false,
+			brief: "Use device code flow (for SSH/headless environments)"
+		} },
+		aliases: { d: "device-code" }
+	},
+	loader: async () => {
+		const { loginHandler } = await import("./loginHandler-C8D6DgjW.js");
+		return loginHandler;
+	}
+});
+
+//#endregion
+//#region src/commands/auth/logout.ts
+const logoutCommand = buildCommand({
+	docs: {
+		brief: "Log out of Levr",
+		fullDescription: `Remove stored credentials.
+
+Note: If using LEVR_TOKEN environment variable, it will remain set.
+
+Examples:
+  levr auth logout`
+	},
+	parameters: {},
+	loader: async () => {
+		const { logoutHandler } = await import("./logoutHandler-BBtdpxHX.js");
+		return logoutHandler;
+	}
+});
+
+//#endregion
+//#region src/commands/auth/status.ts
+const statusCommand = buildCommand({
+	docs: {
+		brief: "Check authentication status",
+		fullDescription: `Check the current authentication status.
+
+Shows whether you are authenticated, the auth method (PAT or JWT),
+and tests API reachability.
+
+Examples:
+  levr auth status`
+	},
+	parameters: {},
+	loader: async () => {
+		const { statusHandler } = await import("./statusHandler-DQDmEOGI.js");
+		return statusHandler;
+	}
+});
+
+//#endregion
+//#region src/commands/push.ts
+const pushCommand = buildCommand({
+	docs: {
+		brief: "Push test results to Levr",
+		fullDescription: `Upload a test result file to Levr.
+
+The backend auto-detects the file format (JUnit XML, Gherkin, Cucumber JSON).
+In CI environments, the automation source name and CI metadata are auto-detected.
+
+Team ID is optional. When omitted, the server resolves the team from:
+  1. The existing automation source's team (if --source matches a known source)
+  2. The workspace's default team
+
+Examples:
+  levr push ./test-results.xml
+  levr push ./results.xml --source "backend-unit-tests"
+  levr push ./report.json --team-id <uuid>   # explicit team
+  levr push ./report.json   # uses LEVR_TOKEN env var, default team`
+	},
+	parameters: {
+		positional: {
+			kind: "tuple",
+			parameters: [{
+				parse: String,
+				brief: "Path to test result file (.xml, .feature, .json)",
+				placeholder: "file",
+				optional: false
+			}]
+		},
+		flags: {
+			"workspace-id": {
+				kind: "parsed",
+				parse: String,
+				brief: "Workspace ID (required for multi-workspace JWT auth)",
+				placeholder: "uuid",
+				optional: true
+			},
+			"team-id": {
+				kind: "parsed",
+				parse: String,
+				brief: "Team ID (optional; server resolves default if omitted)",
+				placeholder: "uuid",
+				optional: true
+			},
+			source: {
+				kind: "parsed",
+				parse: String,
+				brief: "Automation source name (auto-detected in CI)",
+				placeholder: "name",
+				optional: true
+			},
+			"automation-source": {
+				kind: "parsed",
+				parse: String,
+				brief: "Automation source UUID. When set, routes to POST /v1/automation-run/ingest (synchronous, bypasses ImportJob queue) instead of POST /v1/imports.",
+				placeholder: "uuid",
+				optional: true
+			},
+			"run-name": {
+				kind: "parsed",
+				parse: String,
+				brief: "Name for the test run",
+				placeholder: "name",
+				optional: true
+			},
+			format: {
+				kind: "enum",
+				values: [
+					"junit",
+					"gherkin",
+					"cucumber-json"
+				],
+				brief: "File format (auto-detected if omitted)",
+				optional: true
+			},
+			"parent-folder-id": {
+				kind: "parsed",
+				parse: String,
+				brief: "Destination folder ID",
+				placeholder: "uuid",
+				optional: true
+			},
+			"update-mode": {
+				kind: "enum",
+				values: ["update", "create_new"],
+				default: "update",
+				brief: "How to handle existing tests"
+			},
+			verbose: {
+				kind: "boolean",
+				default: false,
+				brief: "Show detailed output"
+			}
+		},
+		aliases: {
+			w: "workspace-id",
+			t: "team-id",
+			s: "source",
+			a: "automation-source",
+			r: "run-name",
+			f: "format",
+			v: "verbose"
+		}
+	},
+	loader: async () => {
+		const { pushHandler } = await import("./pushHandler-DkCrbV7y.js");
+		return pushHandler;
+	}
+});
+
+//#endregion
+//#region src/commands/workspace/list.ts
+const listCommand = buildCommand({
+	docs: {
+		brief: "List available workspaces",
+		fullDescription: `List all workspaces you have access to.
+
+The current workspace (if selected) is marked with an asterisk (*).
+
+Requires JWT authentication (levr auth login).
+
+Examples:
+  levr workspace list`
+	},
+	parameters: {},
+	loader: async () => {
+		const { listHandler } = await import("./listHandler-BiwIo88i.js");
+		return listHandler;
+	}
+});
+
+//#endregion
+//#region src/commands/workspace/select.ts
+const selectCommand = buildCommand({
+	docs: {
+		brief: "Select a workspace",
+		fullDescription: `Select a workspace by ID.
+
+The selected workspace is used for all subsequent commands.
+Use 'levr workspace list' to see available workspaces.
+
+Requires JWT authentication (levr auth login).
+
+Examples:
+  levr workspace select <workspace-id>`
+	},
+	parameters: {
+		positional: {
+			kind: "tuple",
+			parameters: [{
+				parse: String,
+				brief: "Workspace ID",
+				placeholder: "workspace-id",
+				optional: false
+			}]
+		},
+		flags: {}
+	},
+	loader: async () => {
+		const { selectHandler } = await import("./selectHandler-C2UDAWOl.js");
+		return selectHandler;
+	}
+});
+
+//#endregion
+//#region src/commands/workspace/current.ts
+const currentCommand = buildCommand({
+	docs: {
+		brief: "Show current workspace",
+		fullDescription: `Show the currently selected workspace.
+
+Examples:
+  levr workspace current`
+	},
+	parameters: {},
+	loader: async () => {
+		const { currentHandler } = await import("./currentHandler-oXFeNNgd.js");
+		return currentHandler;
+	}
+});
+
+//#endregion
+//#region src/app.ts
+const routes = buildRouteMap({
+	routes: {
+		auth: buildRouteMap({
+			routes: {
+				login: loginCommand,
+				logout: logoutCommand,
+				status: statusCommand
+			},
+			docs: { brief: "Manage authentication" }
+		}),
+		workspace: buildRouteMap({
+			routes: {
+				list: listCommand,
+				select: selectCommand,
+				current: currentCommand
+			},
+			docs: { brief: "Manage workspace selection" }
+		}),
+		push: pushCommand,
+		install: buildInstallCommand("levr", { bash: "__levr_bash_complete" }),
+		uninstall: buildUninstallCommand("levr", { bash: true })
+	},
+	docs: {
+		brief: "The command-line interface for Levr",
+		hideRoute: {
+			install: true,
+			uninstall: true
+		}
+	}
+});
+const app = buildApplication(routes, {
+	name: "levr",
+	versionInfo: { currentVersion: "0.1.0" },
+	localization: { loadText: () => ({
+		...text_en,
+		exceptionWhileParsingArguments: (exc, ansiColor) => {
+			const base = text_en.exceptionWhileParsingArguments(exc, ansiColor);
+			const hint = "Run `levr <command> --help` for usage information.";
+			return ansiColor ? `${base}\n\x1b[2m${hint}\x1b[22m` : `${base}\n${hint}`;
+		}
+	}) }
+});
+
+//#endregion
+export { app, buildContext };

package/dist/bash-complete.js

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+import { app, buildContext } from "./app-0F0Zyyt7.js";
+import { proposeCompletions } from "@stricli/core";
+
+//#region src/bin/bash-complete.ts
+const inputs = process.argv.slice(3);
+if (process.env["COMP_LINE"]?.endsWith(" ")) inputs.push("");
+try {
+	for (const { completion } of await proposeCompletions(app, inputs, buildContext(process))) process.stdout.write(`${completion}\n`);
+} catch {}
+
+//#endregion
+export {  };

package/dist/cli.js

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+import { app, buildContext } from "./app-0F0Zyyt7.js";
+import { run } from "@stricli/core";
+
+//#region src/bin/cli.ts
+let savedExitCode;
+const processProxy = new Proxy(process, { set(target, prop, value) {
+	if (prop === "exitCode" && typeof value === "number" && value !== 0) savedExitCode = value;
+	return Reflect.set(target, prop, value);
+} });
+await run(app, process.argv.slice(2), buildContext(processProxy));
+if (savedExitCode !== void 0) process.exitCode = savedExitCode;
+
+//#endregion
+export {  };

package/dist/credentials-CfHLkU7k.js

@@ -0,0 +1,54 @@
+import { mkdirSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+
+//#region src/utils/env.ts
+const DEFAULT_API_URL = "https://api.levr.one";
+const DEFAULT_AUTH_URL = "https://auth.levr.one";
+/** OAuth client ID for the CLI (seeded in oauth_clients table) */
+const CLI_CLIENT_ID = "3";
+function getApiUrl() {
+	return process.env["LEVR_URL"] || DEFAULT_API_URL;
+}
+function getAuthUrl() {
+	return process.env["LEVR_AUTH_URL"] || DEFAULT_AUTH_URL;
+}
+function getTeamId(flagValue) {
+	return flagValue || process.env["LEVR_TEAM_ID"] || void 0;
+}
+function getPatToken() {
+	return process.env["LEVR_TOKEN"];
+}
+function getSourceOverride() {
+	return process.env["LEVR_SOURCE"];
+}
+function getAutomationSourceIdOverride() {
+	return process.env["LEVR_AUTOMATION_SOURCE_ID"];
+}
+
+//#endregion
+//#region src/auth/credentials.ts
+const CREDENTIALS_PATH = join(join(homedir(), ".config", "levr"), "credentials.json");
+function readCredentials() {
+	try {
+		const raw = readFileSync(CREDENTIALS_PATH, "utf8");
+		return JSON.parse(raw);
+	} catch {
+		return null;
+	}
+}
+function writeCredentials(creds) {
+	mkdirSync(dirname(CREDENTIALS_PATH), { recursive: true });
+	writeFileSync(CREDENTIALS_PATH, JSON.stringify(creds, null, 2), { mode: 384 });
+}
+function deleteCredentials() {
+	try {
+		unlinkSync(CREDENTIALS_PATH);
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+//#endregion
+export { CLI_CLIENT_ID, deleteCredentials, getApiUrl, getAuthUrl, getAutomationSourceIdOverride, getPatToken, getSourceOverride, getTeamId, readCredentials, writeCredentials };

package/dist/currentHandler-oXFeNNgd.js

@@ -0,0 +1,11 @@
+import { loadWorkspace } from "./workspace-store-BcyMJAht.js";
+
+//#region src/commands/workspace/currentHandler.ts
+function currentHandler() {
+	const workspaceId = loadWorkspace();
+	if (workspaceId) this.process.stdout.write(`Current workspace: ${workspaceId}\n`);
+	else this.process.stdout.write("No workspace selected.\n");
+}
+
+//#endregion
+export { currentHandler };

package/dist/listHandler-BiwIo88i.js

@@ -0,0 +1,44 @@
+import "./credentials-CfHLkU7k.js";
+import { authGetSitesV1, configureClient } from "./sdk-client-DunBmYLR.js";
+import { loadWorkspace } from "./workspace-store-BcyMJAht.js";
+import "./token-refresh-waF23pyw.js";
+import { resolveToken } from "./resolve-token-BL8vL_ok.js";
+
+//#region src/commands/workspace/listHandler.ts
+async function listHandler() {
+	let auth;
+	try {
+		auth = await resolveToken();
+	} catch {
+		this.logger.error("Not authenticated. Run 'levr auth login' first.");
+		this.process.exitCode = 1;
+		return;
+	}
+	if (auth.type === "pat") {
+		this.logger.error("Workspace listing requires JWT auth. Run 'levr auth login'.");
+		this.process.exitCode = 1;
+		return;
+	}
+	configureClient(auth);
+	const result = await authGetSitesV1();
+	if (result.error) {
+		this.logger.error("Failed to list workspaces.");
+		this.process.exitCode = 1;
+		return;
+	}
+	const sites = result.data.sites;
+	if (sites.length === 0) {
+		this.logger.info("No workspaces available.");
+		return;
+	}
+	const currentWs = loadWorkspace();
+	this.process.stdout.write("\nWorkspaces:\n\n");
+	for (const site of sites) {
+		const indicator = site.workspace_id === currentWs ? " *" : "";
+		this.process.stdout.write(`  ${site.workspace_name} (${site.workspace_id}) [${site.role}]${indicator}\n`);
+	}
+	this.process.stdout.write("\n");
+}
+
+//#endregion
+export { listHandler };