@polka-codes/cli 0.6.5 → 0.6.7

package/README.md

@@ -7,97 +7,191 @@
 [![Bun Version](https://img.shields.io/badge/Bun-v1.0.0+-brightgreen)](https://bun.sh)
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue)](https://www.typescriptlang.org)
 
-The Polka Codes CLI provides a powerful command-line interface for interacting with the Polka Codes AI coding assistant framework.
+The Polka Codes CLI provides a powerful command-line interface for interacting with AI-powered coding assistants. It offers features like interactive chat, task execution, commit message generation, and pull request creation.
 
 ## Installation
 
-### Global Installation
-
 ```bash
+# Install globally with npm
 npm install -g @polka-codes/cli
-```
 
-### Run Directly
+# Install globally with yarn
+yarn global add @polka-codes/cli
 
-```bash
+# Install globally with bun
+bun add -g @polka-codes/cli
+
+# Or run directly with npx
 npx @polka-codes/cli
 ```
 
-## Usage
+## Commands
+
+### Interactive Chat
 
-### Basic Commands
+Start an interactive chat session with the AI assistant:
 
 ```bash
-# Run interactive session
-polka-codes
+polka chat
+# or simply
+polka
+```
 
-# Run specific task
-pokla task "improve readme"
+### Task Execution
 
-# Create config file
-pokla config
+Execute a specific task:
 
-# Generate commit message
-pokla commit
+```bash
+polka task "improve error handling in auth module"
+# or pipe input
+echo "optimize database queries" | polka task
 ```
 
-### Commit Command
+### Project Creation
 
-The `commit` subcommand helps generate meaningful commit messages based on your staged changes:
+Create a new project with AI assistance:
 
 ```bash
-# Generate commit message for staged changes
-pokla commit
+polka create my-project
+```
 
-# Generate commit message with specific context
-pokla commit "closes issue #123"
+The command will:
+1. Prompt for project location confirmation
+2. Set up initial project structure
+3. Configure basic dependencies
+4. Generate starter code
+
+### Configuration
 
+Initialize Polka Codes configuration:
+
+```bash
+# Create local config
+polka init
+
+# Create global config
+polka init --global
 ```
 
-### PR Command
+### Git Integration
 
-Create a GitHub pull request with AI-generated details:
+Generate commit messages based on staged changes:
 
 ```bash
-pokla pr "optional message. e.g. closes #123"
+# Generate commit message for staged changes
+polka commit
+
+# Generate commit message with context
+polka commit "closes #123"
+
+# Stage all changes and commit
+polka commit -a
 ```
 
-### Configuration
+Create pull requests with AI-generated details:
 
-Create a `.polkacodes.yml` file in your project root:
+```bash
+# Create PR with current branch changes
+polka pr
 
-```yaml
-# Example configuration
-provider: deepseek
-modelId: deepseek-chat
-commands: # a set of available commands for the AI assistant
-  check: bun check # command
-  test: # command name
-    command: bun test # command to execute
-    description: Run tests. Pass file path to run a specific test file. # description of the command
-rules: |
-  Additional rules for the AI assistant.
+# Create PR with additional context
+polka pr "implements feature #456"
 ```
 
-### AI Configuration
+## Configuration
 
-Supported providers
-1. DeepSeek / `deepseek` (recommended)
-2. Anthropic / `anthropic` (Sonnet 3.5 recommended)
-3. OpenRouter / `openrouter`
-4. Ollama / `ollama`
+### Provider Setup
 
-Configure the AI service by creating a `.env` file in your project root:
+Polka Codes supports multiple AI providers:
+
+1. DeepSeek (Recommended)
+2. Anthropic (Claude 3 Sonnet recommended)
+3. OpenRouter
+4. Ollama
+
+Configure your provider in `.env`:
 
 ```bash
+# Required
 POLKA_API_KEY=your_api_key_here
 
-# Optional - override default model
-POLKA_API_PROVIDER=deepseek # or anthropic, ollama
+# Optional - override defaults
+POLKA_API_PROVIDER=deepseek  # or anthropic, openrouter, ollama
 POLKA_AI_MODEL_ID=deepseek-chat  # or claude-3-sonnet-20240229
 ```
 
----
+### Project Configuration
+
+Create `.polkacodes.yml` in your project root:
+
+```yaml
+# AI provider settings
+provider: deepseek  # default provider
+modelId: deepseek-chat  # default model
+
+# Custom commands available to AI
+commands:
+  test:
+    command: bun test
+    description: Run tests. Pass file path to run specific tests.
+  check:
+    command: bun typecheck
+    description: Run type checker
+  format:
+    command: bun fix
+    description: Format code
+
+# Additional rules/guidelines for AI
+rules: |
+  - Use TypeScript for all new files
+  - Follow project's existing code style
+  - Add tests for new features
+```
+
+### Global vs Local Configuration
+
+- Global config (`~/.config/polkacodes/config.yml`): Store API keys and default settings
+- Local config (`.polkacodes.yml`): Project-specific settings and commands
 
+## Features
+
+- 🤖 Multiple AI provider support
+- 💬 Interactive chat mode
+- 🎯 Task-focused commands
+- 🔄 Git workflow integration
+- 📊 Project analysis and configuration
+- 🛠️ Custom command integration
+- 🔑 Secure API key management
+- 📝 Detailed logging with `--verbose`
+
+## Usage Tips
+
+1. Use interactive mode for complex tasks:
+   ```bash
+   polka chat
+   ```
+
+2. Pipe tasks for automation:
+   ```bash
+   echo "update dependencies" | polka task
+   ```
+
+3. Combine with git workflow:
+   ```bash
+   git add . && polka commit && polka pr
+   ```
+
+4. Monitor AI usage:
+   ```bash
+   polka task "refactor auth" --verbose
+   ```
+
+## Requirements
+
+- Node.js 18+
+- Git (for commit/PR features)
+- GitHub CLI (for PR creation)
+
+---
 
-*This README was generated by polka.codes*
+*This README was generated by polka.codes*

package/dist/index.js

@@ -24629,7 +24629,7 @@ var {
   Help
 } = import__.default;
 // package.json
-var version = "0.6.5";
+var version = "0.6.7";
 
 // ../../node_modules/@anthropic-ai/sdk/version.mjs
 var VERSION = "0.36.2";
@@ -33291,7 +33291,8 @@ var toolInfo = {
         }
       ]
     }
-  ]
+  ],
+  permissionLevel: 0 /* None */
 };
 var handler = async (provider, args2) => {
   if (!provider.askFollowupQuestion) {
@@ -33339,7 +33340,8 @@ var toolInfo2 = {
         }
       ]
     }
-  ]
+  ],
+  permissionLevel: 0 /* None */
 };
 var handler2 = async (provider, args2) => {
   const result = getString(args2, "result");
@@ -33415,7 +33417,8 @@ var toolInfo3 = {
         }
       ]
     }
-  ]
+  ],
+  permissionLevel: 0 /* None */
 };
 var handler3 = async (_provider, args2) => {
   const agentName = getString(args2, "agent_name");
@@ -33470,7 +33473,8 @@ var toolInfo4 = {
         }
       ]
     }
-  ]
+  ],
+  permissionLevel: 3 /* Arbitrary */
 };
 var handler4 = async (provider, args2) => {
   if (!provider.executeCommand) {
@@ -33512,7 +33516,7 @@ var executeCommand_default = {
 // ../core/src/tools/listCodeDefinitionNames.ts
 var toolInfo5 = {
   name: "list_code_definition_names",
-  description: "Request to list definition names (classes, functions, methods, etc.) used in a file. This tool provides insights into the codebase structure and important constructs, encapsulating high-level concepts and relationships that are crucial for understanding the overall architecture.",
+  description: "Request to list definition names (classes, functions, methods, etc.) used for all files in a directory. This tool provides insights into the codebase structure and important constructs, encapsulating high-level concepts and relationships that are crucial for understanding the overall architecture.",
   parameters: [
     {
       name: "path",
@@ -33520,7 +33524,19 @@ var toolInfo5 = {
       required: true,
       usageValue: "Directory path here"
     }
-  ]
+  ],
+  examples: [
+    {
+      description: "Request to list code definition names in a directory",
+      parameters: [
+        {
+          name: "path",
+          value: "src/utils"
+        }
+      ]
+    }
+  ],
+  permissionLevel: 1 /* Read */
 };
 var handler5 = async (provider, args2) => {
   if (!provider.listCodeDefinitionNames) {
@@ -33585,7 +33601,8 @@ var toolInfo6 = {
         }
       ]
     }
-  ]
+  ],
+  permissionLevel: 1 /* Read */
 };
 var handler6 = async (provider, args2) => {
   if (!provider.listFiles) {
@@ -33647,7 +33664,8 @@ var toolInfo7 = {
         }
       ]
     }
-  ]
+  ],
+  permissionLevel: 1 /* Read */
 };
 var handler7 = async (provider, args2) => {
   if (!provider.readFile) {
@@ -33764,7 +33782,8 @@ return (
         }
       ]
     }
-  ]
+  ],
+  permissionLevel: 2 /* Write */
 };
 var handler8 = async (provider, args2) => {
   if (!provider.readFile || !provider.writeFile) {
@@ -33833,7 +33852,8 @@ var toolInfo9 = {
         }
       ]
     }
-  ]
+  ],
+  permissionLevel: 1 /* Read */
 };
 var handler9 = async (provider, args2) => {
   if (!provider.searchFiles) {
@@ -33909,7 +33929,8 @@ export default App;
         }
       ]
     }
-  ]
+  ],
+  permissionLevel: 2 /* Write */
 };
 var handler10 = async (provider, args2) => {
   if (!provider.writeFile) {
@@ -33986,7 +34007,8 @@ var toolInfo11 = {
         }
       ]
     }
-  ]
+  ],
+  permissionLevel: 0 /* None */
 };
 var handler11 = async (_provider, args2) => {
   const agentName = getString(args2, "agent_name");
@@ -34031,7 +34053,8 @@ var toolInfo12 = {
         }
       ]
     }
-  ]
+  ],
+  permissionLevel: 2 /* Write */
 };
 var handler12 = async (provider, args2) => {
   if (!provider.removeFile) {
@@ -34087,7 +34110,8 @@ var toolInfo13 = {
         }
       ]
     }
-  ]
+  ],
+  permissionLevel: 2 /* Write */
 };
 var handler13 = async (provider, args2) => {
   if (!provider.renameFile) {
@@ -34112,8 +34136,8 @@ var renameFile_default = {
   handler: handler13,
   isAvailable: isAvailable13
 };
-// ../core/src/tool.ts
-var getAvailableTools = (provider2, allTools2, hasAgent) => {
+// ../core/src/getAvailableTools.ts
+var getAvailableTools = (provider2, allTools2, hasAgent, permissionLevel) => {
   const tools = [];
   for (const tool of allTools2) {
     if (!hasAgent) {
@@ -34123,7 +34147,7 @@ var getAvailableTools = (provider2, allTools2, hasAgent) => {
           continue;
       }
     }
-    if (tool.isAvailable(provider2)) {
+    if (tool.isAvailable(provider2) && tool.permissionLevel <= permissionLevel) {
       tools.push(tool);
     }
   }
@@ -34438,6 +34462,9 @@ ${agents}`;
     return await this.#processLoop(userMessage);
   }
   async#request(userMessage) {
+    if (!userMessage) {
+      throw new Error("userMessage is missing");
+    }
     await this.#callback({ kind: "StartRequest" /* StartRequest */, agent: this, userMessage });
     this.messages.push({
       role: "user",
@@ -34486,6 +34513,12 @@ ${agents}`;
           case "text":
             break;
           case "tool_use": {
+            if (toolReponses.length > 0) {
+              const toolLevel = this.handlers[content.name].permissionLevel;
+              if (toolLevel > 1 /* Read */) {
+                break outer;
+              }
+            }
             await this.#callback({ kind: "ToolUse" /* ToolUse */, agent: this, tool: content.name });
             const toolResp = await this.#invokeTool(content.name, content.params);
             switch (toolResp.type) {
@@ -34508,7 +34541,7 @@ ${agents}`;
                 return { exit: toolResp };
               case "HandOver" /* HandOver */:
                 if (toolReponses.length > 0) {
-                  continue;
+                  break outer;
                 }
                 await this.#callback({
                   kind: "ToolHandOver" /* ToolHandOver */,
@@ -34539,7 +34572,7 @@ ${agents}`;
           }
         }
       }
-    if (toolReponses.length === 0 && !this.config.interactive) {
+    if (toolReponses.length === 0) {
       return { replay: responsePrompts.requireUseTool };
     }
     const finalResp = toolReponses.map(({ tool, response: response2 }) => responsePrompts.toolResults(tool, response2)).join(`
@@ -34611,18 +34644,8 @@ ${interactiveMode(interactive)}
 // ../core/src/Agent/AnalyzerAgent/index.ts
 class AnalyzerAgent extends AgentBase {
   constructor(options) {
-    const agentTools = [
-      ...options.additionalTools ?? [],
-      askFollowupQuestion_default,
-      attemptCompletion_default,
-      handOver_default,
-      delegate_default,
-      listCodeDefinitionNames_default,
-      listFiles_default,
-      readFile_default,
-      searchFiles_default
-    ];
-    const tools = getAvailableTools(options.provider, agentTools, (options.agents?.length ?? 0) > 0);
+    const combinedTools = [...options.additionalTools ?? [], ...Object.values(exports_allTools)];
+    const tools = getAvailableTools(options.provider, combinedTools, (options.agents?.length ?? 0) > 0, 1 /* Read */);
     const toolNamePrefix = "tool_";
     const systemPrompt = fullSystemPrompt({
       os: options.os
@@ -34711,18 +34734,8 @@ ${interactiveMode(interactive)}
 // ../core/src/Agent/ArchitectAgent/index.ts
 class ArchitectAgent extends AgentBase {
   constructor(options) {
-    const agentTools = [
-      ...options.additionalTools ?? [],
-      askFollowupQuestion_default,
-      attemptCompletion_default,
-      handOver_default,
-      delegate_default,
-      listCodeDefinitionNames_default,
-      listFiles_default,
-      readFile_default,
-      searchFiles_default
-    ];
-    const tools = getAvailableTools(options.provider, agentTools, (options.agents?.length ?? 0) > 0);
+    const combinedTools = [...options.additionalTools ?? [], ...Object.values(exports_allTools)];
+    const tools = getAvailableTools(options.provider, combinedTools, (options.agents?.length ?? 0) > 0, 1 /* Read */);
     const toolNamePrefix = "tool_";
     const systemPrompt = fullSystemPrompt2({
       os: options.os
@@ -34835,7 +34848,7 @@ class CodeFixerAgent extends AgentBase {
   #retryCount = 0;
   constructor(options) {
     const combinedTools = [...options.additionalTools ?? [], ...Object.values(exports_allTools)];
-    const tools = getAvailableTools(options.provider, combinedTools, (options.agents?.length ?? 0) > 0);
+    const tools = getAvailableTools(options.provider, combinedTools, (options.agents?.length ?? 0) > 0, 3 /* Arbitrary */);
     const toolNamePrefix = "tool_";
     const systemPrompt = fullSystemPrompt3({
       os: options.os
@@ -35023,7 +35036,7 @@ ${interactiveMode(interactive)}
 class CoderAgent extends AgentBase {
   constructor(options) {
     const combinedTools = [...options.additionalTools ?? [], ...Object.values(exports_allTools)];
-    const tools = getAvailableTools(options.provider, combinedTools, (options.agents?.length ?? 0) > 0);
+    const tools = getAvailableTools(options.provider, combinedTools, (options.agents?.length ?? 0) > 0, 3 /* Arbitrary */);
     const toolNamePrefix = "tool_";
     const systemPrompt = fullSystemPrompt4({
       os: options.os
@@ -45355,6 +45368,7 @@ var agentSchema = providerModelSchema.extend({
   }).optional()
 });
 var configSchema = z2.object({
+  agent: z2.string().optional(),
   providers: z2.record(z2.string(), z2.object({
     apiKey: z2.string().optional(),
     defaultModel: z2.string().optional()
@@ -45462,11 +45476,25 @@ var readConfig = (path4) => {
   return configSchema.parse(config);
 };
 
+// src/env.ts
+function getEnv(override) {
+  return {
+    POLKA_API_PROVIDER: process.env.POLKA_API_PROVIDER,
+    POLKA_MODEL: process.env.POLKA_MODEL,
+    POLKA_API_KEY: process.env.POLKA_API_KEY,
+    POLKA_BUDGET: process.env.POLKA_BUDGET,
+    ANTHROPIC_API_KEY: process.env.ANTHROPIC_API_KEY,
+    DEEPSEEK_API_KEY: process.env.DEEPSEEK_API_KEY,
+    OPENROUTER_API_KEY: process.env.OPENROUTER_API_KEY,
+    ...override
+  };
+}
+
 // src/options.ts
 function addSharedOptions(command) {
-  return command.option("-c --config <paths>", "Path to config file(s)", (value, prev) => prev.concat(value), []).option("--api-provider <provider>", "API provider").option("--model <model>", "Model ID").option("--api-key <key>", "API key").option("--max-messages <iterations>", "Maximum number of messages to send. Default to 50", Number.parseInt, 50).option("--budget <budget>", "Budget for the AI service. Default to $1000", Number.parseFloat, 1000).option("-v --verbose", "Enable verbose output. Use -v for level 1, -vv for level 2", (value, prev) => prev + 1, 0).option("-d --base-dir <path>", "Base directory to run commands in");
+  return command.option("-c --config <paths>", "Path to config file(s)", (value, prev) => prev.concat(value), []).option("--api-provider <provider>", "API provider").option("--model <model>", "Model ID").option("--api-key <key>", "API key").option("--max-messages <iterations>", "Maximum number of messages to send. Default to 50", Number.parseInt, 50).option("--budget <budget>", "Budget for the AI service. Default to $10", Number.parseFloat).option("-v --verbose", "Enable verbose output. Use -v for level 1, -vv for level 2", (value, prev) => prev + 1, 0).option("-d --base-dir <path>", "Base directory to run commands in").option("--agent <agent>", "Initial agent to use (default: architect)");
 }
-function parseOptions(options, cwdArg, home = os2.homedir()) {
+function parseOptions(options, cwdArg, home = os2.homedir(), env = getEnv()) {
   let cwd = cwdArg;
   if (options.baseDir) {
     process.chdir(options.baseDir);
@@ -45476,23 +45504,26 @@ function parseOptions(options, cwdArg, home = os2.homedir()) {
     cwd = process.cwd();
   }
   const config = loadConfig(options.config, cwd, home) ?? {};
-  const defaultProvider = options.apiProvider || process.env.POLKA_API_PROVIDER || config.defaultProvider;
-  const defaultModel = options.model || process.env.POLKA_MODEL || config.defaultModel;
+  const defaultProvider = options.apiProvider || env.POLKA_API_PROVIDER || config.defaultProvider;
+  const defaultModel = options.model || env.POLKA_MODEL || config.defaultModel;
   if (defaultProvider && defaultModel) {
     import_lodash2.set(config, ["providers", defaultProvider, "defaultModel"], defaultModel);
   }
-  const apiKey = options.apiKey || process.env.POLKA_API_KEY;
+  const apiKey = options.apiKey || env.POLKA_API_KEY;
   if (apiKey) {
     if (!defaultProvider) {
       throw new Error("Must specify a provider if providing an API key");
     }
     import_lodash2.set(config, ["providers", defaultProvider, "apiKey"], apiKey);
   }
-  for (const provider2 of Object.values(AiServiceProvider)) {
-    const providerApiKey = process.env[`${provider2.toUpperCase()}_API_KEY`];
-    if (providerApiKey) {
-      import_lodash2.set(config, ["providers", provider2, "apiKey"], providerApiKey);
-    }
+  if (env.ANTHROPIC_API_KEY) {
+    import_lodash2.set(config, ["providers", "anthropic" /* Anthropic */, "apiKey"], env.ANTHROPIC_API_KEY);
+  }
+  if (env.DEEPSEEK_API_KEY) {
+    import_lodash2.set(config, ["providers", "deepseek" /* DeepSeek */, "apiKey"], env.DEEPSEEK_API_KEY);
+  }
+  if (env.OPENROUTER_API_KEY) {
+    import_lodash2.set(config, ["providers", "openrouter" /* OpenRouter */, "apiKey"], env.OPENROUTER_API_KEY);
   }
   const providerConfig = new ApiProviderConfig({
     defaultProvider,
@@ -45500,10 +45531,11 @@ function parseOptions(options, cwdArg, home = os2.homedir()) {
   });
   return {
     maxMessageCount: options.maxMessageCount ?? config.maxMessageCount ?? 30,
-    budget: options.budget ?? Number(process.env.POLKA_BUDGET) ?? config.budget ?? 1000,
+    budget: options.budget ?? (env.POLKA_BUDGET ? Number.parseFloat(env.POLKA_BUDGET) : undefined) ?? config.budget ?? 10,
     verbose: options.verbose ?? 0,
     config,
-    providerConfig
+    providerConfig,
+    agent: options.agent ?? config.agent ?? "architect"
   };
 }
 
@@ -46099,13 +46131,12 @@ ${event.systemPrompt}`);
 // src/commands/chat.ts
 var runChat = async (opts, command) => {
   const options = command?.parent?.opts() ?? opts ?? {};
-  const { config, providerConfig, maxMessageCount, verbose, budget } = parseOptions(options);
+  const { config, providerConfig, maxMessageCount, verbose, budget, agent } = parseOptions(options);
   if (!process.stdin.isTTY) {
     console.error("Error: Terminal is not interactive. Please run this command in an interactive terminal.");
     process.exit(1);
   }
-  const startAgent = architectAgentInfo.name;
-  let { provider: provider2, model, apiKey } = providerConfig.getConfigForAgent(startAgent) ?? {};
+  let { provider: provider2, model, apiKey } = providerConfig.getConfigForAgent(agent) ?? {};
   if (!provider2) {
     const newConfig = await configPrompt({ provider: provider2, model, apiKey });
     provider2 = newConfig.provider;
@@ -46133,7 +46164,7 @@ var runChat = async (opts, command) => {
         const reason = await runner.continueTask(message);
         exitReason = reason;
       } else {
-        const reason = await runner.startTask(message);
+        const reason = await runner.startTask(message, agent);
         exitReason = reason;
       }
       switch (exitReason.type) {
@@ -47161,9 +47192,8 @@ async function runTask(taskArg, _options, command) {
       process.exit(1);
     }
   }
-  const { config, providerConfig, verbose, maxMessageCount, budget } = parseOptions(command.opts());
-  const startAgent = architectAgentInfo.name;
-  const { provider: provider2, model } = providerConfig.getConfigForAgent(startAgent) ?? {};
+  const { config, providerConfig, verbose, maxMessageCount, budget, agent } = parseOptions(command.opts());
+  const { provider: provider2, model } = providerConfig.getConfigForAgent(agent) ?? {};
   if (!provider2 || !model) {
     console.error("Provider and model must be configured");
     process.exit(1);
@@ -47179,7 +47209,7 @@ async function runTask(taskArg, _options, command) {
     eventCallback: printEvent(verbose),
     enableCache: true
   });
-  await runner.startTask(task, startAgent);
+  await runner.startTask(task, agent);
   runner.printUsage();
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@polka-codes/cli",
-  "version": "0.6.5",
+  "version": "0.6.7",
   "license": "AGPL-3.0",
   "author": "github@polka.codes",
   "type": "module",