docstar-cli 1.0.3 → 1.1.0

package/README.md

@@ -2,6 +2,16 @@
 
 A CLI for calling published DocStar API endpoints directly from your terminal, without leaving the shell to read docs. Point it at a DocStar docs site, pick which modules (e.g. "Slack") you want, and it turns each published endpoint into a real command you can run. You can install from multiple docs sites/collections at once — each is kept separate under its own **CLI name**.
 
+## Concepts: collection → module → endpoint
+
+Every command follows a fixed three-level hierarchy:
+
+1. **Collection** — a docs site, identified by its **CLI name** (e.g. `msg91`). This is what `docstar-cli init` installs.
+2. **Module** — a top-level section within that collection (e.g. `slack`).
+3. **Endpoint** — one published API within a module, turned into a command (e.g. `send-message-1`).
+
+Put together: `docstar-cli <collection> <module> <endpoint> [--flags]`, e.g. `docstar-cli msg91 slack send-message-1 --message "hi"`.
+
 ## Install
 
 ```sh
@@ -26,7 +36,7 @@ For a local/non-custom-domain docs site, pass the collection id explicitly:
 docstar-cli init localhost:3000 --collectionId paM4R4A26Hvb
 ```
 
-This fetches the list of published modules for that collection, shows an interactive checklist (all modules pre-checked — press `space` to toggle, `enter` to confirm), and for each selected module:
+This fetches the list of published modules for that collection and shows an interactive checklist (nothing checked by default — press `space` to toggle a module, or select the **"Select all modules"** entry at the bottom of the list to install everything, then `enter` to confirm). For each selected module it:
 
 - saves its full endpoint contract to `~/.docstar/modules/<cli-name>/<module>.json`
 - registers a real CLI command for every endpoint: `docstar-cli <cli-name> <module> <command>`
@@ -65,6 +75,26 @@ docstar-cli msg91 slack send-message-1
 
 The command prints the response status and body from the actual API call.
 
+### 4. Shell tab-completion
+
+This is a purpose-built completion, not a generic "complete every command" plugin: it **only**
+completes a module name (once you've typed a collection) and an endpoint name (once you've typed
+a collection and module). It never completes the collection name itself, and never completes
+top-level commands like `list`/`init`/`mcp` — you always type the collection by hand.
+
+Set it up once (bash, or zsh with `bashcompinit` loaded):
+
+```sh
+echo 'eval "$(docstar-cli completion-script)"' >> ~/.bashrc   # or ~/.zshrc
+```
+
+Then, after typing a known collection name, `Tab` completes modules and endpoints:
+
+```sh
+docstar-cli msg91 sla<Tab>            # -> slack
+docstar-cli msg91 slack send<Tab>     # -> send-message-1
+```
+
 ## Use from an AI client (MCP)
 
 `docstar-cli` can run as an [MCP](https://modelcontextprotocol.io) server, turning every installed
@@ -88,11 +118,13 @@ Register it with Claude Code (`.mcp.json`) or Claude Desktop (`claude_desktop_co
 }
 ```
 
-Each installed endpoint becomes one tool named `<cli-name>__<module>__<command>` (e.g.
-`msg91__slack__send-message-1`), with required/optional parameters exposed in its schema. A prompt
-like "call the slack api and send a message saying hi" resolves directly to that tool call — the
-AI client asks you for any required value it can't infer, exactly like any other MCP tool. Run
-`docstar-cli init` first so there's at least one installed module for `mcp` to expose.
+Each installed endpoint becomes one tool named `<collection>__<module>__<endpoint>` (e.g.
+`msg91__slack__send-message-1`) — the same collection → module → endpoint hierarchy described
+above, just joined with `__` instead of spaces because MCP tool names can't contain spaces.
+Required/optional parameters are exposed in the tool's schema. A prompt like "call the slack api
+and send a message saying hi" resolves directly to that tool call — the AI client asks you for any
+required value it can't infer, exactly like any other MCP tool. Run `docstar-cli init` first so
+there's at least one installed module for `mcp` to expose.
 
 ## How it works
 

package/dist/commands/complete.d.ts

@@ -0,0 +1,9 @@
+import { Command } from '@oclif/core';
+export default class Complete extends Command {
+    static args: {
+        collection: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
+        module: import("@oclif/core/interfaces").Arg<string | undefined, Record<string, unknown>>;
+    };
+    static hidden: boolean;
+    run(): Promise<void>;
+}

package/dist/commands/complete.js

@@ -0,0 +1,20 @@
+import { Args, Command } from '@oclif/core';
+import { completeEndpoints, completeModules } from '../lib/complete.js';
+// Hidden helper invoked by the shell completion function (see `completion-script`), not meant to
+// be run directly. Prints one suggestion per line: module names for `docstar-cli complete
+// <collection>`, endpoint command names/aliases for `docstar-cli complete <collection> <module>`.
+// Never suggests a collection name or a top-level command — completion only starts once the
+// collection has already been typed.
+export default class Complete extends Command {
+    static args = {
+        collection: Args.string({ required: true }),
+        module: Args.string({ required: false }),
+    };
+    static hidden = true;
+    async run() {
+        const { args } = await this.parse(Complete);
+        const suggestions = args.module ? await completeEndpoints(args.collection, args.module) : await completeModules(args.collection);
+        for (const suggestion of suggestions)
+            this.log(suggestion);
+    }
+}

package/dist/commands/completion-script.d.ts

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

package/dist/commands/completion-script.js

@@ -0,0 +1,39 @@
+import { Command } from '@oclif/core';
+const scriptFor = (bin) => {
+    const fnName = `_${bin.replaceAll(/[^a-zA-Z0-9]/g, '_')}_complete`;
+    return `# zsh doesn't support the bash-style \`complete\` builtin used below until compinit (for
+# compdef) and bashcompinit (for complete/compgen) are both loaded, in that order.
+if [ -n "$ZSH_VERSION" ]; then
+  autoload -Uz compinit && compinit -u
+  autoload -U +X bashcompinit && bashcompinit
+fi
+
+${fnName}() {
+  local cur collection module
+  cur="\${COMP_WORDS[COMP_CWORD]}"
+  collection="\${COMP_WORDS[1]}"
+  module="\${COMP_WORDS[2]}"
+
+  COMPREPLY=()
+
+  if [ "$COMP_CWORD" -eq 2 ] && [ -n "$collection" ]; then
+    COMPREPLY=( $(compgen -W "$(${bin} complete "$collection" 2>/dev/null)" -- "$cur") )
+  elif [ "$COMP_CWORD" -eq 3 ] && [ -n "$collection" ] && [ -n "$module" ]; then
+    COMPREPLY=( $(compgen -W "$(${bin} complete "$collection" "$module" 2>/dev/null)" -- "$cur") )
+  fi
+  # COMP_CWORD 0/1 (the binary name and the collection itself) intentionally get no
+  # suggestions — the collection is always typed out by hand.
+}
+complete -F ${fnName} ${bin}
+`;
+};
+export default class CompletionScript extends Command {
+    static description = [
+        'Print a shell completion function that completes ONLY module names (once a collection is typed) and endpoint names (once a collection and module are typed).',
+        'It never completes the collection name itself, and never completes top-level commands like `list`/`init`/`mcp` — those are typed out by hand.',
+    ].join('\n');
+    static examples = ['echo \'eval "$(<%= config.bin %> <%= command.id %>)"\' >> ~/.bashrc  # or ~/.zshrc'];
+    async run() {
+        this.log(scriptFor(this.config.bin));
+    }
+}

package/dist/commands/init.js

@@ -55,17 +55,22 @@ export default class Init extends Command {
             return;
         }
         const { cliName } = listResponse.collection;
-        const selectedPaths = await checkbox({
-            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,
-                };
-            }),
+        const SELECT_ALL = '__select_all__';
+        const rawSelection = await checkbox({
+            choices: [
+                ...listResponse.modules.map((module) => {
+                    const count = module.endpointCount ?? module.endpoints?.length ?? 0;
+                    return {
+                        checked: false,
+                        name: `${module.name} (${module.path}) — ${count} endpoint${count === 1 ? '' : 's'}`,
+                        value: module.path,
+                    };
+                }),
+                { checked: false, name: '➤ Select all modules', value: SELECT_ALL },
+            ],
             message: `Select modules to install for "${cliName}" (space to toggle, enter to confirm)`,
         });
+        const selectedPaths = rawSelection.includes(SELECT_ALL) ? listResponse.modules.map((module) => module.path) : rawSelection;
         if (selectedPaths.length === 0) {
             this.log('No modules selected, nothing installed.');
             return;

package/dist/commands/mcp.js

@@ -17,7 +17,8 @@ const buildInputShape = (required, optional) => {
 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.',
+        'Every tool follows the collection -> module -> endpoint hierarchy: e.g. collection "msg91" -> module "slack" -> endpoint "send-message-1" becomes the tool `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 = [
@@ -42,7 +43,7 @@ export default class Mcp extends Command {
                 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 description = `[collection: ${collection.cliName} / module: ${module.path}] ${cli.description || cli.command.name}`;
                     const inputShape = buildInputShape(cli.parameters.required, cli.parameters.optional);
                     server.tool(toolName, description, inputShape, async (args) => {
                         try {

package/dist/lib/codegen.js

@@ -2,7 +2,11 @@ import { mkdir, writeFile } from 'node:fs/promises';
 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'}),`;
+// Param names come from endpoint body/param keys authored in a rich-text editor and can contain
+// quotes or HTML markup (e.g. a stray `<span text-block='true'>...`) — JSON.stringify escapes
+// that safely for embedding in generated source; naive string interpolation does not and can
+// produce invalid JS.
+`    ${JSON.stringify(name)}: Flags.string({description: ${JSON.stringify(`${required ? 'Required' : 'Optional'} parameter`)}}),`;
 const commandFileContent = (cliName, modulePathSegment, endpoint) => {
     const { cli } = endpoint;
     const flagLines = [
@@ -32,7 +36,7 @@ ${flagLines}
     Object.assign(params, await promptForMissingParams(REQUIRED_PARAMS, params))
 
     try {
-      const result = await executeCliCommand('${cliName}', '${modulePathSegment}', '${cli.command.name}', params)
+      const result = await executeCliCommand(${JSON.stringify(cliName)}, ${JSON.stringify(modulePathSegment)}, ${JSON.stringify(cli.command.name)}, params)
       this.log(JSON.stringify(result, null, 2))
     } catch (error) {
       this.error(error.message)

package/dist/lib/complete.d.ts

@@ -0,0 +1,2 @@
+export declare const completeModules: (cliName: string) => Promise<string[]>;
+export declare const completeEndpoints: (cliName: string, modulePathSegment: string) => Promise<string[]>;

package/dist/lib/complete.js

@@ -0,0 +1,30 @@
+import { readFile } from 'node:fs/promises';
+import { loadModule } from './http.js';
+import { configPath } from './paths.js';
+const readSavedConfig = async () => {
+    try {
+        return JSON.parse(await readFile(configPath(), 'utf8'));
+    }
+    catch {
+        return { collections: [] };
+    }
+};
+// Suggestions for shell completion — intentionally scoped to module names (given a collection)
+// and endpoint command names/aliases (given a collection + module). Never suggests collection
+// names or top-level commands (list/init/mcp/...); the user is expected to type the collection
+// themselves.
+export const completeModules = async (cliName) => {
+    const savedConfig = await readSavedConfig();
+    const collection = savedConfig.collections.find((c) => c.cliName === cliName);
+    return collection ? collection.modules.map((module) => module.path) : [];
+};
+export const completeEndpoints = async (cliName, modulePathSegment) => {
+    try {
+        const moduleJson = await loadModule(cliName, modulePathSegment);
+        const names = moduleJson.endpoints.flatMap((endpoint) => [endpoint.cli.command.name, ...endpoint.cli.command.aliases]);
+        return [...new Set(names)];
+    }
+    catch {
+        return [];
+    }
+};

package/oclif.manifest.json

@@ -1,5 +1,57 @@
 {
   "commands": {
+    "complete": {
+      "aliases": [],
+      "args": {
+        "collection": {
+          "name": "collection",
+          "required": true
+        },
+        "module": {
+          "name": "module",
+          "required": false
+        }
+      },
+      "flags": {},
+      "hasDynamicHelp": false,
+      "hidden": true,
+      "hiddenAliases": [],
+      "id": "complete",
+      "pluginAlias": "docstar-cli",
+      "pluginName": "docstar-cli",
+      "pluginType": "core",
+      "strict": true,
+      "enableJsonFlag": false,
+      "isESM": true,
+      "relativePath": [
+        "dist",
+        "commands",
+        "complete.js"
+      ]
+    },
+    "completion-script": {
+      "aliases": [],
+      "args": {},
+      "description": "Print a shell completion function that completes ONLY module names (once a collection is typed) and endpoint names (once a collection and module are typed).\nIt never completes the collection name itself, and never completes top-level commands like `list`/`init`/`mcp` — those are typed out by hand.",
+      "examples": [
+        "echo 'eval \"$(<%= config.bin %> <%= command.id %>)\"' >> ~/.bashrc  # or ~/.zshrc"
+      ],
+      "flags": {},
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "completion-script",
+      "pluginAlias": "docstar-cli",
+      "pluginName": "docstar-cli",
+      "pluginType": "core",
+      "strict": true,
+      "enableJsonFlag": false,
+      "isESM": true,
+      "relativePath": [
+        "dist",
+        "commands",
+        "completion-script.js"
+      ]
+    },
     "init": {
       "aliases": [],
       "args": {
@@ -85,7 +137,7 @@
     "mcp": {
       "aliases": [],
       "args": {},
-      "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.).\nEach 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.\nThis 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.",
+      "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.).\nEvery tool follows the collection -> module -> endpoint hierarchy: e.g. collection \"msg91\" -> module \"slack\" -> endpoint \"send-message-1\" becomes the tool `msg91__slack__send-message-1`.\nRun `docstar-cli init <domain>` first so there is at least one installed module to expose.\nThis 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.",
       "examples": [
         "<%= config.bin %> <%= command.id %>",
         "# Then register it in an MCP client config, e.g. .mcp.json:",
@@ -106,118 +158,7 @@
         "commands",
         "mcp.js"
       ]
-    },
-    "api-collection-2:viasocket:send-alert": {
-      "aliases": [],
-      "args": {},
-      "description": "send alert",
-      "flags": {
-        "message": {
-          "description": "Required parameter",
-          "name": "message",
-          "hasDynamicHelp": false,
-          "multiple": false,
-          "type": "option"
-        }
-      },
-      "hasDynamicHelp": false,
-      "hiddenAliases": [],
-      "id": "api-collection-2:viasocket:send-alert",
-      "pluginAlias": "docstar-cli",
-      "pluginName": "docstar-cli",
-      "pluginType": "core",
-      "strict": true,
-      "enableJsonFlag": false,
-      "isESM": true,
-      "relativePath": [
-        "dist",
-        "commands",
-        "api-collection-2",
-        "viasocket",
-        "send-alert.js"
-      ]
-    },
-    "api-collection:slack:send-message-1": {
-      "aliases": [],
-      "args": {},
-      "description": "send message",
-      "flags": {
-        "message": {
-          "description": "Required parameter",
-          "name": "message",
-          "hasDynamicHelp": false,
-          "multiple": false,
-          "type": "option"
-        }
-      },
-      "hasDynamicHelp": false,
-      "hiddenAliases": [],
-      "id": "api-collection:slack:send-message-1",
-      "pluginAlias": "docstar-cli",
-      "pluginName": "docstar-cli",
-      "pluginType": "core",
-      "strict": true,
-      "enableJsonFlag": false,
-      "isESM": true,
-      "relativePath": [
-        "dist",
-        "commands",
-        "api-collection",
-        "slack",
-        "send-message-1.js"
-      ]
-    },
-    "docstar-apis:public-routes:find-matches-1": {
-      "aliases": [],
-      "args": {},
-      "description": "Find matches",
-      "flags": {
-        "query": {
-          "description": "Required parameter",
-          "name": "query",
-          "hasDynamicHelp": false,
-          "multiple": false,
-          "type": "option"
-        },
-        "collectionIds": {
-          "description": "Required parameter",
-          "name": "collectionIds",
-          "hasDynamicHelp": false,
-          "multiple": false,
-          "type": "option"
-        },
-        "getUrl": {
-          "description": "Required parameter",
-          "name": "getUrl",
-          "hasDynamicHelp": false,
-          "multiple": false,
-          "type": "option"
-        },
-        "allowNonDomain": {
-          "description": "Required parameter",
-          "name": "allowNonDomain",
-          "hasDynamicHelp": false,
-          "multiple": false,
-          "type": "option"
-        }
-      },
-      "hasDynamicHelp": false,
-      "hiddenAliases": [],
-      "id": "docstar-apis:public-routes:find-matches-1",
-      "pluginAlias": "docstar-cli",
-      "pluginName": "docstar-cli",
-      "pluginType": "core",
-      "strict": true,
-      "enableJsonFlag": false,
-      "isESM": true,
-      "relativePath": [
-        "dist",
-        "commands",
-        "docstar-apis",
-        "public-routes",
-        "find-matches-1.js"
-      ]
     }
   },
-  "version": "1.0.3"
+  "version": "1.1.0"
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "docstar-cli",
   "description": "Call published DocStar API endpoints directly from your terminal, or expose them as MCP tools for AI clients.",
-  "version": "1.0.3",
+  "version": "1.1.0",
   "author": "Swayam Maheshwari",
   "bin": {
     "docstar-cli": "./bin/run.js"

package/dist/commands/api-collection/slack/send-message-1.js

@@ -1,30 +0,0 @@
-import {Command, Flags} from '@oclif/core'
-import {executeCliCommand} from '../../../lib/http.js'
-import {promptForMissingParams} from '../../../lib/prompt.js'
-
-const REQUIRED_PARAMS = ["message"]
-
-export default class Generated extends Command {
-  static description = "send message"
-  static aliases = []
-  static flags = {
-    'message': Flags.string({description: 'Required parameter'}),
-  }
-
-  async run() {
-    const {flags} = await this.parse(Generated)
-    const params = {}
-    for (const [key, value] of Object.entries(flags)) {
-      if (value !== undefined) params[key] = value
-    }
-
-    Object.assign(params, await promptForMissingParams(REQUIRED_PARAMS, params))
-
-    try {
-      const result = await executeCliCommand('api-collection', 'slack', 'send-message-1', params)
-      this.log(JSON.stringify(result, null, 2))
-    } catch (error) {
-      this.error(error.message)
-    }
-  }
-}

package/dist/commands/api-collection-2/viasocket/send-alert.js

@@ -1,30 +0,0 @@
-import {Command, Flags} from '@oclif/core'
-import {executeCliCommand} from '../../../lib/http.js'
-import {promptForMissingParams} from '../../../lib/prompt.js'
-
-const REQUIRED_PARAMS = ["message"]
-
-export default class Generated extends Command {
-  static description = "send alert"
-  static aliases = []
-  static flags = {
-    'message': Flags.string({description: 'Required parameter'}),
-  }
-
-  async run() {
-    const {flags} = await this.parse(Generated)
-    const params = {}
-    for (const [key, value] of Object.entries(flags)) {
-      if (value !== undefined) params[key] = value
-    }
-
-    Object.assign(params, await promptForMissingParams(REQUIRED_PARAMS, params))
-
-    try {
-      const result = await executeCliCommand('api-collection-2', 'viasocket', 'send-alert', params)
-      this.log(JSON.stringify(result, null, 2))
-    } catch (error) {
-      this.error(error.message)
-    }
-  }
-}

package/dist/commands/docstar-apis/public-routes/find-matches-1.js

@@ -1,33 +0,0 @@
-import {Command, Flags} from '@oclif/core'
-import {executeCliCommand} from '../../../lib/http.js'
-import {promptForMissingParams} from '../../../lib/prompt.js'
-
-const REQUIRED_PARAMS = ["query","collectionIds","getUrl","allowNonDomain"]
-
-export default class Generated extends Command {
-  static description = "Find matches"
-  static aliases = []
-  static flags = {
-    'query': Flags.string({description: 'Required parameter'}),
-    'collectionIds': Flags.string({description: 'Required parameter'}),
-    'getUrl': Flags.string({description: 'Required parameter'}),
-    'allowNonDomain': Flags.string({description: 'Required parameter'}),
-  }
-
-  async run() {
-    const {flags} = await this.parse(Generated)
-    const params = {}
-    for (const [key, value] of Object.entries(flags)) {
-      if (value !== undefined) params[key] = value
-    }
-
-    Object.assign(params, await promptForMissingParams(REQUIRED_PARAMS, params))
-
-    try {
-      const result = await executeCliCommand('docstar-apis', 'public-routes', 'find-matches-1', params)
-      this.log(JSON.stringify(result, null, 2))
-    } catch (error) {
-      this.error(error.message)
-    }
-  }
-}