@cluesmith/multisage 0.1.0

package/README.md

@@ -0,0 +1,90 @@
+# @multisage/cli
+
+Query [Multisage](https://multisage.ai) from your terminal. Get answers from a panel of AI experts (Claude, GPT, Gemini) with a single command.
+
+## Installation
+
+```bash
+npm install -g @multisage/cli
+```
+
+Or use without installing:
+
+```bash
+npx @multisage/cli "What's the best programming language for beginners?"
+```
+
+## Setup
+
+1. Create an API key at [multisage.ai/settings](https://multisage.ai/settings)
+2. Set the environment variable:
+
+```bash
+export MULTISAGE_API_KEY=msk_your_key_here
+```
+
+## Usage
+
+```bash
+# Ask a question
+multisage "React vs Vue for a new project?"
+
+# Get full expert details and stages
+multisage --full "Should I use TypeScript?"
+
+# Output as JSON (for scripting)
+multisage --json "Best laptop for developers?"
+
+# Full details as JSON
+multisage --json --full "React vs Vue?"
+
+# Pipe to a markdown renderer
+multisage "Explain async/await" | glow
+
+# Save to file
+multisage "Best practices for REST APIs" > advice.md
+
+# Use with a different server
+multisage --api-url https://staging.multisage.ai "test question"
+```
+
+## Options
+
+| Flag | Short | Description | Default |
+|------|-------|-------------|---------|
+| `--api-key <key>` | `-k` | API key (overrides env var) | `$MULTISAGE_API_KEY` |
+| `--api-url <url>` | `-u` | Base URL for API | `https://multisage.ai` |
+| `--full` | `-f` | Include expert details and all stages | `false` |
+| `--json` | `-j` | Output as structured JSON | `false` |
+| `--quiet` | `-q` | Suppress progress spinner | `false` |
+| `--version` | | Show version | |
+| `--help` | | Show help | |
+
+## Output Modes
+
+### Default (Markdown)
+Prints the synthesized answer as markdown to stdout.
+
+### Full (`--full`)
+Prints all stages: Quick Answer, Expert Responses (per expert), Synthesis, and Debate (if triggered).
+
+### JSON (`--json`)
+Outputs the API response as JSON to stdout. Combine with `--full` for the complete response schema.
+
+## Error Codes
+
+| Error | Message |
+|-------|---------|
+| Invalid API key | "Invalid API key. Check your key at: https://multisage.ai/settings" |
+| Insufficient credits | "Insufficient credits. Purchase more at: https://multisage.ai/settings" |
+| Rate limited | "Rate limit exceeded. Try again in N seconds." |
+| Concurrent limit | "Too many concurrent requests. Try again in a few seconds." |
+| Network error | "Could not connect to {url}." |
+| Timeout | "Request timed out after 300 seconds." |
+
+All errors exit with code 1. With `--json`, errors are also output as JSON to stdout for programmatic handling.
+
+## Requirements
+
+- Node.js 18 or later
+- A Multisage API key ([get one here](https://multisage.ai/settings))

package/dist/index.js

@@ -0,0 +1,321 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { Command } from "commander";
+import ora from "ora";
+
+// src/errors.ts
+var MultisageError = class extends Error {
+  constructor(message, code, exitCode = 1, rateLimitMeta) {
+    super(message);
+    this.code = code;
+    this.exitCode = exitCode;
+    this.name = "MultisageError";
+    this.rateLimitMeta = rateLimitMeta;
+  }
+  rateLimitMeta;
+};
+async function handleApiError(response) {
+  const status = response.status;
+  if (status === 404) {
+    return new MultisageError(
+      "API not available at this URL. Check --api-url or try https://multisage.ai",
+      "not_found"
+    );
+  }
+  let errorCode = "unknown";
+  let errorMessage = "";
+  try {
+    const body = await response.json();
+    errorCode = body?.error?.code || "unknown";
+    errorMessage = body?.error?.message || "";
+  } catch {
+  }
+  switch (status) {
+    case 400:
+      return new MultisageError(
+        `Invalid request: ${errorMessage || "Bad request"}`,
+        "invalid_request"
+      );
+    case 401:
+      return new MultisageError(
+        "Invalid API key. Check your key at: https://multisage.ai/settings",
+        "invalid_key"
+      );
+    case 402:
+      return new MultisageError(
+        "Insufficient credits. Purchase more at: https://multisage.ai/settings",
+        "insufficient_credits"
+      );
+    case 429: {
+      const retryAfter = response.headers.get("Retry-After");
+      const rateLimitMeta = {};
+      if (retryAfter) rateLimitMeta.retryAfter = parseInt(retryAfter, 10);
+      const limitHeader = response.headers.get("X-RateLimit-Limit");
+      if (limitHeader) rateLimitMeta.limit = parseInt(limitHeader, 10);
+      const remainingHeader = response.headers.get("X-RateLimit-Remaining");
+      if (remainingHeader) rateLimitMeta.remaining = parseInt(remainingHeader, 10);
+      const resetHeader = response.headers.get("X-RateLimit-Reset");
+      if (resetHeader) rateLimitMeta.reset = parseInt(resetHeader, 10);
+      if (errorCode === "concurrency_limited") {
+        return new MultisageError(
+          "Too many concurrent requests. Try again in a few seconds.",
+          "concurrency_limited",
+          1,
+          Object.keys(rateLimitMeta).length > 0 ? rateLimitMeta : void 0
+        );
+      } else {
+        const retryMsg = retryAfter ? `Rate limit exceeded. Try again in ${retryAfter} seconds.` : "Rate limit exceeded. Try again shortly.";
+        return new MultisageError(
+          retryMsg,
+          "rate_limited",
+          1,
+          Object.keys(rateLimitMeta).length > 0 ? rateLimitMeta : void 0
+        );
+      }
+    }
+    case 500:
+      return new MultisageError(
+        "Server error. Please try again later.",
+        "internal_error"
+      );
+    default:
+      return new MultisageError(
+        `Unexpected error (HTTP ${status}). Please try again later.`,
+        "unknown"
+      );
+  }
+}
+function networkError(url) {
+  return new MultisageError(
+    `Could not connect to ${url}. Check your internet connection and --api-url.`,
+    "network_error"
+  );
+}
+function timeoutError() {
+  return new MultisageError(
+    "Request timed out after 300 seconds. The server may be overloaded.",
+    "timeout"
+  );
+}
+function validateApiKey(key) {
+  if (!key) {
+    return "No API key provided. Set MULTISAGE_API_KEY or use --api-key.\nGet your key at: https://multisage.ai/settings";
+  }
+  if (!key.startsWith("msk_")) {
+    return 'Invalid API key format. Keys must start with "msk_".\nGet your key at: https://multisage.ai/settings';
+  }
+  return null;
+}
+function validateUrl(url) {
+  try {
+    const parsed = new URL(url);
+    const isLocalhost = parsed.hostname === "localhost" || parsed.hostname === "127.0.0.1";
+    if (parsed.protocol === "http:" && !isLocalhost) {
+      return "API URL must use HTTPS. Only localhost URLs are allowed over HTTP.";
+    }
+    return null;
+  } catch {
+    return `Invalid URL: ${url}`;
+  }
+}
+
+// src/client.ts
+async function queryMultisage(options) {
+  const url = `${options.apiUrl.replace(/\/$/, "")}/api/v1/query`;
+  const body = { question: options.question };
+  if (options.detail) {
+    body.detail = options.detail;
+  }
+  let response;
+  try {
+    response = await fetch(url, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "Authorization": `Bearer ${options.apiKey}`
+      },
+      body: JSON.stringify(body),
+      signal: AbortSignal.timeout(3e5)
+    });
+  } catch (err) {
+    if (err instanceof DOMException && err.name === "TimeoutError") {
+      throw timeoutError();
+    }
+    if (err instanceof TypeError) {
+      throw networkError(options.apiUrl);
+    }
+    throw new MultisageError(
+      `Unexpected error: ${err instanceof Error ? err.message : String(err)}`,
+      "unknown"
+    );
+  }
+  if (!response.ok) {
+    throw await handleApiError(response);
+  }
+  let data;
+  try {
+    data = await response.json();
+  } catch {
+    throw new MultisageError(
+      "Received malformed response from server.",
+      "malformed_response"
+    );
+  }
+  if (!data || typeof data !== "object" || !("answer" in data)) {
+    throw new MultisageError(
+      "Received malformed response from server.",
+      "malformed_response"
+    );
+  }
+  return data;
+}
+
+// src/format.ts
+function isFullResponse(response) {
+  return "stages" in response && response.stages != null;
+}
+function formatDefault(response) {
+  return response.answer;
+}
+function formatFullMarkdown(response) {
+  if (!isFullResponse(response)) {
+    return `# Answer
+
+${response.answer}`;
+  }
+  const sections = [];
+  if (response.stages.quickAnswer) {
+    sections.push(`# Quick Answer
+
+${response.stages.quickAnswer}`);
+  }
+  const experts = response.experts;
+  if (experts.length > 0) {
+    const expertSections = experts.map(
+      (e) => `## ${displayName(e.name)}
+
+${e.response}`
+    );
+    sections.push(`# Expert Responses
+
+${expertSections.join("\n\n")}`);
+  }
+  if (response.stages.synthesis) {
+    sections.push(`# Synthesis
+
+${response.stages.synthesis}`);
+  }
+  if (response.stages.debate) {
+    sections.push(`# Debate
+
+${response.stages.debate}`);
+  }
+  return sections.join("\n\n---\n\n");
+}
+function formatJson(response) {
+  return JSON.stringify(response, null, 2);
+}
+function formatJsonError(code, message, rateLimitMeta) {
+  const error = { code, message };
+  if (rateLimitMeta?.retryAfter != null) {
+    error.retryAfter = rateLimitMeta.retryAfter;
+    error.rateLimit = {
+      limit: rateLimitMeta.limit,
+      remaining: rateLimitMeta.remaining,
+      reset: rateLimitMeta.reset
+    };
+  }
+  return JSON.stringify({ error }, null, 2);
+}
+var DISPLAY_NAMES = {
+  gpt: "GPT",
+  claude: "Claude",
+  gemini: "Gemini"
+};
+function displayName(name) {
+  return DISPLAY_NAMES[name] || name.charAt(0).toUpperCase() + name.slice(1);
+}
+
+// src/index.ts
+var DEFAULT_API_URL = "https://multisage.ai";
+var program = new Command();
+program.name("multisage").description("Query Multisage from your terminal").version("0.1.0").argument("[question]", "The question to ask").option("-k, --api-key <key>", "API key (overrides MULTISAGE_API_KEY env var)").option("-u, --api-url <url>", "Base URL for API", DEFAULT_API_URL).option("-f, --full", "Include all stages and expert details", false).option("-j, --json", "Output as structured JSON", false).option("-q, --quiet", "Suppress progress indicator", false).action(async (question, options) => {
+  if (!question) {
+    if (process.stdin.isTTY) {
+      program.help();
+      return;
+    }
+    process.stderr.write("Error: No question provided. Usage: multisage <question>\n");
+    process.exit(1);
+  }
+  const apiKey = options.apiKey || process.env.MULTISAGE_API_KEY || "";
+  if (options.apiKey) {
+    process.stderr.write(
+      "Warning: API key passed via command line may be visible in shell history. Consider using MULTISAGE_API_KEY env var instead.\n"
+    );
+  }
+  const keyError = validateApiKey(apiKey);
+  if (keyError) {
+    process.stderr.write(`Error: ${keyError}
+`);
+    process.exit(1);
+  }
+  const urlError = validateUrl(options.apiUrl);
+  if (urlError) {
+    process.stderr.write(`Error: ${urlError}
+`);
+    process.exit(1);
+  }
+  if (question.length > 1e3) {
+    process.stderr.write(
+      `Warning: Question is ${question.length} characters. The server truncates to 1000 characters.
+`
+    );
+  }
+  const showSpinner = !!(process.stdout.isTTY && !options.quiet);
+  const spinner = showSpinner ? ora({ text: "Thinking... (asking 3 experts)", stream: process.stderr }).start() : null;
+  const sigintHandler = () => {
+    if (spinner) spinner.stop();
+    process.exit(130);
+  };
+  process.on("SIGINT", sigintHandler);
+  try {
+    const response = await queryMultisage({
+      question,
+      apiKey,
+      apiUrl: options.apiUrl,
+      detail: options.full ? "full" : void 0
+    });
+    if (spinner) spinner.stop();
+    let output;
+    if (options.json) {
+      output = formatJson(response);
+    } else if (options.full) {
+      output = formatFullMarkdown(response);
+    } else {
+      output = formatDefault(response);
+    }
+    process.stdout.write(output + "\n");
+  } catch (err) {
+    if (spinner) spinner.stop();
+    if (err instanceof MultisageError) {
+      if (options.json) {
+        process.stdout.write(formatJsonError(err.code, err.message, err.rateLimitMeta) + "\n");
+      }
+      process.stderr.write(`Error: ${err.message}
+`);
+      process.exit(err.exitCode);
+    }
+    const message = err instanceof Error ? err.message : String(err);
+    if (options.json) {
+      process.stdout.write(formatJsonError("unknown", message) + "\n");
+    }
+    process.stderr.write(`Error: ${message}
+`);
+    process.exit(1);
+  } finally {
+    process.removeListener("SIGINT", sigintHandler);
+  }
+});
+program.parse();

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@cluesmith/multisage",
+  "version": "0.1.0",
+  "description": "CLI client for Multisage — ask questions from your terminal",
+  "type": "module",
+  "bin": {
+    "multisage": "./dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsup",
+    "pretest": "tsup",
+    "test": "node --experimental-vm-modules ../../node_modules/.bin/jest --config jest.config.js"
+  },
+  "dependencies": {
+    "commander": "^12.1.0",
+    "ora": "^8.1.1"
+  },
+  "devDependencies": {
+    "@types/jest": "^29.5.0",
+    "jest": "^29.7.0",
+    "ts-jest": "^29.2.0",
+    "tsup": "^8.3.5",
+    "typescript": "^5.7.0"
+  }
+}