docstar-cli 0.0.0 → 1.0.3

package/dist/commands/init.js

@@ -1,7 +1,7 @@
 import { checkbox } from '@inquirer/prompts';
 import { Args, Command, Flags } from '@oclif/core';
-import { mkdir, writeFile } from 'node:fs/promises';
-import { generateCommandFile, generateListCommandFile } from '../lib/codegen.js';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { generateCommandFile } from '../lib/codegen.js';
 import { configDir, configPath, modulePath } from '../lib/paths.js';
 const buildBaseUrl = (domain) => {
     if (domain.startsWith('http://') || domain.startsWith('https://'))
@@ -15,11 +15,23 @@ const fetchJson = async (url) => {
         throw new Error(`Request to ${url} failed (${response.status} ${response.statusText})`);
     return (await response.json());
 };
+const readSavedConfig = async () => {
+    try {
+        return JSON.parse(await readFile(configPath(), 'utf8'));
+    }
+    catch {
+        return { collections: [] };
+    }
+};
 export default class Init extends Command {
     static args = {
         domain: Args.string({ description: 'DocStar docs domain, e.g. docs.msg91.com or localhost:3000', required: true }),
     };
-    static description = 'Discover published modules for a DocStar docs site, pick which ones to install, and register their CLI commands';
+    static description = [
+        'Discover published modules for a DocStar docs site, pick which ones to install, and register their CLI commands.',
+        'You can run this against multiple docs sites/collections — each is kept separate under its own CLI name (`docstar-cli <cli-name> <module> <command>`).',
+        'After installing, run `docstar-cli list` to see what got installed.',
+    ].join('\n');
     static examples = [
         '<%= config.bin %> <%= command.id %> docs.msg91.com',
         '<%= config.bin %> <%= command.id %> localhost:3000 --collectionId paM4R4A26Hvb',
@@ -35,13 +47,24 @@ export default class Init extends Command {
             listUrl.searchParams.set('collectionId', flags.collectionId);
         this.log(`Fetching modules from ${listUrl.toString()} ...`);
         const listResponse = await fetchJson(listUrl.toString());
+        if (!listResponse.collection?.cliName) {
+            this.error('The docs site did not return a CLI name for this collection. Please update hitman-api/hitman-ui, or set one in the collection settings.');
+        }
         if (!listResponse.modules || listResponse.modules.length === 0) {
             this.log('No published modules found.');
             return;
         }
+        const { cliName } = listResponse.collection;
         const selectedPaths = await checkbox({
-            choices: listResponse.modules.map((module) => ({ checked: true, name: `${module.name} (${module.path})`, value: module.path })),
-            message: 'Select modules to install (space to toggle, enter to confirm)',
+            choices: listResponse.modules.map((module) => {
+                const count = module.endpointCount ?? module.endpoints?.length ?? 0;
+                return {
+                    checked: true,
+                    name: `${module.name} (${module.path}) — ${count} endpoint${count === 1 ? '' : 's'}`,
+                    value: module.path,
+                };
+            }),
+            message: `Select modules to install for "${cliName}" (space to toggle, enter to confirm)`,
         });
         if (selectedPaths.length === 0) {
             this.log('No modules selected, nothing installed.');
@@ -54,26 +77,32 @@ export default class Init extends Command {
             if (flags.collectionId)
                 moduleUrl.searchParams.set('collectionId', flags.collectionId);
             this.log(`Fetching ${path} ...`);
+            // eslint-disable-next-line no-await-in-loop
             const moduleJson = await fetchJson(moduleUrl.toString());
-            await mkdir(configDir() + '/modules', { recursive: true });
-            await writeFile(modulePath(path), JSON.stringify(moduleJson, null, 2));
+            // eslint-disable-next-line no-await-in-loop
+            await mkdir(configDir() + `/modules/${cliName}`, { recursive: true });
+            // eslint-disable-next-line no-await-in-loop
+            await writeFile(modulePath(cliName, path), JSON.stringify(moduleJson, null, 2));
             for (const endpoint of moduleJson.endpoints) {
-                const filePath = await generateCommandFile(this.config.root, path, endpoint);
-                this.log(`  registered command: ${this.config.bin} ${path} ${endpoint.cli.command.name} -> ${filePath}`);
+                // eslint-disable-next-line no-await-in-loop
+                await generateCommandFile(this.config.root, cliName, path, endpoint);
+                this.log(`  registered command: ${this.config.bin} ${cliName} ${path} ${endpoint.cli.command.name}`);
             }
-            await generateListCommandFile(this.config.root, path);
-            this.log(`  registered command: ${this.config.bin} ${path} list`);
             selectedModules.push({ name: moduleJson.module.name, path });
         }
-        const savedConfig = {
+        const collectionConfig = {
             baseUrl,
-            collection: listResponse.collection ?? null,
+            cliName,
             collectionId: flags.collectionId ?? null,
             domain: args.domain,
             modules: selectedModules,
+            name: listResponse.collection.name,
             updatedAt: new Date().toISOString(),
         };
+        const savedConfig = await readSavedConfig();
+        const otherCollections = savedConfig.collections.filter((collection) => collection.cliName !== cliName);
+        savedConfig.collections = [...otherCollections, collectionConfig];
         await writeFile(configPath(), JSON.stringify(savedConfig, null, 2));
-        this.log(`\nInstalled ${selectedModules.length} module(s). Config saved to ${configPath()}`);
+        this.log(`\nInstalled ${selectedModules.length} module(s) for "${cliName}". Config saved to ${configPath()}`);
     }
 }

package/dist/commands/list.d.ts

@@ -0,0 +1,13 @@
+import { Command } from '@oclif/core';
+export default class List extends Command {
+    static args: {
+        collection: import("@oclif/core/interfaces").Arg<string | undefined, Record<string, unknown>>;
+        module: import("@oclif/core/interfaces").Arg<string | undefined, Record<string, unknown>>;
+    };
+    static description: string;
+    static examples: string[];
+    static flags: {
+        all: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+    };
+    run(): Promise<void>;
+}

package/dist/commands/list.js

@@ -0,0 +1,71 @@
+import { Args, Command, Flags } from '@oclif/core';
+import { readFile } from 'node:fs/promises';
+import { loadModule } from '../lib/http.js';
+import { configPath } from '../lib/paths.js';
+export default class List extends Command {
+    static args = {
+        collection: Args.string({ description: 'Show modules installed for this collection (CLI name), e.g. msg91', required: false }),
+        module: Args.string({ description: 'Show all endpoints for this module within the collection, e.g. slack', required: false }),
+    };
+    static description = 'List installed collections, the modules within one, or every endpoint of one module';
+    static examples = [
+        '<%= config.bin %> <%= command.id %>              # list every installed collection',
+        '<%= config.bin %> <%= command.id %> --all        # same as above',
+        '<%= config.bin %> <%= command.id %> msg91         # list modules installed for the "msg91" collection',
+        '<%= config.bin %> <%= command.id %> msg91 slack   # list all of Slack\'s installed endpoints in "msg91"',
+    ];
+    static flags = {
+        all: Flags.boolean({ description: 'List every installed collection (default when no arguments are given)' }),
+    };
+    async run() {
+        const { args } = await this.parse(List);
+        let savedConfig;
+        try {
+            savedConfig = JSON.parse(await readFile(configPath(), 'utf8'));
+        }
+        catch {
+            this.error('No installed modules found. Run `docstar-cli init <domain>` first.');
+        }
+        if (savedConfig.collections.length === 0) {
+            this.log('No collections installed. Run `docstar-cli init <domain>` to install one.');
+            return;
+        }
+        if (!args.collection) {
+            for (const collection of savedConfig.collections) {
+                this.log(`${collection.name} (${collection.cliName}) — ${collection.domain} — ${collection.modules.length} module${collection.modules.length === 1 ? '' : 's'}`);
+            }
+            return;
+        }
+        const collection = savedConfig.collections.find((c) => c.cliName === args.collection);
+        if (!collection) {
+            this.error(`Collection "${args.collection}" isn't installed. Run \`docstar-cli list\` to see installed collections.`);
+        }
+        if (!args.module) {
+            for (const module of collection.modules) {
+                // eslint-disable-next-line no-await-in-loop
+                const moduleJson = await loadModule(collection.cliName, module.path);
+                const count = moduleJson.endpoints.length;
+                this.log(`${module.name} (${module.path}) — ${count} endpoint${count === 1 ? '' : 's'}`);
+            }
+            return;
+        }
+        const moduleJson = await loadModule(collection.cliName, args.module);
+        if (moduleJson.endpoints.length === 0) {
+            this.log(`No endpoints found for module "${args.module}".`);
+            return;
+        }
+        for (const endpoint of moduleJson.endpoints) {
+            const { cli } = endpoint;
+            const aliases = cli.command.aliases.filter((alias) => alias !== cli.command.name);
+            this.log(`${cli.command.name}${aliases.length > 0 ? ` (aliases: ${aliases.join(', ')})` : ''}`);
+            if (cli.description)
+                this.log(`  ${cli.description}`);
+            this.log(`  ${endpoint.method}`);
+            if (cli.parameters.required.length > 0)
+                this.log(`  required: ${cli.parameters.required.join(', ')}`);
+            if (cli.parameters.optional.length > 0)
+                this.log(`  optional: ${cli.parameters.optional.join(', ')}`);
+            this.log('');
+        }
+    }
+}

package/dist/commands/{hello/world.d.ts → mcp.d.ts}

@@ -1,8 +1,6 @@
 import { Command } from '@oclif/core';
-export default class World extends Command {
-    static args: {};
+export default class Mcp extends Command {
     static description: string;
     static examples: string[];
-    static flags: {};
     run(): Promise<void>;
 }

package/dist/commands/mcp.js

@@ -0,0 +1,66 @@
+import { Command } from '@oclif/core';
+import { readFile } from 'node:fs/promises';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+import { executeCliCommand, loadModule } from '../lib/http.js';
+import { configPath } from '../lib/paths.js';
+const sanitize = (value) => value.replaceAll(/[^a-zA-Z0-9_-]/g, '_');
+const buildInputShape = (required, optional) => {
+    const shape = {};
+    for (const name of required)
+        shape[name] = z.string().describe(`Required parameter: ${name}`);
+    for (const name of optional)
+        shape[name] = z.string().optional().describe(`Optional parameter: ${name}`);
+    return shape;
+};
+export default class Mcp extends Command {
+    static description = [
+        'Start an MCP (Model Context Protocol) server exposing every installed endpoint (across all installed collections) as a callable tool for AI clients (Claude Desktop, Claude Code, etc.).',
+        'Each endpoint becomes one tool named `<cli-name>__<module>__<command>`, e.g. `msg91__slack__send-message-1`. Run `docstar-cli init <domain>` first so there is at least one installed module to expose.',
+        'This command does not exit on its own — it stays running and communicates over stdio for as long as the connecting AI client keeps the connection open.',
+    ].join('\n');
+    static examples = [
+        '<%= config.bin %> <%= command.id %>',
+        '# Then register it in an MCP client config, e.g. .mcp.json:',
+        '# { "mcpServers": { "docstar": { "command": "docstar-cli", "args": ["mcp"] } } }',
+    ];
+    async run() {
+        let savedConfig;
+        try {
+            savedConfig = JSON.parse(await readFile(configPath(), 'utf8'));
+        }
+        catch {
+            this.error('No installed modules found. Run `docstar-cli init <domain>` first.');
+        }
+        const server = new McpServer({ name: 'docstar-cli', version: '1.0.0' });
+        let toolCount = 0;
+        for (const collection of savedConfig.collections) {
+            for (const module of collection.modules) {
+                // eslint-disable-next-line no-await-in-loop
+                const moduleJson = await loadModule(collection.cliName, module.path);
+                for (const endpoint of moduleJson.endpoints) {
+                    const { cli } = endpoint;
+                    const toolName = sanitize(`${collection.cliName}__${module.path}__${cli.command.name}`);
+                    const description = cli.description || `${cli.command.name} (${collection.cliName} ${module.path})`;
+                    const inputShape = buildInputShape(cli.parameters.required, cli.parameters.optional);
+                    server.tool(toolName, description, inputShape, async (args) => {
+                        try {
+                            const result = await executeCliCommand(collection.cliName, module.path, cli.command.name, args);
+                            return { content: [{ type: 'text', text: JSON.stringify(result) }] };
+                        }
+                        catch (error) {
+                            return { content: [{ type: 'text', text: error.message }], isError: true };
+                        }
+                    });
+                    toolCount++;
+                }
+            }
+        }
+        if (toolCount === 0) {
+            this.error('No installed endpoints found. Run `docstar-cli init <domain>` and select at least one module first.');
+        }
+        const transport = new StdioServerTransport();
+        await server.connect(transport);
+    }
+}

package/dist/lib/codegen.d.ts

@@ -1,3 +1,2 @@
 import type { EndpointContract } from './types.js';
-export declare const generateCommandFile: (cliRoot: string, modulePathSegment: string, endpoint: EndpointContract) => Promise<string>;
-export declare const generateListCommandFile: (cliRoot: string, modulePathSegment: string) => Promise<string>;
+export declare const generateCommandFile: (cliRoot: string, cliName: string, modulePathSegment: string, endpoint: EndpointContract) => Promise<string>;

package/dist/lib/codegen.js

@@ -3,20 +3,20 @@ import { join } from 'node:path';
 const flagLine = (name, required) => 
 // Required params are collected interactively when missing, so the flag itself stays optional to oclif.
 `    '${name}': Flags.string({description: '${required ? 'Required' : 'Optional'} parameter'}),`;
-const commandFileContent = (modulePathSegment, endpoint) => {
+const commandFileContent = (cliName, modulePathSegment, endpoint) => {
     const { cli } = endpoint;
     const flagLines = [
         ...cli.parameters.required.map((name) => flagLine(name, true)),
         ...cli.parameters.optional.map((name) => flagLine(name, false)),
     ].join('\n');
     return `import {Command, Flags} from '@oclif/core'
-import {executeCliCommand} from '../../lib/http.js'
-import {promptForMissingParams} from '../../lib/prompt.js'
+import {executeCliCommand} from '../../../lib/http.js'
+import {promptForMissingParams} from '../../../lib/prompt.js'
 
 const REQUIRED_PARAMS = ${JSON.stringify(cli.parameters.required)}
 
 export default class Generated extends Command {
-  static description = ${JSON.stringify(cli.description || `${cli.name} (${modulePathSegment})`)}
+  static description = ${JSON.stringify(cli.description || `${cli.name} (${cliName} ${modulePathSegment})`)}
   static aliases = ${JSON.stringify(cli.command.aliases.filter((alias) => alias !== cli.name))}
   static flags = {
 ${flagLines}
@@ -32,7 +32,7 @@ ${flagLines}
     Object.assign(params, await promptForMissingParams(REQUIRED_PARAMS, params))
 
     try {
-      const result = await executeCliCommand('${modulePathSegment}', '${cli.command.name}', params)
+      const result = await executeCliCommand('${cliName}', '${modulePathSegment}', '${cli.command.name}', params)
       this.log(JSON.stringify(result, null, 2))
     } catch (error) {
       this.error(error.message)
@@ -41,38 +41,10 @@ ${flagLines}
 }
 `;
 };
-const listCommandFileContent = (modulePathSegment) => `import {Command} from '@oclif/core'
-import {loadModule} from '../../lib/http.js'
-
-export default class GeneratedList extends Command {
-  static description = 'List installed APIs for the ${modulePathSegment} module'
-
-  async run() {
-    const moduleJson = await loadModule('${modulePathSegment}')
-
-    for (const endpoint of moduleJson.endpoints) {
-      const {cli} = endpoint
-      this.log(\`\${cli.command.name}\${cli.command.aliases.filter((alias) => alias !== cli.command.name).length > 0 ? \` (aliases: \${cli.command.aliases.filter((alias) => alias !== cli.command.name).join(', ')})\` : ''}\`)
-      if (cli.description) this.log(\`  \${cli.description}\`)
-      this.log(\`  \${endpoint.method}\`)
-      if (cli.parameters.required.length > 0) this.log(\`  required: \${cli.parameters.required.join(', ')}\`)
-      if (cli.parameters.optional.length > 0) this.log(\`  optional: \${cli.parameters.optional.join(', ')}\`)
-      this.log('')
-    }
-  }
-}
-`;
-export const generateCommandFile = async (cliRoot, modulePathSegment, endpoint) => {
-    const dir = join(cliRoot, 'dist', 'commands', modulePathSegment);
+export const generateCommandFile = async (cliRoot, cliName, modulePathSegment, endpoint) => {
+    const dir = join(cliRoot, 'dist', 'commands', cliName, modulePathSegment);
     await mkdir(dir, { recursive: true });
     const filePath = join(dir, `${endpoint.cli.command.name}.js`);
-    await writeFile(filePath, commandFileContent(modulePathSegment, endpoint));
-    return filePath;
-};
-export const generateListCommandFile = async (cliRoot, modulePathSegment) => {
-    const dir = join(cliRoot, 'dist', 'commands', modulePathSegment);
-    await mkdir(dir, { recursive: true });
-    const filePath = join(dir, 'list.js');
-    await writeFile(filePath, listCommandFileContent(modulePathSegment));
+    await writeFile(filePath, commandFileContent(cliName, modulePathSegment, endpoint));
     return filePath;
 };

package/dist/lib/http.d.ts

@@ -1,8 +1,8 @@
 import type { EndpointContract, ModuleJson } from './types.js';
 export declare const stripHtml: (value: string | null | undefined) => string;
-export declare const loadModule: (modulePathSegment: string) => Promise<ModuleJson>;
+export declare const loadModule: (cliName: string, modulePathSegment: string) => Promise<ModuleJson>;
 export declare const findEndpoint: (moduleJson: ModuleJson, commandName: string) => EndpointContract | undefined;
-export declare const executeCliCommand: (modulePathSegment: string, commandName: string, params: Record<string, string>) => Promise<{
+export declare const executeCliCommand: (cliName: string, modulePathSegment: string, commandName: string, params: Record<string, string>) => Promise<{
     status: number;
     body: unknown;
 }>;

package/dist/lib/http.js

@@ -4,8 +4,8 @@ import { modulePath } from './paths.js';
 // `<span text-block="true">...</span>`-style markup; unwrap to the raw value.
 export const stripHtml = (value) => (value ?? '').replaceAll(/<[^>]*>/g, '');
 const substitutePlaceholders = (template, params) => Object.entries(params).reduce((result, [key, value]) => result.replaceAll(`:${key}`, value).replaceAll(`{${key}}`, value).replaceAll(`{{${key}}}`, value), template);
-export const loadModule = async (modulePathSegment) => {
-    const raw = await readFile(modulePath(modulePathSegment), 'utf8');
+export const loadModule = async (cliName, modulePathSegment) => {
+    const raw = await readFile(modulePath(cliName, modulePathSegment), 'utf8');
     return JSON.parse(raw);
 };
 export const findEndpoint = (moduleJson, commandName) => moduleJson.endpoints.find((endpoint) => endpoint.cli.command.name === commandName || endpoint.cli.command.aliases.includes(commandName));
@@ -17,14 +17,47 @@ const buildUrl = (endpoint, params) => {
     return `${baseUrl}${path}`;
 };
 const buildHeaders = (endpoint, params) => {
+    // Header names are case-insensitive; the docs editor can end up storing two entries that only
+    // differ by case (e.g. "Content-Type" and "content-type"). Sending both as separate header
+    // lines has been observed to break body parsing on the receiving server, so dedupe by
+    // lowercased name — first entry wins, using its original casing for readability.
+    const seenLowerNames = new Set();
     const headers = {};
     for (const [rawKey, rawValue] of Object.entries(endpoint.headers || {})) {
         const key = stripHtml(rawKey);
+        const lowerKey = key.toLowerCase();
+        if (seenLowerNames.has(lowerKey))
+            continue;
+        seenLowerNames.add(lowerKey);
         const value = stripHtml(rawValue?.value ?? rawValue);
         headers[key] = params[key] ?? value;
     }
     return headers;
 };
+// CLI flag values always arrive as strings, but the JSON body template's existing value for a
+// key tells us its real type (boolean/number/array) — coerce back to that shape instead of
+// clobbering e.g. `getUrl: true` with the literal string "true", or `collectionIds: []` with a
+// plain string.
+const coerceToTemplateType = (existingValue, rawValue) => {
+    if (typeof existingValue === 'boolean')
+        return rawValue === 'true';
+    if (typeof existingValue === 'number') {
+        const parsedNumber = Number(rawValue);
+        return Number.isNaN(parsedNumber) ? rawValue : parsedNumber;
+    }
+    if (Array.isArray(existingValue)) {
+        try {
+            const parsed = JSON.parse(rawValue);
+            if (Array.isArray(parsed))
+                return parsed;
+        }
+        catch {
+            // not a JSON array literal — fall through to comma-splitting
+        }
+        return rawValue.split(',').map((item) => item.trim());
+    }
+    return rawValue;
+};
 const buildBody = (endpoint, params) => {
     const rawValue = endpoint.body?.raw?.value;
     if (endpoint.body?.type !== 'JSON' || !rawValue)
@@ -38,15 +71,15 @@ const buildBody = (endpoint, params) => {
     }
     for (const [key, value] of Object.entries(params)) {
         if (key in parsed)
-            parsed[key] = value;
+            parsed[key] = coerceToTemplateType(parsed[key], value);
     }
     return JSON.stringify(parsed);
 };
-export const executeCliCommand = async (modulePathSegment, commandName, params) => {
-    const moduleJson = await loadModule(modulePathSegment);
+export const executeCliCommand = async (cliName, modulePathSegment, commandName, params) => {
+    const moduleJson = await loadModule(cliName, modulePathSegment);
     const endpoint = findEndpoint(moduleJson, commandName);
     if (!endpoint) {
-        throw new Error(`No endpoint found for command "${commandName}" in module "${modulePathSegment}"`);
+        throw new Error(`No endpoint found for command "${commandName}" in module "${cliName} ${modulePathSegment}"`);
     }
     const url = buildUrl(endpoint, params);
     const headers = buildHeaders(endpoint, params);

package/dist/lib/paths.d.ts

@@ -1,4 +1,5 @@
 export declare const configDir: () => string;
 export declare const configPath: () => string;
 export declare const modulesDir: () => string;
-export declare const modulePath: (modulePathSegment: string) => string;
+export declare const collectionModulesDir: (cliName: string) => string;
+export declare const modulePath: (cliName: string, modulePathSegment: string) => string;

package/dist/lib/paths.js

@@ -3,4 +3,5 @@ import { join } from 'node:path';
 export const configDir = () => join(homedir(), '.docstar');
 export const configPath = () => join(configDir(), 'config.json');
 export const modulesDir = () => join(configDir(), 'modules');
-export const modulePath = (modulePathSegment) => join(modulesDir(), `${modulePathSegment}.json`);
+export const collectionModulesDir = (cliName) => join(modulesDir(), cliName);
+export const modulePath = (cliName, modulePathSegment) => join(collectionModulesDir(cliName), `${modulePathSegment}.json`);

package/dist/lib/types.d.ts

@@ -35,15 +35,26 @@ export type ModuleJson = {
 export type ModuleSummary = {
     name: string;
     path: string;
+    endpointCount?: number;
+    endpoints?: {
+        name: string;
+        path: string;
+    }[];
 };
-export type SavedConfig = {
-    baseUrl: string;
+export type CollectionSummary = {
+    id: string;
+    name: string;
+    cliName: string;
+};
+export type CollectionConfig = {
+    cliName: string;
+    name: string;
     domain: string;
+    baseUrl: string;
     collectionId: string | null;
-    collection: {
-        id: string;
-        name: string;
-    } | null;
     modules: ModuleSummary[];
     updatedAt: string;
 };
+export type SavedConfig = {
+    collections: CollectionConfig[];
+};