@llmtune/cli 0.1.0

package/docs/SKILL_AUTHORING.md

@@ -0,0 +1,175 @@
+# Skill Authoring Guide
+
+Skills are reusable AI workflows that extend the LLMTune CLI. Each skill is defined by a `SKILL.md` file inside a named directory.
+
+## Quick Start
+
+Create a skill in `~/.llmtune/skills/` or `.llmtune/skills/` in your project:
+
+```
+~/.llmtune/skills/
+  my-skill/
+    SKILL.md
+```
+
+## SKILL.md Format
+
+A skill file has two parts: **YAML frontmatter** (optional) and **Markdown body** (the prompt template).
+
+```markdown
+---
+description: "Fix ESLint errors in a file"
+user-invocable: true
+allowed-tools: [read, edit, glob, grep]
+arguments: file_path
+trust: local
+---
+
+You are a linting expert. Fix all ESLint errors in the file at `{{file_path}}`.
+
+1. Read the file
+2. Identify lint errors
+3. Fix each error while preserving the original intent
+4. Report what you changed
+```
+
+## Frontmatter Fields
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `description` | string | (required) | Short description shown in `/skills` list |
+| `user-invocable` | boolean | `true` | Whether users can invoke with `/<skill-name>` |
+| `allowed-tools` | string[] | all tools | Restrict which tools the skill can use |
+| `arguments` | string or string[] | none | Argument names for substitution |
+| `trust` | string | `local` | Trust level: `local`, `community`, `verified`, `signed` |
+| `when-to-use` | string | none | Hint for when the agent should auto-invoke this skill |
+
+## Argument Substitution
+
+Arguments are referenced in the body using `{{arg_name}}` syntax:
+
+```markdown
+---
+arguments: file_path, style
+---
+
+Refactor the file at `{{file_path}}` to use `{{style}}` coding style.
+```
+
+When invoked: `/my-skill src/auth.ts functional`
+
+- `{{file_path}}` becomes `src/auth.ts`
+- `{{style}}` becomes `functional`
+
+## Trust Levels
+
+Skills have four trust levels that determine what tools they can access:
+
+| Level | Tools Allowed | Use Case |
+|-------|--------------|----------|
+| **local** | All | Skills you create yourself in `~/.llmtune/skills/` |
+| **community** | read, glob, grep only | Skills installed from marketplace |
+| **verified** | All | Skills reviewed by the LLMTune team |
+| **signed** | All | Cryptographically signed skills with verified authors |
+
+## Invoking Skills
+
+### From the CLI REPL
+
+```
+> /explain-code src/auth.ts
+> /fix-lint src/utils/helpers.ts
+> /generate-test src/services/user.ts
+```
+
+### From Commander (non-interactive)
+
+```bash
+llmtune skills run explain-code --args "src/auth.ts"
+```
+
+## Built-in Skills
+
+The LLMTune CLI includes these built-in skills:
+
+| Skill | Description | Arguments |
+|-------|-------------|-----------|
+| `explain-code` | Explain code with a clear breakdown | `file_path` |
+| `fix-lint` | Auto-fix linting errors | `file_path` |
+| `generate-test` | Generate unit tests for a file | `file_path` |
+| `security-review` | Review code for security issues | `file_path` |
+
+## Publishing to the Marketplace
+
+```bash
+# Sign your skill
+llmtune skills sign my-skill
+
+# Publish to marketplace
+llmtune skills publish my-skill
+
+# Install from marketplace
+llmtune skills install security-review
+```
+
+## Examples
+
+### Code Review Skill
+
+```markdown
+---
+description: "Review code for best practices and potential issues"
+allowed-tools: [read, glob, grep]
+arguments: file_path
+---
+
+Review the code at `{{file_path}}` for:
+
+1. **Security vulnerabilities** - XSS, injection, auth issues
+2. **Performance problems** - N+1 queries, unnecessary re-renders, memory leaks
+3. **Code quality** - Naming, structure, DRY violations
+4. **Error handling** - Missing error cases, swallowed errors
+5. **Type safety** - Any `any` types, missing null checks
+
+Provide specific, actionable feedback with line numbers.
+```
+
+### Database Migration Skill
+
+```markdown
+---
+description: "Generate a Prisma migration for schema changes"
+allowed-tools: [read, write, edit, bash]
+arguments: description
+---
+
+The user wants to make this database change: {{description}}
+
+1. Read the current prisma/schema.prisma
+2. Make the necessary schema changes
+3. Generate the migration using `npx prisma migrate dev --name <descriptive-name>`
+4. Report what changed
+```
+
+### API Endpoint Skill
+
+```markdown
+---
+description: "Scaffold a new REST API endpoint"
+allowed-tools: [read, write, edit, glob, grep]
+arguments: method, path
+---
+
+Create a new API endpoint:
+
+- Method: `{{method}}`
+- Path: `{{path}}`
+
+1. Find existing route files to understand the pattern
+2. Create the route handler
+3. Add input validation
+4. Add error handling
+5. Register the route
+
+Follow the existing code patterns in the project.
+```

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@llmtune/cli",
+  "version": "0.1.0",
+  "description": "LLMTune CLI - AI coding agent powered by api.llmtune.io",
+  "main": "dist/index.js",
+  "bin": {
+    "llmtune": "dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsx src/index.ts",
+    "start": "node dist/index.js",
+    "lint": "tsc --noEmit"
+  },
+  "keywords": ["llmtune", "cli", "ai", "agent", "coding"],
+  "license": "MIT",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "commander": "^13.1.0",
+    "openai": "^4.78.0",
+    "chalk": "^5.3.0",
+    "ora": "^8.1.0",
+    "@inquirer/prompts": "^7.3.0",
+    "marked": "^15.0.0",
+    "marked-terminal": "^7.3.0",
+    "simple-git": "^3.27.0",
+    "glob": "^11.0.0",
+    "zod": "^3.24.0",
+    "yaml": "^2.6.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.7.0",
+    "tsx": "^4.19.0",
+    "@types/node": "^22.10.0"
+  }
+}

package/src/agent/conversation.ts

@@ -0,0 +1,140 @@
+import crypto from "crypto"
+import fs from "fs"
+import path from "path"
+import os from "os"
+
+export interface Message {
+  role: "system" | "user" | "assistant" | "tool"
+  content: string
+  toolCalls?: ToolCallMessage[]
+  toolCallId?: string
+}
+
+export interface ToolCallMessage {
+  id: string
+  type: "function"
+  function: {
+    name: string
+    arguments: string
+  }
+}
+
+export interface ConversationMeta {
+  id: string
+  createdAt: string
+  updatedAt: string
+  model: string
+  messageCount: number
+  totalTokens?: number
+}
+
+export class Conversation {
+  messages: Message[] = []
+  id: string
+  model: string
+  createdAt: Date
+  totalTokens = 0
+
+  constructor(model: string) {
+    this.id = crypto.randomUUID()
+    this.model = model
+    this.createdAt = new Date()
+  }
+
+  addSystemMessage(content: string): void {
+    this.messages.push({ role: "system", content })
+  }
+
+  addUserMessage(content: string): void {
+    this.messages.push({ role: "user", content })
+  }
+
+  addAssistantMessage(content: string, toolCalls?: ToolCallMessage[]): void {
+    this.messages.push({ role: "assistant", content, toolCalls })
+  }
+
+  addToolResult(toolCallId: string, content: string | Record<string, unknown>, isError?: boolean): void {
+    const text = typeof content === "string" ? content : JSON.stringify(content)
+    this.messages.push({
+      role: "tool",
+      content: isError ? `Error: ${text}` : text,
+      toolCallId,
+    })
+  }
+
+  clear(): void {
+    this.messages = []
+  }
+
+  getApiMessages(): Message[] {
+    return [...this.messages]
+  }
+
+  getTokenEstimate(): number {
+    return this.messages.reduce((total, msg) => {
+      const content =
+        typeof msg.content === "string"
+          ? msg.content
+          : JSON.stringify(msg.content)
+      return total + Math.ceil(content.length / 4)
+    }, 0)
+  }
+
+  getMeta(): ConversationMeta {
+    return {
+      id: this.id,
+      createdAt: this.createdAt.toISOString(),
+      updatedAt: new Date().toISOString(),
+      model: this.model,
+      messageCount: this.messages.length,
+      totalTokens: this.totalTokens || undefined,
+    }
+  }
+
+  save(sessionsDir?: string): string {
+    const dir = sessionsDir || path.join(os.homedir(), ".llmtune", "sessions")
+    fs.mkdirSync(dir, { recursive: true })
+    const filePath = path.join(dir, `${this.id}.json`)
+    const data = {
+      meta: this.getMeta(),
+      messages: this.messages,
+    }
+    fs.writeFileSync(filePath, JSON.stringify(data, null, 2), "utf-8")
+    return filePath
+  }
+
+  static load(filePath: string): Conversation {
+    const raw = fs.readFileSync(filePath, "utf-8")
+    const data = JSON.parse(raw) as {
+      meta: ConversationMeta
+      messages: Message[]
+    }
+    const conv = new Conversation(data.meta.model)
+    conv.id = data.meta.id
+    conv.createdAt = new Date(data.meta.createdAt)
+    conv.messages = data.messages
+    conv.totalTokens = data.meta.totalTokens || 0
+    return conv
+  }
+
+  static listSessions(sessionsDir?: string): ConversationMeta[] {
+    const dir = sessionsDir || path.join(os.homedir(), ".llmtune", "sessions")
+    if (!fs.existsSync(dir)) return []
+    return fs
+      .readdirSync(dir)
+      .filter((f) => f.endsWith(".json"))
+      .map((f) => {
+        try {
+          const raw = fs.readFileSync(path.join(dir, f), "utf-8")
+          return (JSON.parse(raw) as { meta: ConversationMeta }).meta
+        } catch {
+          return null
+        }
+      })
+      .filter((m): m is ConversationMeta => m !== null)
+      .sort(
+        (a, b) =>
+          new Date(b.updatedAt).getTime() - new Date(a.updatedAt).getTime()
+      )
+  }
+}

package/src/agent/loop.ts

@@ -0,0 +1,215 @@
+import OpenAI from "openai"
+import { ToolRegistry, type ToolContext } from "../tools/registry"
+import { Conversation, type ToolCallMessage } from "./conversation"
+import { buildContextPrompt } from "../context/builder"
+import chalk from "chalk"
+
+export interface AgentLoopConfig {
+  model?: string
+  maxTurns?: number
+  verbose?: boolean
+  cwd: string
+  workspaceRoot: string
+}
+
+export interface AgentLoopResult {
+  finalText: string
+  totalToolCalls: number
+  totalTokensIn: number
+  totalTokensOut: number
+  turns: number
+}
+
+export async function runAgentLoop(
+  client: OpenAI,
+  conversation: Conversation,
+  registry: ToolRegistry,
+  userInput: string,
+  config: AgentLoopConfig,
+  onTextChunk?: (text: string) => void
+): Promise<AgentLoopResult> {
+  const model = config.model ?? "z-ai/GLM-5.1"
+  const maxTurns = config.maxTurns ?? 20
+
+  conversation.addUserMessage(userInput)
+
+  const toolSpecs = registry.listSpecs()
+  const openaiTools: OpenAI.ChatCompletionTool[] = toolSpecs.map((spec) => ({
+    type: "function" as const,
+    function: {
+      name: spec.name,
+      description: spec.description,
+      parameters: spec.inputSchema as OpenAI.FunctionParameters,
+    },
+  }))
+
+  const contextResult = await buildContextPrompt(config.workspaceRoot, config.cwd)
+  const contextPrompt = contextResult.prompt
+
+  let totalToolCalls = 0
+  let totalTokensIn = 0
+  let totalTokensOut = 0
+  let turns = 0
+  let finalText = ""
+
+  for (let turn = 0; turn < maxTurns; turn++) {
+    const apiMessages = conversation.getApiMessages()
+    const systemMessage: OpenAI.ChatCompletionSystemMessageParam = {
+      role: "system",
+      content: contextPrompt,
+    }
+
+    const allMessages: OpenAI.ChatCompletionMessageParam[] = [
+      systemMessage,
+      ...apiMessages.map((msg): OpenAI.ChatCompletionMessageParam => {
+        if (msg.role === "system") return { role: "system", content: msg.content }
+        if (msg.role === "user") return { role: "user", content: msg.content }
+        if (msg.role === "assistant") {
+          const m: OpenAI.ChatCompletionAssistantMessageParam = {
+            role: "assistant",
+            content: msg.content || null,
+          }
+          if (msg.toolCalls && msg.toolCalls.length > 0) {
+            m.tool_calls = msg.toolCalls.map((tc): OpenAI.ChatCompletionMessageToolCall => ({
+              id: tc.id,
+              type: "function",
+              function: { name: tc.function.name, arguments: tc.function.arguments },
+            }))
+          }
+          return m
+        }
+        if (msg.role === "tool") {
+          return {
+            role: "tool",
+            tool_call_id: msg.toolCallId ?? "",
+            content: typeof msg.content === "string" ? msg.content : JSON.stringify(msg.content),
+          } as OpenAI.ChatCompletionToolMessageParam
+        }
+        return { role: "user", content: msg.content }
+      }),
+    ]
+
+    const stream = await client.chat.completions.create({
+      model,
+      messages: allMessages,
+      tools: openaiTools.length > 0 ? openaiTools : undefined,
+      stream: true,
+      temperature: 0.7,
+      max_tokens: 16384,
+    })
+
+    let assistantContent = ""
+    const toolCalls: ToolCallMessage[] = []
+    let currentToolCall: { id: string; name: string; arguments: string } | null = null
+
+    for await (const chunk of stream) {
+      const delta = chunk.choices[0]?.delta
+      if (!delta) continue
+
+      if (delta.content) {
+        assistantContent += delta.content
+        if (onTextChunk) onTextChunk(delta.content)
+        else process.stdout.write(delta.content)
+      }
+
+      if (delta.tool_calls) {
+        for (const tc of delta.tool_calls) {
+          if (tc.id && tc.function?.name) {
+            currentToolCall = {
+              id: tc.id,
+              name: tc.function.name,
+              arguments: tc.function.arguments ?? "",
+            }
+            toolCalls.push({
+              id: tc.id,
+              type: "function",
+              function: { name: tc.function.name, arguments: tc.function.arguments ?? "" },
+            })
+          } else if (currentToolCall && tc.function?.arguments) {
+            currentToolCall.arguments += tc.function.arguments
+            const last = toolCalls[toolCalls.length - 1]
+            if (last) last.function.arguments = currentToolCall.arguments
+          }
+        }
+      }
+
+      if (chunk.usage) {
+        totalTokensIn += chunk.usage.prompt_tokens ?? 0
+        totalTokensOut += chunk.usage.completion_tokens ?? 0
+      }
+    }
+
+    if (!onTextChunk) console.log()
+    turns++
+
+    if (toolCalls.length === 0) {
+      conversation.addAssistantMessage(assistantContent)
+      finalText = assistantContent
+      break
+    }
+
+    conversation.addAssistantMessage(assistantContent, toolCalls)
+
+    for (const tc of toolCalls) {
+      totalToolCalls++
+      let toolInput: Record<string, unknown>
+      try {
+        toolInput = JSON.parse(tc.function.arguments)
+      } catch {
+        toolInput = { raw: tc.function.arguments }
+      }
+
+      const summary = summarizeToolInput(tc.function.name, toolInput)
+      console.log(chalk.cyan(`  ▶ ${tc.function.name}`) + chalk.dim(` ${summary}`))
+
+      const toolCtx: ToolContext = {
+        workspaceRoot: config.workspaceRoot,
+        cwd: config.cwd,
+      }
+
+      const result = await registry.dispatch(tc.function.name, toolInput, toolCtx)
+
+      if (result.isError) {
+        console.log(chalk.red(`  ✗ ${tc.function.name}: ${String(result.output).slice(0, 200)}`))
+      } else {
+        console.log(chalk.green(`  ✓ ${summarizeToolResult(tc.function.name, result.output)}`))
+      }
+
+      const resultStr = typeof result.output === "string" ? result.output : JSON.stringify(result.output)
+      conversation.addToolResult(tc.id, resultStr)
+    }
+
+    if (turn === maxTurns - 1) {
+      finalText = "[Max tool turns reached]"
+    }
+  }
+
+  return { finalText, totalToolCalls, totalTokensIn, totalTokensOut, turns }
+}
+
+function summarizeToolInput(name: string, input: Record<string, unknown>): string {
+  const n = name.toLowerCase()
+  if (n === "bash") {
+    const cmd = String(input.command ?? "").replace(/\n/g, " ")
+    return cmd.length > 60 ? cmd.slice(0, 57) + "..." : cmd
+  }
+  if (n === "read" || n === "write" || n === "edit") {
+    return String(input.file_path ?? input.path ?? "")
+  }
+  if (n === "glob") return String(input.pattern ?? "")
+  if (n === "grep") return String(input.pattern ?? "")
+  return ""
+}
+
+function summarizeToolResult(name: string, output: unknown): string {
+  if (typeof output === "string") {
+    return output.length > 100 ? output.slice(0, 97) + "..." : output
+  }
+  if (typeof output === "object" && output !== null) {
+    const obj = output as Record<string, unknown>
+    if (obj.error) return `error: ${String(obj.error).slice(0, 80)}`
+    if (obj.numFiles !== undefined) return `${name} · ${obj.numFiles} results`
+    if (obj.exit_code !== undefined) return `${name} · exit ${obj.exit_code}`
+  }
+  return `${name} completed`
+}

package/src/agent/planner.ts

@@ -0,0 +1,55 @@
+import OpenAI from "openai";
+import type { ChatCompletionMessageParam } from "openai/resources/chat/completions";
+
+const PLANNER_SYSTEM_PROMPT = `You are a tool-use planner. Given a user message and available tools, decide:
+1. Does this request need any tools? (simple questions like "what is 2+2" do not)
+2. If yes, which specific tools are needed?
+3. What is the execution plan?
+
+Respond in this exact JSON format:
+{"needs_tools": boolean, "tools_needed": ["tool_name", ...], "plan": "brief description"}
+
+Only include tools that are actually necessary. Do not over-plan.`;
+
+export interface PlanResult {
+  needsTools: boolean;
+  toolsNeeded: string[];
+  plan: string;
+}
+
+export async function planToolUsage(
+  client: OpenAI,
+  model: string,
+  userMessage: string,
+  availableTools: string[]
+): Promise<PlanResult> {
+  try {
+    const response = await client.chat.completions.create({
+      model,
+      messages: [
+        { role: "system", content: PLANNER_SYSTEM_PROMPT },
+        {
+          role: "user",
+          content: `Available tools: ${availableTools.join(", ")}\n\nUser message: ${userMessage}`,
+        },
+      ],
+      max_tokens: 200,
+      temperature: 0,
+    });
+
+    const content = response.choices[0]?.message?.content?.trim() ?? "";
+    const jsonMatch = content.match(/\{[\s\S]*\}/);
+    if (!jsonMatch) {
+      return { needsTools: true, toolsNeeded: [], plan: "proceed with all tools" };
+    }
+
+    const parsed = JSON.parse(jsonMatch[0]);
+    return {
+      needsTools: parsed.needs_tools ?? true,
+      toolsNeeded: parsed.tools_needed ?? [],
+      plan: parsed.plan ?? "",
+    };
+  } catch {
+    return { needsTools: true, toolsNeeded: [], plan: "" };
+  }
+}

package/src/auth/client.ts

@@ -0,0 +1,19 @@
+import OpenAI from "openai"
+import { loadConfig, getApiBase, getDefaultModel as getDefaultModelConfig } from "./config"
+
+export function createClient(): OpenAI {
+  const apiKey = loadConfig().apiKey as string | undefined
+  if (!apiKey) {
+    console.error("Not logged in. Run: llmtune login")
+    process.exit(1)
+  }
+
+  return new OpenAI({
+    apiKey,
+    baseURL: getApiBase(),
+  })
+}
+
+export function getDefaultModel(): string {
+  return getDefaultModelConfig()
+}