@connxio/cli 0.1.3 → 0.1.5

package/README.md

@@ -0,0 +1,280 @@
+# Connxio CLI
+
+Connxio CLI provides the `connxio` command and an MCP server for Connxio management APIs.
+
+The current implementation focuses on MCP usage through:
+
+```bash
+connxio mcp serve
+```
+
+## Prerequisites
+
+- Node.js 24 or newer
+- Connxio OAuth client credentials
+- A Connxio subscription-scoped API key for each subscription context you want to use
+
+## Install
+
+Install the CLI globally from npm:
+
+```bash
+npm i -g @connxio/cli
+```
+
+Verify installation:
+
+```bash
+connxio --help
+```
+
+## Configure OAuth
+
+```bash
+connxio auth configure
+```
+
+You will be prompted for:
+
+- OAuth client id
+- OAuth scope, defaulting to `api://connxio/.default`
+- OAuth client secret
+
+Check status:
+
+```bash
+connxio auth status
+```
+
+Clear OAuth configuration:
+
+```bash
+connxio auth clear
+```
+
+You can also configure OAuth with environment variables:
+
+```bash
+CONNXIO_OAUTH_CLIENT_ID="<client-id>"
+CONNXIO_OAUTH_CLIENT_SECRET="<client-secret>"
+CONNXIO_OAUTH_TOKEN_URL="https://api.connxio.com/oauth/token"
+CONNXIO_OAUTH_SCOPE="api://connxio/.default"
+```
+
+`CONNXIO_OAUTH_TOKEN_URL` and `CONNXIO_OAUTH_SCOPE` are optional overrides.
+
+## Configure Contexts
+
+A context represents one Connxio subscription. Connxio API keys are subscription-scoped, so add one context for each subscription you want to use.
+
+```bash
+connxio context add
+```
+
+The CLI calls `/v2/subscriptions/current` with the provided API key and stores the subscription/company metadata locally. API keys are stored through the credential abstraction, not in `config.json`.
+
+List contexts:
+
+```bash
+connxio context list
+```
+
+Set a default context:
+
+```bash
+connxio context default <context-id>
+```
+
+Remove a context:
+
+```bash
+connxio context remove <context-id>
+```
+
+## Register With VS Code
+
+VS Code 1.99+ supports MCP servers natively via GitHub Copilot agent mode.
+
+**Option 1 — user settings (all projects)**
+
+Open the command palette (`Ctrl+Shift+P`/`Cmd+Shift+P`) and select `MCP: Add server`.
+
+Select `stdio` transport, `connxio mcp serve` as the command, and set the name to `connxio`. This will create a user-level MCP server registration that is available in all projects.
+
+Alternatively, edit the user level mcp.json config file directly. Open the command palette and select `MCP: Open User Configuration`, then add:
+
+```json
+{
+  "servers": {
+    "connxio": {
+      "type": "stdio",
+      "command": "connxio",
+      "args": ["mcp", "serve"]
+    }
+  }
+}
+```
+
+**Option 2 — workspace settings (this project only)**
+
+Create `.vscode/mcp.json` in your project root:
+
+```json
+{
+  "servers": {
+    "connxio": {
+      "type": "stdio",
+      "command": "connxio",
+      "args": ["mcp", "serve"]
+    }
+  }
+}
+```
+
+The Connxio MCP server will now be available when you open this project in VS Code.
+
+If you need to pass environment variables (e.g. for OAuth or a custom API base URL), add an `env` block:
+
+```json
+{
+  "servers": {
+    "connxio": {
+      "type": "stdio",
+      "command": "connxio",
+      "args": ["mcp", "serve"],
+      "env": {
+        "CONNXIO_OAUTH_CLIENT_ID": "<client-id>",
+        "CONNXIO_OAUTH_CLIENT_SECRET": "<client-secret>"
+      }
+    }
+  }
+}
+```
+
+Do not commit files containing OAuth client secrets to source control.
+
+## Register With Claude Code
+
+Register the installed MCP server:
+
+```bash
+claude mcp add --transport stdio connxio -- connxio mcp serve
+```
+
+To register the MCP server at user level (available in all projects), add `--scope user`:
+
+```bash
+claude mcp add --scope user --transport stdio connxio -- connxio mcp serve
+```
+
+Verify registration:
+
+```bash
+claude mcp list
+```
+
+If you need to replace an existing registration:
+
+```bash
+claude mcp remove connxio
+claude mcp add --transport stdio connxio -- connxio mcp serve
+```
+
+## API Base URL
+
+The default API base URL is:
+
+```text
+https://api.connxio.com
+```
+
+Override it per context:
+
+```bash
+connxio context add --base-url http://localhost:5119/api
+```
+
+Or with an environment variable:
+
+```bash
+CONNXIO_API_BASE_URL="http://localhost:5119/api"
+```
+
+For localhost development with self-signed HTTPS certificates, the CLI automatically allows insecure TLS for localhost URLs. For other local development endpoints, use:
+
+```bash
+CONNXIO_INSECURE_TLS=true
+```
+
+Do not use insecure TLS settings in production.
+
+## Run Diagnostics
+
+```bash
+connxio mcp doctor
+```
+
+For HTTP troubleshooting, enable redacted request diagnostics:
+
+```bash
+CONNXIO_DEBUG_HTTP=true connxio mcp doctor
+```
+
+## MCP Tools
+
+The MCP server exposes non-message Connxio v2 management operations.
+
+Context and subscription tools:
+
+- `list_contexts`
+- `get_current_context`
+- `list_subscriptions`
+- `get_current_subscription`
+
+Integration tools:
+
+- `list_integrations`
+- `get_integration`
+- `create_integration`
+- `create_integration_no_validation`
+- `update_integration`
+- `delete_integration`
+
+Code component tools:
+
+- `list_code_components`
+- `get_code_component`
+- `get_code_component_versions`
+- `create_code_component`
+- `deprecate_code_component`
+- `rename_code_component`
+- `delete_code_component`
+
+Environment variable tools:
+
+- `list_environment_variables`
+- `get_environment_variable`
+- `create_environment_variable`
+- `delete_environment_variable`
+
+Security configuration tools:
+
+- `list_security_configs`
+- `get_security_config`
+- `create_security_config`
+- `delete_security_config`
+
+Write tools require `contextId`. Destructive tools require `contextId` and `confirm: true`.
+
+`/messages` operations are intentionally not exposed yet.
+
+## Local Config Files
+
+Non-secret config is stored in:
+
+- macOS/Linux: `${XDG_CONFIG_HOME:-~/.config}/connxio/config.json`
+- Windows: `%APPDATA%\connxio\config.json`
+
+Secrets are stored through the CLI credential abstraction. The CLI now uses the OS keyring when available and falls back to `${XDG_CONFIG_HOME:-~/.config}/connxio/credentials.json` on macOS/Linux or `%APPDATA%\connxio\credentials.json` on Windows when secure storage is unavailable.
+
+If you already have secrets in `credentials.json`, the CLI migrates them into the OS keyring lazily as they are used and removes the legacy file entries after a successful migration.

package/dist/index.mjs

@@ -11222,7 +11222,7 @@ function updateNotifier(options) {
 //#endregion
 //#region packages/cli/package.json
 var name = "@connxio/cli";
-var version$1 = "0.1.3";
+var version$1 = "0.1.5";
 var package_default = {
 	name,
 	version: version$1,
@@ -11246,8 +11246,13 @@ var package_default = {
 	types: "./dist/index.d.mts",
 	exports: { ".": "./dist/index.mjs" },
 	publishConfig: { "access": "public" },
+	scripts: {
+		"prepack": "cp ../../README.md ./README.md",
+		"postpack": "rm -f ./README.md"
+	},
 	dependencies: {
 		"@modelcontextprotocol/sdk": "^1.29.0",
+		"@napi-rs/keyring": "^1.3.0",
 		"commander": "^14.0.3",
 		"update-notifier": "^7.3.1",
 		"yazl": "^3.3.1",
@@ -11333,51 +11338,157 @@ function isNodeError$1(error) {
 }
 //#endregion
 //#region packages/cli/src/connxio/credentials.ts
-function getCredentialStoreDescription() {
-	return `local file (${getCredentialPath()})`;
+const KEYRING_SERVICE_NAME = "com.connxio.cli";
+let credentialBackendPromise;
+let fileFallbackWarningEmitted = false;
+async function getCredentialStoreDescription() {
+	return (await getCredentialBackend()).description;
 }
 async function deleteApiKey(ref) {
-	const store = await readCredentialFile();
-	delete store.apiKeys[ref];
-	await writeCredentialFile(store);
+	await deleteCredential("apiKey", ref);
 }
 async function deleteOAuthClientSecret(ref) {
-	const store = await readCredentialFile();
-	delete store.oauthClientSecrets[ref];
-	await writeCredentialFile(store);
+	await deleteCredential("oauthClientSecret", ref);
 }
 async function getApiKey(ref) {
-	const apiKey = (await readCredentialFile()).apiKeys[ref];
-	if (!apiKey) throw new Error(`Missing credential for context ${ref}. Run \`connxio context add ${ref}\`.`);
-	return apiKey;
+	return getCredential("apiKey", ref);
 }
 async function getOAuthClientSecret(ref) {
-	const clientSecret = (await readCredentialFile()).oauthClientSecrets[ref];
-	if (!clientSecret) throw new Error("Missing OAuth client secret. Run `connxio auth configure`.");
-	return clientSecret;
+	return getCredential("oauthClientSecret", ref);
 }
 async function hasApiKey(ref) {
-	const store = await readCredentialFile();
-	return typeof store.apiKeys[ref] === "string" && store.apiKeys[ref].length > 0;
+	return hasCredential("apiKey", ref);
 }
 async function hasOAuthClientSecret(ref) {
-	const store = await readCredentialFile();
-	return typeof store.oauthClientSecrets[ref] === "string" && store.oauthClientSecrets[ref].length > 0;
+	return hasCredential("oauthClientSecret", ref);
 }
 async function setApiKey(ref, apiKey) {
-	const trimmed = apiKey.trim();
-	if (!trimmed) throw new Error("API key cannot be empty.");
-	const store = await readCredentialFile();
-	store.apiKeys[ref] = trimmed;
-	await writeCredentialFile(store);
+	await setCredential("apiKey", ref, apiKey);
 }
 async function setOAuthClientSecret(ref, clientSecret) {
-	const trimmed = clientSecret.trim();
-	if (!trimmed) throw new Error("OAuth client secret cannot be empty.");
-	const store = await readCredentialFile();
-	store.oauthClientSecrets[ref] = trimmed;
-	await writeCredentialFile(store);
+	await setCredential("oauthClientSecret", ref, clientSecret);
+}
+async function deleteCredential(kind, ref) {
+	const backend = await getCredentialBackend();
+	await backend.delete(kind, ref);
+	if (backend.type === "keyring") await deleteLegacyCredentialQuietly(kind, ref);
+}
+async function getCredential(kind, ref) {
+	const backend = await getCredentialBackend();
+	const credential = await backend.get(kind, ref);
+	if (credential) return credential;
+	if (backend.type === "keyring") {
+		const legacyCredential = await fileCredentialBackend.get(kind, ref);
+		if (legacyCredential) {
+			await backend.set(kind, ref, legacyCredential);
+			await deleteLegacyCredentialQuietly(kind, ref);
+			return legacyCredential;
+		}
+	}
+	throw new Error(getMissingCredentialMessage(kind, ref));
+}
+async function getCredentialBackend() {
+	credentialBackendPromise ??= resolveCredentialBackend();
+	return credentialBackendPromise;
+}
+function getCredentialFileKey(kind) {
+	return kind === "apiKey" ? "apiKeys" : "oauthClientSecrets";
+}
+function getKeyringAccountName(kind, ref) {
+	return kind === "apiKey" ? `api-key:${ref}` : `oauth-client-secret:${ref}`;
+}
+function getMissingCredentialMessage(kind, ref) {
+	return kind === "apiKey" ? `Missing credential for context ${ref}. Run \`connxio context add ${ref}\`.` : "Missing OAuth client secret. Run `connxio auth configure`.";
+}
+async function hasCredential(kind, ref) {
+	const backend = await getCredentialBackend();
+	if (await backend.has(kind, ref)) return true;
+	return backend.type === "keyring" ? fileCredentialBackend.has(kind, ref) : false;
+}
+function normalizeKeyringModule(value) {
+	const candidate = isRecord$3(value) ? value : void 0;
+	const defaultCandidate = candidate && Object.prototype.hasOwnProperty.call(candidate, "default") && isRecord$3(candidate["default"]) ? candidate["default"] : void 0;
+	const normalizedCandidate = defaultCandidate ? {
+		...defaultCandidate,
+		...candidate
+	} : candidate;
+	if (!normalizedCandidate || typeof normalizedCandidate.AsyncEntry !== "function" || typeof normalizedCandidate.findCredentialsAsync !== "function") throw new Error("@napi-rs/keyring did not expose the expected API.");
+	return {
+		AsyncEntry: normalizedCandidate.AsyncEntry,
+		findCredentialsAsync: normalizedCandidate.findCredentialsAsync
+	};
+}
+async function resolveCredentialBackend() {
+	try {
+		const keyring = normalizeKeyringModule(await import("@napi-rs/keyring"));
+		await keyring.findCredentialsAsync(KEYRING_SERVICE_NAME);
+		return createKeyringCredentialBackend(keyring);
+	} catch (error) {
+		warnFileFallback(error);
+		return fileCredentialBackend;
+	}
 }
+async function setCredential(kind, ref, value) {
+	const trimmed = value.trim();
+	if (!trimmed) throw new Error(kind === "apiKey" ? "API key cannot be empty." : "OAuth client secret cannot be empty.");
+	const backend = await getCredentialBackend();
+	await backend.set(kind, ref, trimmed);
+	if (backend.type === "keyring") await deleteLegacyCredentialQuietly(kind, ref);
+}
+function warnFileFallback(error) {
+	if (fileFallbackWarningEmitted) return;
+	fileFallbackWarningEmitted = true;
+	console.warn(`Connxio secure credential storage unavailable; falling back to local file storage at ${getCredentialPath()}: ${formatError$4(error)}`);
+}
+async function deleteLegacyCredentialQuietly(kind, ref) {
+	try {
+		await fileCredentialBackend.delete(kind, ref);
+	} catch {}
+}
+function createKeyringCredentialBackend(keyring) {
+	const get = async (kind, ref) => {
+		const credential = await new keyring.AsyncEntry(KEYRING_SERVICE_NAME, getKeyringAccountName(kind, ref)).getPassword();
+		return typeof credential === "string" && credential.length > 0 ? credential : void 0;
+	};
+	return {
+		description: "OS keyring",
+		type: "keyring",
+		async delete(kind, ref) {
+			const entry = new keyring.AsyncEntry(KEYRING_SERVICE_NAME, getKeyringAccountName(kind, ref));
+			if (await get(kind, ref) === void 0) return;
+			await entry.deleteCredential();
+		},
+		get,
+		async has(kind, ref) {
+			return await get(kind, ref) !== void 0;
+		},
+		async set(kind, ref, value) {
+			await new keyring.AsyncEntry(KEYRING_SERVICE_NAME, getKeyringAccountName(kind, ref)).setPassword(value);
+		}
+	};
+}
+const fileCredentialBackend = {
+	description: `local file (${getCredentialPath()})`,
+	type: "file",
+	async delete(kind, ref) {
+		const store = await readCredentialFile();
+		delete store[getCredentialFileKey(kind)][ref];
+		await writeCredentialFile(store);
+	},
+	async get(kind, ref) {
+		const credential = (await readCredentialFile())[getCredentialFileKey(kind)][ref];
+		return typeof credential === "string" && credential.length > 0 ? credential : void 0;
+	},
+	async has(kind, ref) {
+		const credential = (await readCredentialFile())[getCredentialFileKey(kind)][ref];
+		return typeof credential === "string" && credential.length > 0;
+	},
+	async set(kind, ref, value) {
+		const store = await readCredentialFile();
+		store[getCredentialFileKey(kind)][ref] = value;
+		await writeCredentialFile(store);
+	}
+};
 function getCredentialPath() {
 	return path.join(getConfigDir(), "credentials.json");
 }
@@ -11429,6 +11540,9 @@ function isStringRecord(value) {
 function isNodeError(error) {
 	return error instanceof Error && "code" in error;
 }
+function formatError$4(error) {
+	return error instanceof Error ? error.message : String(error);
+}
 //#endregion
 //#region packages/cli/src/connxio/http.ts
 function allowInsecureTlsIfLocal(url) {
@@ -33183,7 +33297,7 @@ function registerMcpCommands(program) {
 		const oauth = await getOAuthStatus();
 		const problems = [];
 		console.log(`Config: ${getConfigPath()}`);
-		console.log(`Credential store: ${getCredentialStoreDescription()}`);
+		console.log(`Credential store: ${await getCredentialStoreDescription()}`);
 		if (!oauth.configured) problems.push("OAuth is not configured. Run `connxio auth configure`.");
 		else if (!oauth.hasClientSecret) problems.push("OAuth client secret is missing. Run `connxio auth configure`.");
 		if (contexts.length === 0) problems.push("No contexts configured. Run `connxio context add`.");