@levr-one/cli 0.3.1 → 0.5.0

package/README.md

@@ -1,13 +1,15 @@
 # @levr-one/cli
 
 The command-line interface for [Levr](https://www.levr.one). The binary is
-`levr`, and it does two jobs:
+`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
 
@@ -129,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
@@ -207,13 +272,39 @@ levr workspace current    # show the active workspace
 
 ## Shell completion (optional)
 
-Tab-completion is an explicit opt-in step (it is not installed automatically):
+`levr completion` prints a completion script to **stdout**. It never edits your
+shell config — you choose where the script goes:
 
 ```bash
-levr install       # add shell completion for the current shell
-levr uninstall     # remove it
+# This session only
+eval "$(levr completion bash)"
+eval "$(levr completion zsh)"
+
+# Persist it
+levr completion bash >> ~/.bashrc
+levr completion zsh  >> ~/.zshrc
+
+# Or system-wide (bash)
+levr completion bash > /etc/bash_completion.d/levr
+```
+
+**zsh:** load it _after_ `compinit`, which is what defines `compdef`:
+
+```zsh
+autoload -Uz compinit && compinit
+eval "$(levr completion zsh)"
 ```
 
+If `compinit` has not run, the script says so on stderr instead of failing with
+a bare `command not found: compdef`.
+
+Supported shells: **bash** and **zsh**. The shell is detected from `$SHELL` when
+you omit the argument — pass it explicitly in scripts, or to generate a script
+for a shell other than the one you are running. An unsupported or undetectable
+shell writes an error to stderr and exits non-zero.
+
+Nothing is installed automatically: the package ships no `postinstall` hook.
+
 ## Configuration
 
 All configuration is via environment variables. Flags take precedence.

package/dist/{addHandler-boWTd9yY.js → addHandler-K2a4rVv8.js}

@@ -1,7 +1,7 @@
-import { getApiUrl } from "./env-NxtzJJPk.js";
+import { getApiUrl } from "./env-CHeKHu5S.js";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
-import { homedir } from "node:os";
 import { delimiter, dirname, join } from "node:path";
+import { homedir } from "node:os";
 import { applyEdits, modify, parse } from "jsonc-parser";
 
 //#region ../mcp-harnesses/dist/catalog.js
@@ -356,17 +356,17 @@ function signalMatches(signal, env) {
 	return existsSync(signal.startsWith("~") ? expandTilde(signal, env.homedir) : signal);
 }
 /** Read a text file, or `null` if it doesn't exist / can't be read. */
-function readTextOrNull(path$1) {
+function readTextOrNull(path) {
 	try {
-		return readFileSync(path$1, "utf8");
+		return readFileSync(path, "utf8");
 	} catch {
 		return null;
 	}
 }
 /** Safe nested lookup over an unknown-typed parsed JSON value. */
-function getAtPath(obj, path$1) {
+function getAtPath(obj, path) {
 	let cur = obj;
-	for (const key of path$1) {
+	for (const key of path) {
 		if (cur === null || typeof cur !== "object") return void 0;
 		cur = cur[key];
 	}
@@ -430,8 +430,8 @@ function installHarnessSync(harness, mcpUrl, opts = {}) {
 		alreadyConfigured: false,
 		dryRun
 	};
-	const path$1 = resolveConfigPath(harness, env);
-	if (!path$1) return {
+	const path = resolveConfigPath(harness, env);
+	if (!path) return {
 		ok: false,
 		wrote: false,
 		path: "",
@@ -440,7 +440,7 @@ function installHarnessSync(harness, mcpUrl, opts = {}) {
 	};
 	const entryValue = buildServerEntry(harness, mcpUrl)[SERVER_NAME];
 	const modPath = [harness.serverPropertyName, SERVER_NAME];
-	const existing = readTextOrNull(path$1);
+	const existing = readTextOrNull(path);
 	const baseText = existing && existing.trim() ? existing : "{}";
 	const current = getAtPath(parse(baseText), modPath);
 	const alreadyConfigured = current !== void 0 && sameValue(current, entryValue);
@@ -448,7 +448,7 @@ function installHarnessSync(harness, mcpUrl, opts = {}) {
 	if (alreadyConfigured) return {
 		ok: true,
 		wrote: false,
-		path: path$1,
+		path,
 		alreadyConfigured: true,
 		dryRun,
 		preview: nextText
@@ -456,18 +456,18 @@ function installHarnessSync(harness, mcpUrl, opts = {}) {
 	if (dryRun) return {
 		ok: true,
 		wrote: false,
-		path: path$1,
+		path,
 		alreadyConfigured: false,
 		dryRun: true,
 		preview: nextText
 	};
-	mkdirSync(dirname(path$1), { recursive: true });
+	mkdirSync(dirname(path), { recursive: true });
 	const finalText = nextText.endsWith("\n") ? nextText : `${nextText}\n`;
-	writeFileSync(path$1, finalText, "utf8");
+	writeFileSync(path, finalText, "utf8");
 	return {
 		ok: true,
 		wrote: true,
-		path: path$1,
+		path,
 		alreadyConfigured: false,
 		dryRun: false,
 		preview: finalText

package/dist/cli.js

@@ -1,10 +1,7 @@
 #!/usr/bin/env node
+import { COMPLETION_SHELLS } from "./completionHandler-O2G_WZLf.js";
 import { buildApplication, buildCommand, buildRouteMap, proposeCompletions, run, 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 {
@@ -41,9 +38,6 @@ var Logger = class {
 function buildContext(process$1) {
 	return {
 		process: process$1,
-		os,
-		fs,
-		path,
 		logger: new Logger({
 			verbose: false,
 			stdout: process$1.stdout,
@@ -52,6 +46,45 @@ function buildContext(process$1) {
 	};
 }
 
+//#endregion
+//#region src/commands/completion.ts
+const completionCommand = buildCommand({
+	docs: {
+		brief: "Print the shell completion script for bash or zsh",
+		fullDescription: `Prints a shell completion script to stdout. You decide where it goes —
+this command never edits your shell config.
+
+Load it for the current session:
+  eval "$(levr completion bash)"
+  eval "$(levr completion zsh)"
+
+Or persist it:
+  levr completion bash >> ~/.bashrc
+  levr completion zsh  >> ~/.zshrc
+  levr completion bash > /etc/bash_completion.d/levr   # system-wide
+
+The shell is detected from $SHELL when omitted; pass it explicitly in scripts
+or when generating a script for a shell other than the one you are running.`
+	},
+	parameters: {
+		positional: {
+			kind: "tuple",
+			parameters: [{
+				parse: String,
+				proposeCompletions: (partial) => COMPLETION_SHELLS.filter((shell) => shell.startsWith(partial)),
+				brief: `Shell to emit (${COMPLETION_SHELLS.join("|")}); detected from $SHELL if omitted`,
+				placeholder: "shell",
+				optional: true
+			}]
+		},
+		flags: {}
+	},
+	loader: async () => {
+		const { completionHandler } = await import("./completionHandler-DtG_CsK0.js");
+		return completionHandler;
+	}
+});
+
 //#endregion
 //#region src/commands/mcp/add.ts
 const mcpAddCommand = buildCommand({
@@ -109,7 +142,7 @@ Examples:
 		aliases: { y: "yes" }
 	},
 	loader: async () => {
-		const { mcpAddHandler } = await import("./addHandler-boWTd9yY.js");
+		const { mcpAddHandler } = await import("./addHandler-K2a4rVv8.js");
 		return mcpAddHandler;
 	}
 });
@@ -147,7 +180,7 @@ Examples:
 		aliases: { d: "device-code" }
 	},
 	loader: async () => {
-		const { loginHandler } = await import("./loginHandler-Dfg89AD2.js");
+		const { loginHandler } = await import("./loginHandler-BhvCWTd8.js");
 		return loginHandler;
 	}
 });
@@ -166,7 +199,7 @@ Examples:
 	},
 	parameters: {},
 	loader: async () => {
-		const { logoutHandler } = await import("./logoutHandler-BC8laIAB.js");
+		const { logoutHandler } = await import("./logoutHandler-BFutKash.js");
 		return logoutHandler;
 	}
 });
@@ -186,7 +219,7 @@ Examples:
 	},
 	parameters: {},
 	loader: async () => {
-		const { statusHandler } = await import("./statusHandler-DljfUcC2.js");
+		const { statusHandler } = await import("./statusHandler-B6XRPg4k.js");
 		return statusHandler;
 	}
 });
@@ -297,11 +330,123 @@ Examples:
 		}
 	},
 	loader: async () => {
-		const { pushHandler } = await import("./pushHandler-CC709aNJ.js");
+		const { pushHandler } = await import("./pushHandler-v4-lHK6A.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-D27Xrx73.js");
+		return importHandler;
+	}
+});
+
 //#endregion
 //#region src/commands/workspace/list.ts
 const listCommand = buildCommand({
@@ -318,7 +463,7 @@ Examples:
 	},
 	parameters: {},
 	loader: async () => {
-		const { listHandler } = await import("./listHandler-7DZhE8jn.js");
+		const { listHandler } = await import("./listHandler-8uqFClxw.js");
 		return listHandler;
 	}
 });
@@ -351,7 +496,7 @@ Examples:
 		flags: {}
 	},
 	loader: async () => {
-		const { selectHandler } = await import("./selectHandler-nOUsPW9p.js");
+		const { selectHandler } = await import("./selectHandler-DeEZe6PU.js");
 		return selectHandler;
 	}
 });
@@ -368,14 +513,14 @@ Examples:
 	},
 	parameters: {},
 	loader: async () => {
-		const { currentHandler } = await import("./currentHandler-Bm7GFMkj.js");
+		const { currentHandler } = await import("./currentHandler-CHydiFui.js");
 		return currentHandler;
 	}
 });
 
 //#endregion
 //#region package.json
-var version = "0.3.1";
+var version = "0.5.0";
 
 //#endregion
 //#region src/app.ts
@@ -404,16 +549,10 @@ const routes = buildRouteMap({
 		auth: authRoutes,
 		workspace: workspaceRoutes,
 		push: pushCommand,
-		install: buildInstallCommand("levr", { bash: "levr __complete" }),
-		uninstall: buildUninstallCommand("levr", { bash: true })
+		import: importCommand,
+		completion: completionCommand
 	},
-	docs: {
-		brief: "The command-line interface for Levr",
-		hideRoute: {
-			install: true,
-			uninstall: true
-		}
-	}
+	docs: { brief: "The command-line interface for Levr" }
 });
 const app = buildApplication(routes, {
 	name: "levr",
@@ -432,10 +571,13 @@ const app = buildApplication(routes, {
 //#region src/completion.ts
 /**
 * Compute shell tab-completion suggestions for the hidden `__complete` entrypoint
-* (see src/bin/cli.ts). `levr install` registers a bash function that invokes
-* `levr __complete <COMP_LINE>` on each TAB, so `rawArgs` (process.argv.slice(2))
-* is `['__complete', <targetCommandName>, ...wordsBeingCompleted]`. A COMP_LINE
-* ending in a space means the cursor is on a fresh (empty) word to complete.
+* (see src/bin/cli.ts). The scripts emitted by `levr completion bash|zsh`
+* register a shell function that invokes `levr __complete <words…>` on each TAB,
+* so `rawArgs` (process.argv.slice(2)) is
+* `['__complete', <targetCommandName>, ...wordsBeingCompleted]` — note the
+* command name is passed through and dropped here, which is why the shell
+* scripts pass their FULL word array. A COMP_LINE ending in a space means the
+* cursor is on a fresh (empty) word to complete.
 *
 * Never throws — completion must not surface an error to the user's shell.
 */

package/dist/completionHandler-DtG_CsK0.js

@@ -0,0 +1,3 @@
+import { COMPLETION_SHELLS, completionHandler, completionScript, detectShell, isCompletionShell } from "./completionHandler-O2G_WZLf.js";
+
+export { completionHandler };

package/dist/completionHandler-O2G_WZLf.js

@@ -0,0 +1,95 @@
+//#region src/commands/completionHandler.ts
+const COMPLETION_SHELLS = ["bash", "zsh"];
+function isCompletionShell(value) {
+	return COMPLETION_SHELLS.includes(value);
+}
+/**
+* Best-effort shell detection from `$SHELL`. Matches on the basename so login
+* shells (`-bash`) and non-standard prefixes (`/usr/local/bin/zsh`) still
+* resolve. Returns undefined when the shell is unset or unsupported — the
+* caller must then fail loudly rather than guess.
+*/
+function detectShell(shellPath) {
+	const name = shellPath?.split("/").pop() ?? "";
+	if (name.includes("zsh")) return "zsh";
+	if (name.includes("bash")) return "bash";
+}
+const BASH_SCRIPT = `# levr bash completion.
+# Load it from ~/.bashrc:  eval "$(levr completion bash)"
+__levr_complete() {
+  export COMP_LINE
+  local -a words=( "\${COMP_WORDS[@]}" )
+  # Drop a trailing empty word. COMP_LINE's trailing space is already the
+  # signal that the cursor is on a fresh word; passing the empty word too
+  # would make __complete see it twice and match nothing. Harmless when the
+  # last word is non-empty, so this is correct however bash populates
+  # COMP_WORDS.
+  if [[ \${#words[@]} -gt 0 && -z "\${words[\${#words[@]}-1]}" ]]; then
+    words=( "\${words[@]:0:\${#words[@]}-1}" )
+  fi
+  COMPREPLY=( $(levr __complete "\${words[@]}") )
+  return 0
+}
+complete -o default -o nospace -F __levr_complete levr
+`;
+const ZSH_SCRIPT = `# levr zsh completion.
+# Load it from ~/.zshrc, AFTER your compinit call:
+#   autoload -Uz compinit && compinit
+#   eval "$(levr completion zsh)"
+_levr_complete() {
+  local -a candidates args
+  local raw
+  local comp_line="\${(j: :)words}"
+
+  args=("\${(@)words}")
+  if [[ -z "\${args[-1]}" ]]; then
+    args=("\${(@)args[1,-2]}")
+  fi
+
+  # Return before splitting when there is nothing to offer, so compadd is
+  # never reached with an empty candidate list.
+  raw="$(COMP_LINE="$comp_line" levr __complete "\${args[@]}" 2>/dev/null)"
+  [[ -n "$raw" ]] || return
+
+  candidates=(\${(f)raw})
+  # -S '' matches bash's \`complete -o nospace\`: no space is appended after a
+  # unique match, so subcommands can be chained without deleting one.
+  compadd -S '' -- "\${candidates[@]}"
+}
+
+# compdef only exists once compinit has run. Without this guard a .zshrc that
+# eval's this before compinit dies with a bare "command not found: compdef" on
+# every new shell; the explicit message says what to actually do.
+if (( $+functions[compdef] )); then
+  compdef _levr_complete levr
+else
+  print -u2 "levr: completion not registered — run \\\`autoload -Uz compinit && compinit\\\` before loading it."
+fi
+`;
+function completionScript(shell) {
+	return shell === "zsh" ? ZSH_SCRIPT : BASH_SCRIPT;
+}
+/**
+* Print the completion script for `shell` (or the detected shell) to stdout.
+*
+* stdout carries the script and NOTHING else, so `eval "$(levr completion zsh)"`
+* is safe; diagnostics go to stderr and set a non-zero exit code. The command
+* never writes to the filesystem — wiring it up is the user's call (ENG-2702).
+*/
+function completionHandler(_flags, shell) {
+	const requested = shell === void 0 ? detectShell(this.process.env["SHELL"]) : shell;
+	if (requested === void 0) {
+		this.process.stderr.write(`Could not detect your shell from \$SHELL. Pass one explicitly: levr completion <${COMPLETION_SHELLS.join("|")}>\n`);
+		this.process.exitCode = 1;
+		return;
+	}
+	if (!isCompletionShell(requested)) {
+		this.process.stderr.write(`Unsupported shell "${requested}". Supported shells: ${COMPLETION_SHELLS.join(", ")}.\n`);
+		this.process.exitCode = 1;
+		return;
+	}
+	this.process.stdout.write(completionScript(requested));
+}
+
+//#endregion
+export { COMPLETION_SHELLS, completionHandler, completionScript, detectShell, isCompletionShell };

package/dist/{currentHandler-Bm7GFMkj.js → currentHandler-CHydiFui.js}

@@ -1,4 +1,4 @@
-import { loadWorkspace } from "./workspace-store-4hfvsEHS.js";
+import { loadWorkspace } from "./workspace-store-DDOxnut1.js";
 
 //#region src/commands/workspace/currentHandler.ts
 function currentHandler() {

package/dist/{env-NxtzJJPk.js → env-CHeKHu5S.js}

@@ -1,6 +1,6 @@
 import { mkdirSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
-import { homedir } from "node:os";
 import { dirname, join } from "node:path";
+import { homedir } from "node:os";
 
 //#region src/auth/credentials.ts
 const CREDENTIALS_PATH = join(join(homedir(), ".config", "levr"), "credentials.json");