mantisai-cli 2.0.0

package/lib/picker.js

@@ -0,0 +1,150 @@
+import { createSpaceState, fetchThreads } from './fetch.js';
+import { loadConfig, saveConfig } from './config.js';
+import { syncMcpConfigs } from './mcp-config.js';
+import { searchSpaces, resolveSpaceFromInput } from './spaces.js';
+import { parseSpaceIdFromInput } from './space-id.js';
+import { die, info, promptInput, promptSearch, success } from './ui.js';
+
+const BROWSE_PAGE = 20;
+
+function spaceLabel(s) {
+  const name = s.name || '(unnamed)';
+  const maps = s.map_count != null ? ` · ${s.map_count} map(s)` : '';
+  const role = s.role ? ` · ${s.role}` : '';
+  return name + maps + role;
+}
+
+function spaceChoices(spaces) {
+  return spaces.map((s) => ({
+    name: spaceLabel(s),
+    value: s,
+    description: s.id,
+  }));
+}
+
+export async function requireConfig() {
+  const cfg = loadConfig();
+  if (!cfg.apiKey || !cfg.apiBaseUrl) {
+    die('Run mantis setup or /mantis:connect first (API key + URL).');
+  }
+  return cfg;
+}
+
+function threadChoices(threads, query) {
+  const terms = (query || '').trim().toLowerCase();
+  const list = terms
+    ? threads.filter((t) => {
+        const hay = `${t.name} ${t.id}`.toLowerCase();
+        return hay.includes(terms);
+      })
+    : threads;
+  const out = [
+    { name: '➕ Create new thread', value: '__new__', description: 'New space state' },
+  ];
+  for (const t of list) {
+    const when = t.updated_at ? String(t.updated_at).slice(0, 10) : '';
+    out.push({
+      name: t.name || '(unnamed)',
+      value: t,
+      description: when || t.id,
+    });
+  }
+  return out;
+}
+
+async function pickSpaceByLink(cfg) {
+  const raw = await promptInput('Paste Mantis space link or UUID (Enter to browse)', {
+    default: '',
+  });
+  if (!raw?.trim()) return null;
+  const space = await resolveSpaceFromInput(cfg.apiBaseUrl, cfg.apiKey, raw);
+  if (!space) die('Space not found or you do not have access.');
+  return saveSpace(cfg, space);
+}
+
+export async function pickSpace() {
+  const cfg = await requireConfig();
+
+  if (!process.stdin.isTTY) {
+    const page = await searchSpaces(cfg.apiBaseUrl, cfg.apiKey, { limit: 1 });
+    if (!page.spaces?.length) die('No spaces found.');
+    return saveSpace(cfg, page.spaces[0]);
+  }
+
+  const fromLink = await pickSpaceByLink(cfg);
+  if (fromLink) return fromLink;
+
+  const picked = await promptSearch(
+    'Select space (↑↓ type to search, paste link in previous step)',
+    async (input) => {
+      const id = parseSpaceIdFromInput(input);
+      if (id) {
+        const one = await resolveSpaceFromInput(cfg.apiBaseUrl, cfg.apiKey, input);
+        return one ? spaceChoices([one]) : [{ name: 'No match for that link/id', value: null, disabled: true }];
+      }
+      const page = await searchSpaces(cfg.apiBaseUrl, cfg.apiKey, {
+        q: input || '',
+        limit: BROWSE_PAGE,
+        offset: 0,
+      });
+      return spaceChoices(page.spaces || []);
+    },
+  );
+  if (!picked) die('No space selected.');
+  return saveSpace(cfg, picked);
+}
+
+function saveSpace(cfg, space) {
+  const changed = cfg.spaceId !== space.id;
+  const next = { ...cfg, spaceId: space.id, spaceName: space.name };
+  if (changed) {
+    delete next.spaceStateId;
+    delete next.spaceStateName;
+  }
+  saveConfig(next);
+  syncMcpConfigs(next);
+  success(`Space: ${space.name}`);
+  if (changed) {
+    info('Thread cleared — pick a thread, then /reload-plugins in Claude Code.');
+  }
+  return next;
+}
+
+export async function pickThread(initialFilter = '') {
+  const cfg = await requireConfig();
+  if (!cfg.spaceId) die('Pick a space first: /mantis:space');
+
+  const threads = await fetchThreads(cfg.apiBaseUrl, cfg.apiKey, cfg.spaceId);
+
+  if (!process.stdin.isTTY) {
+    if (!threads.length) die('No threads. Run interactively to create one.');
+    return saveThread(cfg, threads[0]);
+  }
+
+  const picked = await promptSearch(
+    `Thread in "${cfg.spaceName || 'space'}" (↑↓, type to filter)`,
+    async (input) => threadChoices(threads, input || initialFilter),
+  );
+
+  if (picked === '__new__') {
+    const name = await promptInput('Thread name', { default: 'Claude Code' });
+    const created = await createSpaceState(
+      cfg.apiBaseUrl, cfg.apiKey, cfg.spaceId, name || 'Claude Code',
+    );
+    return saveThread(cfg, created);
+  }
+  return saveThread(cfg, picked);
+}
+
+function saveThread(cfg, thread) {
+  const next = {
+    ...cfg,
+    spaceStateId: thread.id,
+    spaceStateName: thread.name,
+  };
+  saveConfig(next);
+  syncMcpConfigs(next);
+  success(`Thread: ${thread.name}`);
+  info('MCP headers update on reconnect — run /reload-plugins if tools lack context.');
+  return next;
+}

package/lib/space-id.js

@@ -0,0 +1,13 @@
+const UUID_RE =
+  /[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/i;
+
+/** Extract space UUID from a Mantis URL (/space/{id}), raw UUID, or search text containing one. */
+export function parseSpaceIdFromInput(text) {
+  const t = (text || '').trim();
+  if (!t) return null;
+  const pathMatch = t.match(/\/space\/([0-9a-f-]{36})/i);
+  if (pathMatch) return pathMatch[1].toLowerCase();
+  const uuidMatch = t.match(UUID_RE);
+  if (uuidMatch) return uuidMatch[0].toLowerCase();
+  return null;
+}

package/lib/spaces.js

@@ -0,0 +1,48 @@
+import { listSpaces } from './api.js';
+import { parseSpaceIdFromInput } from './space-id.js';
+
+export async function fetchSpaceById(baseUrl, apiKey, spaceId) {
+  const page = await listSpaces(baseUrl, apiKey, {
+    scope: 'accessible',
+    space_id: spaceId,
+    limit: 1,
+    offset: 0,
+  });
+  return page.spaces?.[0] ?? null;
+}
+
+export async function resolveSpaceFromInput(baseUrl, apiKey, text) {
+  const id = parseSpaceIdFromInput(text);
+  if (!id) return null;
+  return fetchSpaceById(baseUrl, apiKey, id);
+}
+
+/** One page of spaces; optional name/id search — does not load the full catalog. */
+export async function searchSpaces(
+  baseUrl,
+  apiKey,
+  { q = '', limit = 20, offset = 0, scope = 'accessible' } = {},
+) {
+  const id = parseSpaceIdFromInput(q);
+  if (id) {
+    const one = await fetchSpaceById(baseUrl, apiKey, id);
+    return {
+      spaces: one ? [one] : [],
+      total: one ? 1 : 0,
+      limit: 1,
+      offset: 0,
+    };
+  }
+  const page = await listSpaces(baseUrl, apiKey, {
+    scope,
+    limit,
+    offset,
+    q: q.trim() || undefined,
+  });
+  return {
+    spaces: page.spaces || [],
+    total: page.total ?? (page.spaces || []).length,
+    limit: page.limit ?? limit,
+    offset: page.offset ?? offset,
+  };
+}

package/lib/ui.js

@@ -0,0 +1,73 @@
+import { confirm, input, password, search, select } from '@inquirer/prompts';
+
+export function isCancel(err) {
+  return err?.name === 'ExitPromptError';
+}
+
+export function die(msg) {
+  console.error(`\n  ✖ ${msg}\n`);
+  process.exit(1);
+}
+
+export function banner(title, subtitle) {
+  console.log('');
+  console.log(`  \x1b[36m${title}\x1b[0m`);
+  if (subtitle) console.log(`  \x1b[2m${subtitle}\x1b[0m`);
+  console.log('');
+}
+
+export function success(msg) {
+  console.log(`  \x1b[32m✔\x1b[0m ${msg}`);
+}
+
+export function info(msg) {
+  console.log(`  \x1b[2m→\x1b[0m ${msg}`);
+}
+
+export async function promptInput(message, { default: def } = {}) {
+  try {
+    return await input({ message, default: def });
+  } catch (e) {
+    if (isCancel(e)) die('Cancelled.');
+    throw e;
+  }
+}
+
+export async function promptSecret(message, { default: def } = {}) {
+  if (def) {
+    return promptInput(message, { default: def });
+  }
+  try {
+    return await password({ message, mask: '•' });
+  } catch (e) {
+    if (isCancel(e)) die('Cancelled.');
+    throw e;
+  }
+}
+
+export async function promptSearch(message, source, { pageSize = 12 } = {}) {
+  try {
+    return await search({ message, pageSize, source });
+  } catch (e) {
+    if (isCancel(e)) die('Cancelled.');
+    throw e;
+  }
+}
+
+export async function promptSelect(message, choices) {
+  try {
+    return await select({ message, choices });
+  } catch (e) {
+    if (isCancel(e)) die('Cancelled.');
+    throw e;
+  }
+}
+
+export async function promptConfirm(message, { default: def = false } = {}) {
+  try {
+    return await confirm({ message, default: def });
+  } catch (e) {
+    if (isCancel(e)) die('Cancelled.');
+    throw e;
+  }
+}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "mantisai-cli",
+  "version": "2.0.0",
+  "description": "Mantis developer CLI — create maps, manage spaces and threads, configure Claude Code, and connect agents to Mantis MCP.",
+  "type": "module",
+  "license": "MIT",
+  "author": "AnasMaar",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/KellisLab/mantis-cli.git"
+  },
+  "bugs": {
+    "url": "https://github.com/KellisLab/mantis-cli/issues"
+  },
+  "homepage": "https://github.com/KellisLab/mantis-cli#readme",
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org"
+  },
+  "dependencies": {
+    "@inquirer/prompts": "^7.5.1",
+    "commander": "^13.1.0",
+    "csv-parse": "^6.2.1",
+    "csv-stringify": "^6.7.0",
+    "fast-glob": "^3.3.3"
+  },
+  "bin": {
+    "mantis": "bin/mantis.js"
+  },
+  "files": [
+    ".claude-plugin",
+    ".claude-plugin/marketplace.json",
+    ".mcp.json",
+    "skills",
+    "bin",
+    "lib",
+    "LICENSE",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "mantis",
+    "cli",
+    "mcp",
+    "claude-code",
+    "plugin"
+  ]
+}

package/skills/codebase/SKILL.md

@@ -0,0 +1,75 @@
+---
+description: Index a local codebase into a CSV for Mantis, optionally creating and activating a Mantis codebase map. Use when the user wants Claude Code to map a repository or create a codebase CSV.
+argument-hint: [repo-path]
+allowed-tools: Bash, AskUserQuestion
+disable-model-invocation: true
+---
+
+# Create Codebase CSV
+
+Use `mantis create codebase`. This command is local-first: it scans files on the user's machine and writes a CSV. It can optionally continue into `mantis create map`.
+
+## CSV-only Flow
+
+1. Get the repo root from `$ARGUMENTS` or ask the user.
+2. Run:
+
+```bash
+mantis create codebase "./repo" --out "./repo-codebase.csv"
+```
+
+3. Explain the CSV columns:
+   - `path`: repo-relative file path
+   - `file_name`
+   - `extension`
+   - `language`
+   - `kind`: rough file role such as component, route, api, utility, test, source
+   - `loc`
+   - `bytes`
+   - `imports`
+   - `summary`
+   - `content`
+
+## Full Demo Flow
+
+If the user wants the codebase to become a Mantis map immediately, run:
+
+```bash
+mantis create codebase "./repo" \
+  --create-map \
+  --space-mode new \
+  --space-name "Codebase: Repo Name" \
+  --private \
+  --map-name "Source Code Index" \
+  --activate \
+  --thread-name "Architecture Review"
+```
+
+The command uses good defaults for codebase maps:
+
+- `title`: `path`
+- `semantic`: `summary,content,imports`
+- `categoric`: `language,kind,extension`
+- `numeric`: `loc,bytes`
+
+## After Activation
+
+If `--activate` was used, tell the user to run:
+
+```text
+/reload-plugins
+```
+
+Then suggest prompts like:
+
+```text
+What are the main architectural zones in this codebase?
+Which files are central or risky?
+Where should I start if I want to refactor the map rendering system?
+```
+
+## Notes
+
+- Use `mantis setup` first if API configuration is missing.
+- Avoid scanning dependency/build folders manually; the CLI already ignores common junk like `.git`, `node_modules`, `.next`, `dist`, `build`, and caches.
+- For agent-driven demos, pass flags explicitly instead of relying on interactive prompts.

package/skills/connect/SKILL.md

@@ -0,0 +1,42 @@
+---
+description: Run the Mantis MCP setup wizard (API key, space, thread). Use when the user wants to connect Claude Code to Mantis or fix MCP connection issues.
+disable-model-invocation: true
+---
+
+# Connect Mantis MCP
+
+Run the interactive setup in the user's terminal:
+
+```bash
+mantis setup
+```
+
+If the plugin is not on PATH, use:
+
+```bash
+node "${CLAUDE_PLUGIN_ROOT}/bin/mantis.js" setup
+```
+
+The wizard will:
+
+1. Ask for Mantis API URL and Developer API key (`live_…` from the Mantis Developer portal).
+2. List accessible spaces — owned, shared, and public (most recent first).
+3. Pick or create a **space state** (thread).
+4. Save config for MCP headers (`X-Space-State-ID`).
+
+After setup, switch context with **`/mantis:space`** and **`/mantis:thread`** (Claude Code **AskUserQuestion** menu with arrow keys). Terminal: `mantis select space` / `mantis select thread`.
+
+If they have not run **`mantis setup`** yet, tell them:
+
+```bash
+npm install -g mantisai-cli
+mantis setup
+```
+
+That installs the **mantis@mantis-plugins** Claude Code plugin and saves API/space/thread config.
+
+Then: **`/reload-plugins`** in Claude Code (if already open). Confirm **API URL** when prompted (default `https://kellis-h200-1.csail.mit.edu`; use `http://localhost:8000` for local Docker). API keys: https://mantis.csail.mit.edu/developer/#keys
+
+If `/plugin` shows **Disabled** or *not installed*: run `claude plugin install mantis@mantis-plugins`, enable it, then `/reload-plugins`. If update fails, uninstall and reinstall the plugin (stale `installed_plugins.json` / orphaned cache).
+
+For connection errors: URL must end with `/mcp_integrated/`; avoid `/mcp/mcp` unless their deployment uses it.

package/skills/createmap/SKILL.md

@@ -0,0 +1,62 @@
+---
+description: Create a Mantis map from a local CSV or XLSX file using the mantis CLI. Use when the user wants to upload a dataset, configure field types, or turn a CSV into a Mantis map.
+argument-hint: [csv-or-xlsx-path]
+allowed-tools: Bash, AskUserQuestion
+disable-model-invocation: true
+---
+
+# Create Mantis Map
+
+Use the local `mantis create map` CLI. Prefer passing arguments explicitly so this works for agents and humans.
+
+## Steps
+
+1. Get the local CSV/XLSX path from `$ARGUMENTS` or ask the user for it.
+
+2. Inspect the header row if it is a CSV. Decide field types:
+   - `title`: one human-readable identifier column, usually `title`, `name`, `path`, or `file`.
+   - `semantic`: text columns to embed, usually `content`, `summary`, `description`, `text`, or `body`.
+   - `categoric`: labels like `language`, `kind`, `extension`, `category`.
+   - `numeric`: measurements like `loc`, `bytes`, `score`, `count`.
+   - `date`: date/time columns.
+   - `links`: URL columns.
+   - ignored columns go in `--delete-column`.
+
+3. Ask where to put the map if the user did not specify:
+   - new space
+   - existing space
+
+4. Run `mantis create map` with explicit flags. Example:
+
+```bash
+mantis create map "./dataset.csv" \
+  --space-mode new \
+  --space-name "Codebase Index" \
+  --private \
+  --map-name "Source Files" \
+  --title-column "path" \
+  --semantic-column "summary,content" \
+  --categoric-column "language,kind,extension" \
+  --numeric-column "loc,bytes" \
+  --activate \
+  --thread-name "Dataset Exploration"
+```
+
+For an existing space:
+
+```bash
+mantis create map "./dataset.csv" \
+  --space-mode existing \
+  --space-id "<space-uuid>" \
+  --map-name "Source Files" \
+  --title-column "path" \
+  --semantic-column "summary,content"
+```
+
+5. Report the created space link and map id from the JSON output. If `--activate` was used, tell the user to run `/reload-plugins`.
+
+## Notes
+
+- If the user wants a fully interactive human flow, run only `mantis create map "./dataset.csv"`.
+- If Claude Code is driving the flow, avoid interactive prompts by passing flags.
+- Use `mantis setup` first if the CLI says API key or URL is missing.

package/skills/mantis/SKILL.md

@@ -0,0 +1,52 @@
+---
+
+## name: mantis
+description: Work with MIT Mantis spaces, maps, clusters, and notebooks via MCP. Use when the user mentions Mantis, spaces, maps, embeddings, clusters, bags, or wants to explore/visualize data in their workspace.
+
+# Mantis (Claude Code)
+
+Mantis is a spatial data workspace: **spaces** contain **maps** (embeddings of datasets), **clusters**, **bags**, and **notebooks**.
+
+## Connection
+
+1. User runs `mantis setup` (or `/mantis:connect`) with a Developer API key from the Mantis portal.
+2. MCP endpoint: `{api_base_url}/mcp_integrated/` (trailing slash required).
+3. Required header on every MCP request: `**X-Space-State-ID`** = thread UUID from setup (setup writes this into the plugin MCP config).
+4. After changing space/thread: `mantis select` then ask the user to run `**/reload-plugins**`.
+
+## REST (setup only)
+
+
+| Endpoint                                      | Purpose                             |
+| --------------------------------------------- | ----------------------------------- |
+| `GET /api/v1/me/spaces/?scope=accessible&limit=100` | List owned, shared, and public spaces |
+| `GET /api/v1/me/space-states/?space_id=`      | List threads                        |
+| `POST /api/v1/me/space-states/`               | Create thread `{ space_id, name? }` |
+
+
+Auth: `Authorization: Bearer live_…` — key must be linked to a Mantis user.
+
+## MCP tools (read-focused)
+
+Call `**get_space_context**` first when you need map IDs, field types, cluster names, or point counts.
+
+Other useful tools: `get_tree_status`, `get_cluster_children`, `get_bags_from_map`, `get_bag_contents`, `get_point_details`, `get_selected_points`, `get_available_dimensions`.
+
+Space management tools (`create_space`, `create_map_from_url`, etc.) need session or space-state context.
+
+## Conventions
+
+- Refer to spaces and maps by **name** in user-facing text; use UUIDs only in tool arguments.
+- Maps belong to a space; pick `primary_map_id` from space list API or `get_space_context`.
+- Notebooks can bootstrap from `X-Space-State-ID` alone; file uploads still need a chat session when applicable.
+- Default API URL: `https://kellis-h200-1.csail.mit.edu` (local: `http://localhost:8000`). API keys: https://mantis.csail.mit.edu/developer/#keys
+
+## Slash commands in this plugin
+
+- `/mantis:connect` — first-time setup (API key)
+- `/mantis:space` — pick space via **AskUserQuestion** (↑↓ in Claude UI; optional filter: `/mantis:space atlas`)
+- `/mantis:thread` — pick thread the same way
+- Terminal pickers: `mantis select space` / `mantis select thread` if the in-chat menu fails
+- `/mantis:status` — show current space/thread
+
+After **`/mantis:thread`** only, run `/reload-plugins` once (MCP headers are fixed at connect time). Space-only changes do not need a reload until a thread is set.

package/skills/select/SKILL.md

@@ -0,0 +1,17 @@
+---
+description: Change the active Mantis space or thread (space state) for MCP. Use when the user wants to switch workspace or conversation context.
+disable-model-invocation: true
+---
+
+# Select Mantis space / thread
+
+Prefer the interactive slash commands (arrow keys + filter as you type):
+
+- **`/mantis:space`** — pick a space
+- **`/mantis:thread`** — pick a thread (after space)
+
+CLI fallback: `mantis select` or `node "${CLAUDE_PLUGIN_ROOT}/bin/mantis.js" select`.
+
+After a change, run **`/reload-plugins`**.
+
+Optional argument from user (not passed to CLI automatically): if they give a **thread UUID**, they can paste it during setup or edit `~/.mantis/claude-code/config.json` (or `${CLAUDE_PLUGIN_DATA}/config.json`) and set `spaceStateId`.

package/skills/space/SKILL.md

@@ -0,0 +1,62 @@
+---
+description: Select your Mantis space (arrow-key menu in Claude Code). Use when switching workspace for MCP.
+argument-hint: [filter]
+allowed-tools: AskUserQuestion, Bash
+disable-model-invocation: true
+---
+
+# Select Mantis space
+
+Slash-command `!` blocks cannot use an interactive terminal (no arrow keys). Use **AskUserQuestion** — that is the native Claude Code picker UI.
+
+## Steps
+
+1. If `$ARGUMENTS` looks like a Mantis space URL (`/space/{uuid}`) or a UUID, resolve it first:
+
+```bash
+node "${CLAUDE_PLUGIN_ROOT}/bin/mantis-resolve-space.js" $ARGUMENTS
+```
+
+If JSON has `space`, run `mantis-set-space.js` with that id and name, then stop (skip browse). On `error`, explain and offer browse.
+
+2. Otherwise run (search text or empty for recent page):
+
+```bash
+node "${CLAUDE_PLUGIN_ROOT}/bin/mantis-list-spaces.js" --filter "$ARGUMENTS"
+```
+
+Parse the JSON. On `error`, tell the user to run `mantis setup` in a terminal.
+
+3. **AskUserQuestion** (max 4 options per call):
+   - If the user pasted a link in chat, pass it as `$ARGUMENTS` or run step 1 with that URL.
+   - `header`: `Space`
+   - `question`: `Which Mantis space should Claude use?`
+   - For each item in `spaces`, one option:
+     - `label`: space `name` (short)
+     - `description`: full `id` + map count if present
+   - If `hasMore` is true, use the 3rd slot for the best match and the 4th option:
+     - `label`: `More spaces…`
+     - `description`: `Show next page (${total} total)`
+   - On "More spaces…", re-run with `--offset` increased by `limit` (same filter), then AskUserQuestion again.
+
+4. After the user picks a space (not "More"), run:
+
+```bash
+node "${CLAUDE_PLUGIN_ROOT}/bin/mantis-set-space.js" <uuid-from-description> "<name>"
+```
+
+Use the UUID from the selected option's **description**, not the label.
+
+5. If `needThread` or `threadCleared`, run **`/mantis:thread`** next in this session (user must pick a thread for the new space).
+
+6. After space or thread changes, tell the user to run **`/reload-plugins`** so MCP reconnects with the updated `X-Space-State-ID` header. Do not try to invoke `/reload-plugins` as a Skill tool.
+
+## Terminal fallback
+
+If AskUserQuestion does not appear (known CC bug in some versions), tell the user to run in a separate terminal:
+
+```bash
+mantis select space
+```
+
+Then `/reload-plugins`.

package/skills/status/SKILL.md

@@ -0,0 +1,20 @@
+---
+description: Show the current Mantis space, thread, and MCP URL from plugin config. Use when checking whether Claude Code is connected to Mantis.
+disable-model-invocation: true
+---
+
+# Mantis status
+
+Run in the terminal:
+
+```bash
+mantis status
+```
+
+Or:
+
+```bash
+node "${CLAUDE_PLUGIN_ROOT}/bin/mantis.js" status
+```
+
+Report the output to the user. If no thread is set, tell them to run `/mantis:connect` or `mantis setup`, then `/reload-plugins`.