@levr-one/cli 0.3.0 → 0.3.1

package/README.md

@@ -1,8 +1,13 @@
 # @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 two 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.
 
 ## Install
 
@@ -15,82 +20,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
-```
-
-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:
-
-```bash
-npx @levr-one/cli mcp add    # detect installed clients and pick interactively
-```
-
-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)
+## Quick start
 
-Tab-completion is an explicit opt-in step (it is not installed automatically):
+**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
-levr install       # add shell completion for the current shell
-levr uninstall     # remove it
+npx @levr-one/cli mcp add
 ```
 
-## Authentication
-
-The CLI supports three authentication modes.
-
-### Interactive (browser) — default
+**Pushing test results?** Authentication is all you need — log in once (or
+set `LEVR_TOKEN` in CI):
 
 ```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)
+**Supported clients:**
 
-Set the `LEVR_TOKEN` environment variable and the CLI uses it automatically —
-no interactive login:
+| 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)                                   |
 
-```bash
-export LEVR_TOKEN=<your-personal-access-token>
-levr push ./results.xml
-```
-
-### 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
 
@@ -168,6 +159,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 +229,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

@@ -147,7 +147,7 @@ Examples:
 		aliases: { d: "device-code" }
 	},
 	loader: async () => {
-		const { loginHandler } = await import("./loginHandler-BfIUQJrC.js");
+		const { loginHandler } = await import("./loginHandler-Dfg89AD2.js");
 		return loginHandler;
 	}
 });
@@ -186,7 +186,7 @@ Examples:
 	},
 	parameters: {},
 	loader: async () => {
-		const { statusHandler } = await import("./statusHandler-BaQB40t7.js");
+		const { statusHandler } = await import("./statusHandler-DljfUcC2.js");
 		return statusHandler;
 	}
 });
@@ -297,7 +297,7 @@ Examples:
 		}
 	},
 	loader: async () => {
-		const { pushHandler } = await import("./pushHandler-DBBa6hKz.js");
+		const { pushHandler } = await import("./pushHandler-CC709aNJ.js");
 		return pushHandler;
 	}
 });
@@ -318,7 +318,7 @@ Examples:
 	},
 	parameters: {},
 	loader: async () => {
-		const { listHandler } = await import("./listHandler-EsB3AeOB.js");
+		const { listHandler } = await import("./listHandler-7DZhE8jn.js");
 		return listHandler;
 	}
 });
@@ -351,7 +351,7 @@ Examples:
 		flags: {}
 	},
 	loader: async () => {
-		const { selectHandler } = await import("./selectHandler-XOUHdyea.js");
+		const { selectHandler } = await import("./selectHandler-nOUsPW9p.js");
 		return selectHandler;
 	}
 });
@@ -375,7 +375,7 @@ Examples:
 
 //#endregion
 //#region package.json
-var version = "0.3.0";
+var version = "0.3.1";
 
 //#endregion
 //#region src/app.ts

package/dist/{listHandler-EsB3AeOB.js → listHandler-7DZhE8jn.js}

@@ -1,5 +1,5 @@
 import "./env-NxtzJJPk.js";
-import { authGetSitesV1, configureClient } from "./sdk-client-BeE6mXns.js";
+import { authGetSitesV1, configureClient } from "./sdk-client-BWrIbeUg.js";
 import { loadWorkspace } from "./workspace-store-4hfvsEHS.js";
 import "./token-refresh-Cz-FqDtC.js";
 import { resolveToken } from "./resolve-token-BRPrqdG-.js";

package/dist/{loginHandler-BfIUQJrC.js → loginHandler-Dfg89AD2.js}

@@ -1,7 +1,7 @@
 import { CLI_CLIENT_ID, getApiUrl, getAuthUrl, setSessionApiUrl, writeCredentials } from "./env-NxtzJJPk.js";
-import { configureClient } from "./sdk-client-BeE6mXns.js";
+import { configureClient } from "./sdk-client-BWrIbeUg.js";
 import "./workspace-store-4hfvsEHS.js";
-import { autoSelectWorkspace } from "./resolve-workspace-Dj7jgtE3.js";
+import { autoSelectWorkspace } from "./resolve-workspace-vJZku4FK.js";
 import chalk from "chalk";
 import { createHash, randomBytes } from "node:crypto";
 import { createServer } from "node:http";

package/dist/{pushHandler-DBBa6hKz.js → pushHandler-CC709aNJ.js}

@@ -1,7 +1,7 @@
 import { getApiUrl, getAutomationSourceIdOverride, getSourceOverride, getTeamId } from "./env-NxtzJJPk.js";
-import { client, configureClient, uploadAutomationIngest, uploadImport } from "./sdk-client-BeE6mXns.js";
+import { client, configureClient, uploadAutomationIngest, uploadImport } from "./sdk-client-BWrIbeUg.js";
 import "./workspace-store-4hfvsEHS.js";
-import { resolveWorkspace } from "./resolve-workspace-Dj7jgtE3.js";
+import { resolveWorkspace } from "./resolve-workspace-vJZku4FK.js";
 import "./token-refresh-Cz-FqDtC.js";
 import { resolveToken } from "./resolve-token-BRPrqdG-.js";
 import { readFileSync, statSync } from "node:fs";

package/dist/{resolve-workspace-Dj7jgtE3.js → resolve-workspace-vJZku4FK.js}

@@ -1,4 +1,4 @@
-import { authGetSitesV1 } from "./sdk-client-BeE6mXns.js";
+import { authGetSitesV1 } from "./sdk-client-BWrIbeUg.js";
 import { clearWorkspace, loadWorkspace, saveWorkspace } from "./workspace-store-4hfvsEHS.js";
 
 //#region src/workspace/resolve-workspace.ts

package/dist/{sdk-client-BeE6mXns.js → sdk-client-BWrIbeUg.js}

@@ -14060,6 +14060,11 @@ const zCreateGithubIssueLinkDto = z.object({
 	sync_direction: z.string().optional().describe(""),
 	origin: z.string().optional().describe(""),
 	role: z.string().optional().describe(""),
+	last_synced_fingerprint: z.string().nullable().optional().describe(""),
+	last_synced_origin: z.string().nullable().optional().describe(""),
+	last_synced_snapshot: z.unknown().optional().describe(""),
+	sync_status: z.string().optional().describe(""),
+	conflict_id: z.string().nullable().optional().describe(""),
 	tq_issue_id: z.string(),
 	github_repository_id: z.string(),
 	team_id: z.string()
@@ -14071,6 +14076,11 @@ const zResponseGithubIssueLinkDto = z.object({
 	sync_direction: z.string().optional().describe(""),
 	origin: z.string().optional().describe(""),
 	role: z.string().optional().describe(""),
+	last_synced_fingerprint: z.string().nullable().optional().describe(""),
+	last_synced_origin: z.string().nullable().optional().describe(""),
+	last_synced_snapshot: z.unknown().optional().describe(""),
+	sync_status: z.string().optional().describe(""),
+	conflict_id: z.string().nullable().optional().describe(""),
 	tq_issue_id: z.string(),
 	github_repository_id: z.string(),
 	team_id: z.string(),
@@ -14090,6 +14100,11 @@ const zUpdateGithubIssueLinkDto = z.object({
 	sync_direction: z.string().optional().describe(""),
 	origin: z.string().optional().describe(""),
 	role: z.string().optional().describe(""),
+	last_synced_fingerprint: z.string().nullable().optional().describe(""),
+	last_synced_origin: z.string().nullable().optional().describe(""),
+	last_synced_snapshot: z.unknown().optional().describe(""),
+	sync_status: z.string().optional().describe(""),
+	conflict_id: z.string().nullable().optional().describe(""),
 	tq_issue_id: z.string().optional(),
 	github_repository_id: z.string().optional(),
 	team_id: z.string().optional()
@@ -27227,7 +27242,6 @@ const zIngestRequestDto = z.object({
 	force_upsert: z.boolean().optional()
 });
 const zSyncGetLastSyncIdV1Data = z.object({ url: z.literal("/v1/sync/last-sync-id") });
-const zSyncResetSyncV1Data = z.object({ url: z.literal("/v1/sync/reset") });
 const zSyncBootstrapV1Data = z.object({
 	body: zBootstrapRequestDto,
 	url: z.literal("/v1/sync/bootstrap")

package/dist/{selectHandler-XOUHdyea.js → selectHandler-nOUsPW9p.js}

@@ -1,5 +1,5 @@
 import "./env-NxtzJJPk.js";
-import { authGetSitesV1, configureClient } from "./sdk-client-BeE6mXns.js";
+import { authGetSitesV1, configureClient } from "./sdk-client-BWrIbeUg.js";
 import { saveWorkspace } from "./workspace-store-4hfvsEHS.js";
 import "./token-refresh-Cz-FqDtC.js";
 import { resolveToken } from "./resolve-token-BRPrqdG-.js";

package/dist/{statusHandler-BaQB40t7.js → statusHandler-DljfUcC2.js}

@@ -1,5 +1,5 @@
 import { getApiUrl, getPatToken, readCredentials } from "./env-NxtzJJPk.js";
-import { authGetProfileV1, configureClient } from "./sdk-client-BeE6mXns.js";
+import { authGetProfileV1, configureClient } from "./sdk-client-BWrIbeUg.js";
 import { isTokenExpired } from "./token-refresh-Cz-FqDtC.js";
 import chalk from "chalk";
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@levr-one/cli",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "The command-line interface for Levr",
   "type": "module",
   "license": "MIT",