mantisai-cli 2.0.2 → 3.0.0

package/README.md

@@ -1,120 +1,47 @@
 # mantisai-cli
 
-Mantis developer CLI — manage spaces, create maps from local data, and configure [Claude Code](https://code.claude.com) as a Mantis client. Distributed alongside the **mantis@mantis-plugins** Claude Code plugin.
+Mantis developer CLI — spaces, maps, MCP tools for AI agents, and editor skill sync.
 
-> **Naming note:** the repo is `KellisLab/mantis-cli` but the npm package is published as **`mantisai-cli`** because `mantis-cli` was already taken on npm. The binary you run is just `mantis`.
+> **Naming:** repo [`KellisLab/mantis-cli`](https://github.com/KellisLab/mantis-cli), npm package **`mantisai-cli`**, binary **`mantis`**.
+
+Full docs (VitePress):
+
+- [Overview](https://mantis.csail.mit.edu/docs/mantis-cli/)
+- [Install](https://mantis.csail.mit.edu/docs/mantis-cli/install)
+- [Claude Code](https://mantis.csail.mit.edu/docs/mantis-cli/claude-code)
+- [OpenCode](https://mantis.csail.mit.edu/docs/mantis-cli/opencode)
+
+Source: `Mantis/docs/mantis-cli/`
 
 ## Requirements
 
-- [Node.js](https://nodejs.org/) 18+
-- A running Mantis API (default `https://kellis-h200-1.csail.mit.edu`; local dev: `http://localhost:8000`)
-- A Mantis **Developer API key** (`live_…`) from https://mantis.csail.mit.edu/developer/#keys
-- (Optional, for plugin features) [Claude Code](https://code.claude.com) (`claude` on your PATH)
+- Node.js 18+
+- Mantis API + Developer key from https://mantis.csail.mit.edu/developer/#keys
 
 ## Install
 
 ```bash
 npm install -g mantisai-cli
 mantis setup
+mantis setup claude    # optional: Claude Code skills
+mantis use get_space_context
 ```
 
-`mantis setup` walks through API URL, API key, space, and thread selection. If Claude Code is installed, it also registers the **mantis@mantis-plugins** plugin and writes the MCP config.
+Config: `~/.mantis/config.json`
 
 ## Commands
 
 | Command | Description |
-|---------|-------------|
-| `mantis setup` | Connect to Mantis, pick space & thread, configure Claude Code |
-| `mantis status` | Show current API, space, thread, and MCP URL |
-| `mantis select [space\|thread\|both]` | Switch active space and/or thread |
-| `mantis create map <file>` | Create a Mantis map from a local CSV/XLSX |
-| `mantis create codebase [root]` | Index a local codebase to CSV; optionally create a map |
-
-Run any command with `--help` for full options.
-
-### Examples
-
-```bash
-# Create a new private space and load a CSV as a map
-mantis create map ./data.csv \
-  --space-mode new --space-name "Sales" --private \
-  --map-name "Q4 Pipeline" \
-  --title-column name --semantic-column description --numeric-column revenue
-
-# Add a map to an existing space
-mantis create map ./more-data.csv \
-  --space-mode existing --space-id <uuid> \
-  --map-name "Cohort 2"
-
-# Index your repo into Mantis
-mantis create codebase . --create-map --space-mode new --space-name "Repo Index" --private
-```
-
-## Claude Code integration
-
-After `mantis setup`:
-
-1. Open Claude Code (restart if it was already running).
-2. `/plugin` → enable **mantis @ mantis-plugins** (user scope) if needed.
-3. `/reload-plugins`
-4. Confirm with `/mantis:status`.
-
-### Slash commands
-
-| Command | Description |
-|---------|-------------|
-| `/mantis:connect` | Run setup / reconnect |
-| `/mantis:space` | Change space (search or paste a `/space/{uuid}` link) |
-| `/mantis:thread` | Change thread (space state) |
-| `/mantis:status` | Show current space, thread, and MCP URL |
-| `/mantis:select` | Quick space/thread selection |
-
-After changing **thread**, run `/reload-plugins` so MCP picks up the new `X-Space-State-ID` header.
-
-### Paste a space link
-
-In `mantis setup` or `/mantis:space`, paste a URL such as:
-
-`https://mantis.csail.mit.edu/space/1e1ed055-c869-4b78-b41f-4216a44049d4/`
-
-Use the same Mantis API base URL as the space you are targeting (local vs production).
-
-## Update
-
-**CLI**:
-
-```bash
-npm install -g mantisai-cli@latest
-```
-
-**Plugin (slash commands, MCP, skills)** — in Claude Code:
-
-```text
-/plugin marketplace update mantis-plugins
-```
-
-Then update **mantis@mantis-plugins** and `/reload-plugins`.
-
-## Manual plugin install
-
-```bash
-claude plugin marketplace add KellisLab/mantis-cli
-claude plugin install mantis@mantis-plugins --scope user
-```
-
-Enable in `/plugin`, then `/reload-plugins`.
-
-## Migrating from `mantis-claude-code`
-
-If you previously installed the package as `mantis-claude-code`, migrate with:
-
-```bash
-npm uninstall -g mantis-claude-code
-npm install -g mantisai-cli
-mantis setup
-```
-
-Your local config at `~/.mantis/claude-code/config.json` is preserved.
+| --- | --- |
+| `mantis setup [claude\|opencode]` | API + space/thread, or sync editor skills |
+| `mantis status` | Current config |
+| `mantis select [space\|thread\|both]` | Switch space/thread |
+| `mantis spaces list\|resolve\|set` | Scriptable space ops (JSON) |
+| `mantis threads list\|new\|set` | Scriptable thread ops (JSON) |
+| `mantis tools` | List MCP tools |
+| `mantis use <tool>` | Call an MCP tool (JSON output) |
+| `mantis create map <file>` | Map from CSV/XLSX |
+| `mantis create codebase [root]` | Index repo; optional `--create-map` |
 
 ## npm
 

package/bin/mantis.js

@@ -1,114 +1,494 @@
 #!/usr/bin/env node
+
 import path from 'node:path';
+
 import { Command } from 'commander';
 
-import { createCodebaseCsv } from '../lib/codebase-csv.js';
-import { createMapFlow } from '../lib/map-create.js';
-import { die, info, success } from '../lib/ui.js';
+
+
+import { getContainer } from '../lib/container.js';
+
+import { parseUseCommand } from '../lib/utils/tool-args.js';
+
+
+
+const c = getContainer();
+
+const { map, codebaseIndexer, tools, ui, setup, selection, context, query } = c;
 
 const program = new Command();
 
+
+
 function defaultCodebaseOut(root) {
+
   const base = path.basename(path.resolve(root || process.cwd())) || 'codebase';
+
   return path.resolve(process.cwd(), `${base}-codebase.csv`);
+
 }
 
+
+
 function addMapOptions(cmd) {
+
   return cmd
+
     .option('--space-mode <mode>', 'new or existing')
+
     .option('--space-id <uuid>', 'existing Mantis space id')
+
     .option('--space-name <name>', 'new space name or display name for existing space')
+
     .option('--space-search <query>', 'search text for choosing an existing space')
+
     .option('--public', 'make a new space public')
+
     .option('--private', 'make a new space private')
+
     .option('--map-name <name>', 'map name')
+
     .option('--title-column <columns>', 'comma-separated title column names')
+
     .option('--semantic-column <columns>', 'comma-separated semantic column names')
+
     .option('--numeric-column <columns>', 'comma-separated numeric column names')
+
     .option('--categoric-column <columns>', 'comma-separated categorical column names')
+
     .option('--date-column <columns>', 'comma-separated date column names')
+
     .option('--links-column <columns>', 'comma-separated link column names')
+
     .option('--delete-column <columns>', 'comma-separated ignored column names')
+
     .option('--data-types <json>', 'raw data_types JSON array')
-    .option('--activate', 'set created space/thread as active in Claude Code')
-    .option('--no-activate', 'do not set active Claude Code context')
+
+    .option('--activate', 'set created space/thread as active context')
+
+    .option('--no-activate', 'do not update active space/thread')
+
     .option('--thread-name <name>', 'thread name when activating');
+
 }
 
+
+
+function addListOptions(cmd) {
+
+  return cmd
+
+    .option('--filter <query>', 'search filter')
+
+    .option('--offset <n>', 'pagination offset', (v) => parseInt(v, 10) || 0)
+
+    .option('--limit <n>', 'page size', (v) => parseInt(v, 10) || 4);
+
+}
+
+
+
+async function listTools() {
+
+  const data = await tools.listTools();
+
+  console.log(JSON.stringify(data, null, 2));
+
+}
+
+
+
 program
+
   .name('mantis')
-  .description('Mantis developer CLI — manage spaces, create maps, and configure Claude Code integration')
-  .version('2.0.1');
+
+  .description('Mantis CLI — spaces, maps, and MCP tools for AI agents')
+
+  .version('3.0.0');
+
+
 
 program
-  .command('setup')
-  .description('Connect Claude Code to Mantis')
-  .action(async () => import('./mantis-setup.js'));
+
+  .command('setup [provider]')
+
+  .description('Configure Mantis, or install skills for claude/opencode')
+
+  .action(async (provider) => {
+
+    try {
+
+      if (!provider) return setup.run();
+
+      setup.runProvider(provider);
+
+    } catch (e) {
+
+      ui.die(e.message || String(e));
+
+    }
+
+  });
+
+
 
 program
+
   .command('status')
-  .description('Show current Mantis Claude Code config')
-  .action(async () => import('./mantis-status.js'));
+
+  .description('Show current Mantis config')
+
+  .action(() => {
+
+    const s = context.status();
+
+    console.log('Mantis — status\n');
+
+    console.log(`Config:  ${s.configPath}`);
+
+    console.log(`API:     ${s.apiBaseUrl}`);
+
+    console.log(`MCP:     ${s.mcpUrl}`);
+
+    console.log(`API key: ${s.apiKeyHint}`);
+
+    console.log(`Space:   ${s.spaceName} (${s.spaceId})`);
+
+    console.log(`Thread:  ${s.threadName} (${s.threadId})`);
+
+    if (!s.hasThread) {
+
+      console.log('\nNo thread selected. Run: mantis select thread');
+
+      process.exit(1);
+
+    }
+
+  });
+
+
 
 program
+
   .command('select')
-  .description('Select active Mantis space and thread')
+
+  .description('Select active space and thread')
+
   .argument('[target]', 'space, thread, or both', 'both')
+
   .action(async (target) => {
-    if (target === 'space') return import('./mantis-pick-space.js');
-    if (target === 'thread') return import('./mantis-pick-thread.js');
-    return import('./mantis-select.js');
+
+    if (target === 'space') return selection.pickSpace();
+
+    if (target === 'thread') return selection.pickThread();
+
+    ui.banner('Mantis — switch space / thread');
+
+    await selection.pickSpace();
+
+    await selection.pickThread();
+
+  });
+
+
+
+const spaces = program.command('spaces').description('List, resolve, or set spaces');
+
+
+
+addListOptions(spaces.command('list').description('List spaces (JSON)')).action(async (opts) => {
+
+  try {
+
+    const data = await query.spacesForPrompt(opts.filter || '', { limit: opts.limit, offset: opts.offset });
+
+    console.log(JSON.stringify(data));
+
+  } catch (e) {
+
+    console.error(JSON.stringify({ error: e.message }));
+
+    process.exit(1);
+
+  }
+
+});
+
+
+
+spaces
+
+  .command('resolve')
+
+  .description('Resolve a space link or UUID (JSON)')
+
+  .argument('<query>', 'space link or UUID')
+
+  .action(async (queryText) => {
+
+    try {
+
+      const data = await selection.resolveSpace(queryText);
+
+      console.log(JSON.stringify(data));
+
+    } catch (e) {
+
+      console.error(JSON.stringify({ error: e.message }));
+
+      process.exit(1);
+
+    }
+
+  });
+
+
+
+spaces
+
+  .command('set')
+
+  .description('Set active space by UUID')
+
+  .argument('<uuid>', 'space UUID')
+
+  .argument('[name]', 'display name')
+
+  .action((uuid, name) => console.log(JSON.stringify(selection.setSpace(uuid, name || ''))));
+
+
+
+const threads = program.command('threads').description('List or set threads in the active space');
+
+
+
+addListOptions(threads.command('list').description('List threads (JSON)')).action(async (opts) => {
+
+  try {
+
+    const data = await query.threadsForPrompt(opts.filter || '', { limit: opts.limit, offset: opts.offset });
+
+    console.log(JSON.stringify(data));
+
+  } catch (e) {
+
+    console.error(JSON.stringify({ error: e.message }));
+
+    process.exit(1);
+
+  }
+
+});
+
+
+
+threads
+
+  .command('new')
+
+  .description('Create and activate a new thread')
+
+  .argument('[name]', 'thread name')
+
+  .action(async (name) => {
+
+    try {
+
+      const result = await selection.setThread('--new', name);
+
+      console.log(JSON.stringify(result));
+
+    } catch (e) {
+
+      console.error(e.message || String(e));
+
+      process.exit(1);
+
+    }
+
+  });
+
+
+
+threads
+
+  .command('set')
+
+  .description('Set active thread by UUID')
+
+  .argument('<uuid>', 'thread UUID')
+
+  .argument('[name]', 'display name')
+
+  .action(async (uuid, name) => {
+
+    try {
+
+      const result = await selection.setThread(uuid, name);
+
+      console.log(JSON.stringify(result));
+
+    } catch (e) {
+
+      console.error(e.message || String(e));
+
+      process.exit(1);
+
+    }
+
   });
 
+
+
+const toolsCmd = program.command('tools').description('MCP tools available via mantis use');
+
+toolsCmd.command('list', { isDefault: true }).description('List tools (JSON)').action(async () => {
+
+  try {
+
+    await listTools();
+
+  } catch (e) {
+
+    console.error(JSON.stringify({ error: e.message }));
+
+    process.exit(1);
+
+  }
+
+});
+
+
+
+program
+
+  .command('use <tool>')
+
+  .description('Call a Mantis MCP tool (prints JSON)')
+
+  .allowUnknownOption()
+
+  .action(async () => {
+
+    try {
+
+      const { tool, args } = parseUseCommand(process.argv);
+
+      const result = await tools.useTool(tool, args);
+
+      console.log(JSON.stringify(result, null, 2));
+
+    } catch (e) {
+
+      ui.die(e.message || String(e));
+
+    }
+
+  });
+
+
+
 const create = program.command('create').description('Create Mantis resources from local inputs');
 
+
+
 addMapOptions(create
+
   .command('map')
+
   .description('Create a Mantis map from a local CSV/XLSX file')
+
   .argument('<file>', 'CSV/XLSX file path'))
+
   .action(async (file, opts) => {
+
     try {
+
       if (opts.private) opts.public = false;
-      const result = await createMapFlow(path.resolve(file), opts);
+
+      const result = await map.createMap(path.resolve(file), opts);
+
       console.log(JSON.stringify(result, null, 2));
+
     } catch (e) {
-      die(e.message || String(e));
+
+      ui.die(e.message || String(e));
+
     }
+
   });
 
+
+
 addMapOptions(create
+
   .command('codebase')
+
   .description('Index a local codebase into CSV, optionally creating a Mantis map')
+
   .argument('[root]', 'codebase root', '.')
+
   .option('--out <file>', 'output CSV path')
+
   .option('--max-chars <n>', 'max characters stored per file', (v) => Number(v), 12000)
+
   .option('--create-map', 'create a Mantis map after writing the CSV'))
+
   .action(async (root, opts) => {
+
     try {
+
       if (opts.private) opts.public = false;
+
       const out = path.resolve(opts.out || defaultCodebaseOut(root));
-      const result = await createCodebaseCsv(root, out, { maxChars: opts.maxChars });
-      success(`Indexed ${result.count} files`);
-      info(`CSV: ${result.outFile}`);
+
+      const result = await codebaseIndexer.index(root, out, { maxChars: opts.maxChars });
+
+      ui.success(`Indexed ${result.count} files`);
+
+      ui.info(`CSV: ${result.outFile}`);
+
       if (result.skipped?.length) {
-        info(`Skipped ${result.skipped.length} binary file(s) (e.g. ${result.skipped.slice(0, 3).join(', ')})`);
+
+        ui.info(`Skipped ${result.skipped.length} binary file(s) (e.g. ${result.skipped.slice(0, 3).join(', ')})`);
+
       }
+
       if (opts.createMap) {
-        const mapResult = await createMapFlow(result.outFile, {
+
+        const mapResult = await map.createMap(result.outFile, {
+
           ...opts,
+
           mapName: opts.mapName || `${path.basename(path.resolve(root))} Code Index`,
+
           titleColumn: opts.titleColumn || 'path',
+
           semanticColumn: opts.semanticColumn || 'summary,content,imports',
+
           categoricColumn: opts.categoricColumn || 'language,kind,extension',
+
           numericColumn: opts.numericColumn || 'loc,bytes',
+
         });
+
         console.log(JSON.stringify({ csv: result, map: mapResult }, null, 2));
+
       } else {
+
         console.log(JSON.stringify(result, null, 2));
+
       }
+
     } catch (e) {
-      die(e.message || String(e));
+
+      ui.die(e.message || String(e));
+
     }
+
   });
 
+
+
 program.parseAsync(process.argv);
+

package/lib/constants.js

@@ -0,0 +1,13 @@
+export const DEFAULT_API_BASE = 'https://kellis-h200-1.csail.mit.edu';
+export const DEFAULT_THREAD_NAME = 'Main';
+export const DEVELOPER_PORTAL_URL = 'https://mantis.csail.mit.edu/developer/#keys';
+export const CONFIG_NAME = 'config.json';
+export const BROWSE_PAGE = 20;
+export const API_PAGE = 100;
+
+/** MCP tools disabled in CLI — use `mantis create map` / setup instead */
+export const DISABLED_MCP_TOOLS = new Set([
+  'create_space',
+  'create_map_from_url',
+  'modify_map_from_url',
+]);