@elvix.is/sdk 0.3.2 → 0.4.0

package/README.md

@@ -126,7 +126,7 @@ elvix ships first-class agent support. Three surfaces:
      "mcpServers": {
        "elvix": {
          "command": "npx",
-         "args": ["-y", "-p", "@elvix.is/sdk", "elvix-mcp"],
+         "args": ["-y", "-p", "@elvix.is/sdk", "elvix", "mcp"],
          "env": { "ELVIX_API_KEY": "eak_..." }
        }
      }
@@ -135,6 +135,20 @@ elvix ships first-class agent support. Three surfaces:
 
    Read-only by default. `--admin` opts in to mutation tools. Never logs the bearer token.
 
+## CLI
+
+The package ships an `elvix` command:
+
+```bash
+# Diagnose an integration — base URL, clientId, verify endpoint, API key.
+ELVIX_CLIENT_ID=client_… npx -p @elvix.is/sdk elvix doctor
+
+# Launch the MCP server on stdio.
+ELVIX_API_KEY=eak_… npx -p @elvix.is/sdk elvix mcp
+```
+
+`elvix doctor` prints a green/red checklist so "why isn't elvix working" is a two-second answer. (`elvix-mcp` is kept as an alias for `elvix mcp`.)
+
 Full agent guide: <https://elvix.is/docs/agents>
 
 ## Components

package/dist/cli/doctor.d.ts

@@ -0,0 +1,21 @@
+/**
+ * `elvix doctor` — diagnose an elvix integration from the terminal.
+ *
+ * Runs a green/red checklist so a developer (or their agent) can
+ * answer "why isn't elvix working" in two seconds instead of a support
+ * email. Read-only; never mutates anything.
+ *
+ * Checks:
+ *   - base URL reachable (GET /llms.txt)
+ *   - clientId resolves (GET /api/v1/bootstrap/<clientId> → 200)
+ *   - verify endpoint live (POST /api/v1/verify with a dummy token → 401)
+ *   - ELVIX_API_KEY present (informational)
+ *
+ * Inputs (env or flags):
+ *   ELVIX_BASE_URL    default https://elvix.is        (--base-url=)
+ *   ELVIX_CLIENT_ID   the app's public clientId       (--client-id=)
+ *   ELVIX_API_KEY     server API key (presence only)
+ */
+declare function runDoctor(): Promise<number>;
+
+export { runDoctor };

package/dist/cli/doctor.js

@@ -0,0 +1,78 @@
+// src/cli/doctor.ts
+var DEFAULT_BASE_URL = "https://elvix.is";
+function flag(name) {
+  const hit = process.argv.find((a) => a.startsWith(`--${name}=`));
+  return hit?.split("=").slice(1).join("=");
+}
+async function timed(fn, timeoutMs = 8e3) {
+  const ctrl = new AbortController();
+  const t = setTimeout(() => ctrl.abort(), timeoutMs);
+  try {
+    return await fn();
+  } catch {
+    return null;
+  } finally {
+    clearTimeout(t);
+  }
+}
+async function runDoctor() {
+  const baseUrl = flag("base-url") ?? process.env.ELVIX_BASE_URL ?? DEFAULT_BASE_URL;
+  const clientId = flag("client-id") ?? process.env.ELVIX_CLIENT_ID;
+  const apiKey = process.env.ELVIX_API_KEY;
+  const checks = [];
+  const llms = await timed(() => fetch(`${baseUrl}/llms.txt`));
+  checks.push({
+    label: `Base URL reachable (${baseUrl})`,
+    ok: Boolean(llms?.ok),
+    detail: llms ? `HTTP ${llms.status}` : "no response / timeout"
+  });
+  if (clientId) {
+    const boot = await timed(
+      () => fetch(`${baseUrl}/api/v1/bootstrap/${encodeURIComponent(clientId)}`)
+    );
+    checks.push({
+      label: `clientId resolves (${clientId})`,
+      ok: Boolean(boot?.ok),
+      detail: boot ? boot.ok ? `HTTP ${boot.status}` : `HTTP ${boot.status} \u2014 wrong clientId, or app is draft/deleted` : "no response / timeout"
+    });
+  } else {
+    checks.push({
+      label: "clientId resolves",
+      ok: false,
+      detail: "skipped \u2014 pass --client-id=<id> or set ELVIX_CLIENT_ID"
+    });
+  }
+  const verify = await timed(
+    () => fetch(`${baseUrl}/api/v1/verify`, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ token: "doctor-probe" })
+    })
+  );
+  checks.push({
+    label: "Verify endpoint live (POST /api/v1/verify)",
+    ok: verify?.status === 401,
+    detail: verify ? `HTTP ${verify.status} (401 expected)` : "no response / timeout"
+  });
+  checks.push({
+    label: "ELVIX_API_KEY present",
+    ok: Boolean(apiKey),
+    detail: apiKey ? `set (${apiKey.slice(0, 8)}\u2026)` : "not set \u2014 server-side verify will fail"
+  });
+  let criticalFail = false;
+  process.stdout.write("\nelvix doctor\n\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n");
+  for (const c of checks) {
+    const mark = c.ok ? "\u2713" : "\u2717";
+    process.stdout.write(`  ${mark}  ${c.label}
+       ${c.detail}
+`);
+  }
+  if (!checks[0]?.ok || !checks[2]?.ok) criticalFail = true;
+  process.stdout.write(
+    criticalFail ? "\nResult: elvix is NOT reachable from here. Check network / base URL.\n" : "\nResult: elvix is reachable. Warnings above (if any) are config hints.\n"
+  );
+  return criticalFail ? 1 : 0;
+}
+export {
+  runDoctor
+};

package/dist/cli/index.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node

package/dist/cli/index.js

@@ -0,0 +1,61 @@
+#!/usr/bin/env node
+
+// src/cli/index.ts
+var HELP = `elvix \u2014 @elvix.is/sdk CLI
+
+Usage:
+  elvix mcp [--admin] [--base-url=<url>]
+      Launch the elvix MCP server on stdio. Reads ELVIX_API_KEY from
+      the environment. Read-only by default; --admin enables mutation
+      tools (the server still enforces the admin scope on the key).
+
+  elvix doctor [--client-id=<id>] [--base-url=<url>]
+      Diagnose an integration: base URL reachability, clientId
+      resolution, verify-endpoint liveness, API-key presence.
+      Reads ELVIX_CLIENT_ID / ELVIX_API_KEY / ELVIX_BASE_URL.
+
+  elvix help
+      Show this message.
+
+Docs: https://elvix.is/docs/agents`;
+async function main() {
+  const sub = process.argv[2];
+  switch (sub) {
+    case "mcp": {
+      const { createElvixMcpServer } = await import("../mcp/index.js");
+      const apiKey = process.env.ELVIX_API_KEY;
+      if (!apiKey) {
+        process.stderr.write("ELVIX_API_KEY environment variable is required.\n");
+        process.exit(1);
+      }
+      const admin = process.argv.includes("--admin");
+      const baseUrl = process.argv.find((a) => a.startsWith("--base-url="))?.split("=")[1];
+      const { connectStdio } = await createElvixMcpServer({ apiKey, readonly: !admin, baseUrl });
+      await connectStdio();
+      return;
+    }
+    case "doctor": {
+      const { runDoctor } = await import("./doctor.js");
+      process.exit(await runDoctor());
+      break;
+    }
+    case "help":
+    case "--help":
+    case "-h":
+    case void 0:
+      process.stdout.write(`${HELP}
+`);
+      return;
+    default:
+      process.stderr.write(`Unknown command: ${sub}
+
+${HELP}
+`);
+      process.exit(1);
+  }
+}
+main().catch((e) => {
+  process.stderr.write(`elvix: ${e instanceof Error ? e.message : String(e)}
+`);
+  process.exit(1);
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@elvix.is/sdk",
-  "version": "0.3.2",
+  "version": "0.4.0",
   "description": "Official elvix SDK. Drop-in React components, server helpers, and an MCP server so AI coding agents integrate elvix on the first try.",
   "license": "MIT",
   "homepage": "https://elvix.is",
@@ -21,6 +21,7 @@
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "bin": {
+    "elvix": "./dist/cli/index.js",
     "elvix-mcp": "./dist/mcp/bin.js"
   },
   "exports": {
@@ -47,7 +48,7 @@
   },
   "files": ["dist", "README.md", "LICENSE"],
   "scripts": {
-    "build": "tsup src/index.ts src/react.ts src/server.ts src/types.ts src/mcp/index.ts src/mcp/bin.ts --format esm --dts --clean --external react --external next",
+    "build": "tsup src/index.ts src/react.ts src/server.ts src/types.ts src/mcp/index.ts src/mcp/bin.ts src/cli/index.ts src/cli/doctor.ts --format esm --dts --clean --external react --external next",
     "typecheck": "tsc --noEmit",
     "test": "vitest run"
   },