@levr-one/cli 0.3.0 → 0.4.0

package/README.md

@@ -1,8 +1,15 @@
 # @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`.
+The command-line interface for [Levr](https://www.levr.one). The binary is
+`levr`, and it does three jobs:
+
+- **Connect your AI tools** — `levr mcp add` wires the Levr MCP server into
+  the AI clients on your machine (Claude Desktop, Claude Code, Cursor,
+  Windsurf, Zed) with one command.
+- **Push test results** — `levr push` uploads results from any terminal or CI
+  pipeline.
+- **Import test cases** — `levr import` brings existing cases in from CSV,
+  Excel, JSON, or Google Sheets.
 
 ## Install
 
@@ -15,82 +22,68 @@ npx @levr-one/cli --help
 The package is self-contained — no peer setup required. A global install
 replaces the `levr` bin from the deprecated `@levr-one/setup` package.
 
-## Get started
-
-Pushing test results needs authentication and nothing else — log in once
-(or set `LEVR_TOKEN` in CI):
-
-```bash
-levr auth login              # browser PKCE (or --device-code for SSH/headless)
-levr push ./results.xml
-```
+## Quick start
 
-Using an AI client (Claude Desktop/Code, Cursor, Windsurf, Zed)? Wire the
-Levr MCP server into it with one command — no login needed; the client opens
-a browser to authorize the first time it connects:
+**Using an AI client?** Wire the Levr MCP server into it — no login needed;
+the client opens a browser to authorize the first time it connects:
 
 ```bash
-npx @levr-one/cli mcp add    # detect installed clients and pick interactively
+npx @levr-one/cli mcp add
 ```
 
-Config edits preserve your existing MCP servers and comments, and re-running
-is a no-op. Use `--all`, `--client <id>`, or `--yes` for non-interactive
-runs and `--dry-run` to preview.
-
-### Shell completion (optional)
-
-Tab-completion is an explicit opt-in step (it is not installed automatically):
+**Pushing test results?** Authentication is all you need — log in once (or
+set `LEVR_TOKEN` in CI):
 
 ```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
+levr auth login              # browser PKCE (or --device-code for SSH/headless)
+levr push ./results.xml
 ```
 
-Opens a browser for PKCE-based OAuth login.
+## Connect AI clients: `levr mcp add`
 
-### Device code (SSH / headless)
+Detects the MCP-capable clients installed on your machine, lets you pick
+which to set up, and writes the Levr MCP server into each one's config:
 
 ```bash
-levr auth login --device-code
+levr mcp add                 # detect clients and pick interactively
+levr mcp add --all           # set up every detected client
+levr mcp add --dry-run       # preview the changes without writing
+levr mcp add --client cursor,zed --yes   # non-interactive selection
 ```
 
-A code is displayed in the terminal. Open the provided URL on any device, enter
-the code, and approve.
+What it writes is **credential-free** — a `levr` server entry that connects
+via `mcp-remote`. No token or secret is stored; your client opens the browser
+to authorize with Levr on its first connection. After a run, restart the
+client(s) and authorize once.
 
-### Personal Access Token (CI/CD)
-
-Set the `LEVR_TOKEN` environment variable and the CLI uses it automatically —
-no interactive login:
+**Supported clients:**
 
-```bash
-export LEVR_TOKEN=<your-personal-access-token>
-levr push ./results.xml
-```
+| Client         | How it's configured                                                            |
+| -------------- | ------------------------------------------------------------------------------ |
+| Claude Desktop | config file (`claude_desktop_config.json`)                                     |
+| Claude Code    | prints the `claude mcp add --transport http levr <url>` command for you to run |
+| Cursor         | config file (`~/.cursor/mcp.json`)                                             |
+| Windsurf       | config file (`~/.codeium/windsurf/mcp_config.json`)                            |
+| Zed            | config file (`settings.json`, `context_servers`)                               |
+| VS Code, Codex | listed but not yet installable (coming soon)                                   |
 
-### Other auth commands
+Config edits are **safe and repeatable**: existing MCP servers and comments
+in your config files are preserved (jsonc-aware merge), and re-running is a
+no-op that reports "already set up".
 
-```bash
-levr auth status     # show current authentication state
-levr auth logout     # clear stored credentials
-```
+**Flags:**
 
-## Workspaces
+| Flag              | Alias | Description                                           |
+| ----------------- | ----- | ----------------------------------------------------- |
+| `--client <id,…>` |       | Set up these client ids (comma-separated or repeated) |
+| `--all`           |       | Set up every detected, installable client             |
+| `--yes`           | `-y`  | Non-interactive; auto-select detected clients         |
+| `--dry-run`       |       | Show the changes without writing                      |
+| `--url <url>`     |       | MCP server URL (default derived from the API server)  |
 
-```bash
-levr workspace list       # list the workspaces you belong to
-levr workspace select     # choose the active workspace
-levr workspace current    # show the active workspace
-```
+Runs non-interactively whenever `--all`, `--client`, or `--yes` is passed —
+or automatically when not attached to a terminal (CI). Unknown client ids and
+failed writes exit non-zero.
 
 ## Push test results
 
@@ -138,6 +131,69 @@ 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).
 
+## Import test cases
+
+```bash
+levr import <file> --team-id <uuid> [options]
+```
+
+Brings existing test cases into Levr from CSV, Excel (`.xlsx`), JSON, or a
+public Google Sheet. It runs in two phases: **preview** proposes a mapping from
+your columns onto the Levr test-case schema (exact and fuzzy matching, with an
+LLM assist for whatever is left over), you review and adjust it, then **commit**
+writes the folders, tests, steps, and preconditions.
+
+In a terminal, unmapped and low-confidence columns are walked with a picker. For
+scripts and CI, pass `--yes` — and `--map` or `--mapping-file` to pin the
+mapping so a replay can't drift.
+
+**One column must map to `test_name`.** Interactive runs ask for it;
+non-interactive runs exit 1 rather than import unnamed cases.
+
+**Examples:**
+
+```bash
+# Interactive import from a CSV export
+levr import ./testrail-export.csv --team-id <uuid>
+
+# Excel, with one column pinned up front
+levr import ./cases.xlsx --team-id <uuid> --map "Title=test_name"
+
+# A public Google Sheet, no prompts
+levr import --sheets-url "https://docs.google.com/spreadsheets/d/..." --team-id <uuid> --yes
+
+# Save the confirmed mapping once, then replay it in CI
+levr import ./cases.csv --team-id <uuid> --save-mapping mapping.json
+levr import ./cases.csv --team-id <uuid> --mapping-file mapping.json --yes
+```
+
+**Flags:**
+
+| Flag                    | Alias | Description                                                                       |
+| ----------------------- | ----- | --------------------------------------------------------------------------------- |
+| `--team-id <uuid>`      | `-t`  | Team the imported test cases belong to (required)                                 |
+| `--workspace-id <uuid>` | `-w`  | Workspace ID (required for multi-workspace JWT auth)                              |
+| `--sheets-url <url>`    |       | Public Google Sheets URL, used instead of a file argument                         |
+| `--format <type>`       | `-f`  | Source format: `csv`, `xlsx`, `json` (auto-detected from the filename if omitted) |
+| `--map <pair>`          | `-m`  | Column override, repeatable — three forms, below                                  |
+| `--mapping-file <path>` |       | JSON file holding a saved confirmed mapping (from `--save-mapping`)               |
+| `--save-mapping <path>` |       | Write the confirmed mapping to this JSON file for CI replay                       |
+| `--yes`                 | `-y`  | Accept the mapping without prompts (required for non-TTY runs)                    |
+| `--verbose`             | `-v`  | Show detailed output                                                              |
+
+`--map` accepts three forms:
+
+| Form                            | Effect                                                                         |
+| ------------------------------- | ------------------------------------------------------------------------------ |
+| `"Source Column=target_field"`  | Map the column onto that Levr field                                            |
+| `"Source Column="`              | Drop the column (empty target)                                                 |
+| `"Source Column=labels:prefix"` | Import each value as the label `prefix:value`, keeping the column's provenance |
+
+```bash
+# Keep a TestRail "State" column as state:Draft / state:Approved labels
+levr import ./cases.csv --team-id <uuid> --map "State=labels:state"
+```
+
 ## CI/CD integration
 
 ### GitHub Actions
@@ -168,6 +224,61 @@ withEnv(["LEVR_TOKEN=${LEVR_TOKEN}"]) {
 }
 ```
 
+## Authentication
+
+Needed for `push` and `workspace` commands (`mcp add` needs none). Three 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
+```
+
+## 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
+```
+
 ## Configuration
 
 All configuration is via environment variables. Flags take precedence.
@@ -183,6 +294,14 @@ All configuration is via environment variables. Flags take precedence.
 
 ## Troubleshooting
 
+**The `levr` server doesn't appear in my AI client after `mcp add`** — Restart
+the client; MCP servers are read at startup. Verify the entry with
+`levr mcp add --dry-run` (it reports "already set up" when the config is in
+place).
+
+**My client asks me to authorize Levr** — Expected on the first connection:
+the config is credential-free, so each client authorizes once in the browser.
+
 **`Authentication required. Run: levr auth login`** — No valid credentials
 found. Run `levr auth login` or set `LEVR_TOKEN`.
 

package/dist/cli.js

@@ -109,7 +109,7 @@ Examples:
 		aliases: { y: "yes" }
 	},
 	loader: async () => {
-		const { mcpAddHandler } = await import("./addHandler-boWTd9yY.js");
+		const { mcpAddHandler } = await import("./addHandler-DFtvzTci.js");
 		return mcpAddHandler;
 	}
 });
@@ -147,7 +147,7 @@ Examples:
 		aliases: { d: "device-code" }
 	},
 	loader: async () => {
-		const { loginHandler } = await import("./loginHandler-BfIUQJrC.js");
+		const { loginHandler } = await import("./loginHandler-D9k-tQLX.js");
 		return loginHandler;
 	}
 });
@@ -186,7 +186,7 @@ Examples:
 	},
 	parameters: {},
 	loader: async () => {
-		const { statusHandler } = await import("./statusHandler-BaQB40t7.js");
+		const { statusHandler } = await import("./statusHandler-DuVZJMtw.js");
 		return statusHandler;
 	}
 });
@@ -297,11 +297,123 @@ Examples:
 		}
 	},
 	loader: async () => {
-		const { pushHandler } = await import("./pushHandler-DBBa6hKz.js");
+		const { pushHandler } = await import("./pushHandler-COg5WbGS.js");
 		return pushHandler;
 	}
 });
 
+//#endregion
+//#region src/commands/import.ts
+const importCommand = buildCommand({
+	docs: {
+		brief: "Import test cases from CSV, Excel, JSON, or Google Sheets",
+		fullDescription: `Two-phase test-case import: preview proposes a column mapping to the
+Levr test-case schema (exact/fuzzy matching with an LLM assist), you review
+and adjust it, then commit writes folders, tests, steps, and preconditions.
+
+Interactive mode (default in a terminal) walks unmapped and low-confidence
+columns with a picker. For scripts/CI use --yes and/or --map.
+
+Required-field rule: a column must map to test_name or the commit is
+rejected — interactive mode will ask; non-interactive runs exit 1.
+
+Examples:
+  levr import ./testrail-export.csv --team-id <uuid>
+  levr import ./cases.xlsx --team-id <uuid> --map "Title=test_name"
+  levr import --sheets-url "https://docs.google.com/spreadsheets/d/..." --team-id <uuid> --yes
+  levr import ./cases.csv --team-id <uuid> --save-mapping mapping.json
+  levr import ./cases.csv --team-id <uuid> --mapping-file mapping.json --yes   # CI replay`
+	},
+	parameters: {
+		positional: {
+			kind: "tuple",
+			parameters: [{
+				parse: String,
+				brief: "Path to the source file (.csv, .xlsx, .json)",
+				placeholder: "file",
+				optional: true
+			}]
+		},
+		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 the imported test cases will belong to",
+				placeholder: "uuid",
+				optional: false
+			},
+			"sheets-url": {
+				kind: "parsed",
+				parse: String,
+				brief: "Public Google Sheets URL (instead of a file)",
+				placeholder: "url",
+				optional: true
+			},
+			format: {
+				kind: "enum",
+				values: [
+					"csv",
+					"xlsx",
+					"json"
+				],
+				brief: "Source format (auto-detected from the filename if omitted)",
+				optional: true
+			},
+			map: {
+				kind: "parsed",
+				parse: String,
+				brief: "Column override (repeatable): \"Column=target_field\", \"Column=\" to drop, or \"Column=labels:prefix\"",
+				placeholder: "pair",
+				variadic: true,
+				optional: true
+			},
+			"mapping-file": {
+				kind: "parsed",
+				parse: String,
+				brief: "JSON file with a saved confirmed mapping (from --save-mapping)",
+				placeholder: "path",
+				optional: true
+			},
+			"save-mapping": {
+				kind: "parsed",
+				parse: String,
+				brief: "Write the confirmed mapping to this JSON file for CI replay",
+				placeholder: "path",
+				optional: true
+			},
+			yes: {
+				kind: "boolean",
+				default: false,
+				brief: "Accept the mapping without prompts (required for non-TTY runs)"
+			},
+			verbose: {
+				kind: "boolean",
+				default: false,
+				brief: "Show detailed output"
+			}
+		},
+		aliases: {
+			w: "workspace-id",
+			t: "team-id",
+			f: "format",
+			m: "map",
+			y: "yes",
+			v: "verbose"
+		}
+	},
+	loader: async () => {
+		const { importHandler } = await import("./importHandler-ChywPYeL.js");
+		return importHandler;
+	}
+});
+
 //#endregion
 //#region src/commands/workspace/list.ts
 const listCommand = buildCommand({
@@ -318,7 +430,7 @@ Examples:
 	},
 	parameters: {},
 	loader: async () => {
-		const { listHandler } = await import("./listHandler-EsB3AeOB.js");
+		const { listHandler } = await import("./listHandler-fK9Mapr3.js");
 		return listHandler;
 	}
 });
@@ -351,7 +463,7 @@ Examples:
 		flags: {}
 	},
 	loader: async () => {
-		const { selectHandler } = await import("./selectHandler-XOUHdyea.js");
+		const { selectHandler } = await import("./selectHandler-BzQRF8E7.js");
 		return selectHandler;
 	}
 });
@@ -368,14 +480,14 @@ Examples:
 	},
 	parameters: {},
 	loader: async () => {
-		const { currentHandler } = await import("./currentHandler-Bm7GFMkj.js");
+		const { currentHandler } = await import("./currentHandler-BD-h0j-S.js");
 		return currentHandler;
 	}
 });
 
 //#endregion
 //#region package.json
-var version = "0.3.0";
+var version = "0.4.0";
 
 //#endregion
 //#region src/app.ts
@@ -404,6 +516,7 @@ const routes = buildRouteMap({
 		auth: authRoutes,
 		workspace: workspaceRoutes,
 		push: pushCommand,
+		import: importCommand,
 		install: buildInstallCommand("levr", { bash: "levr __complete" }),
 		uninstall: buildUninstallCommand("levr", { bash: true })
 	},