@miphamai/cli 0.2.3

package/src/skills/standard/runtime.ts

@@ -0,0 +1,59 @@
+import type { SkillDefinition } from '../../shared/index.ts'
+
+export interface StandardRuntimeContext {
+  skill: SkillDefinition
+  cwd: string
+  sessionId: string
+}
+
+/**
+ * Standard skill runtime — executes SKILL.md definitions.
+ * Standard skills follow the open-source SKILL.md specification.
+ */
+export class StandardRuntime {
+  private context: StandardRuntimeContext
+
+  constructor(context: StandardRuntimeContext) {
+    this.context = context
+  }
+
+  getSkill(): SkillDefinition {
+    return this.context.skill
+  }
+
+  getPrompts(): Record<string, string> {
+    return this.context.skill.prompts || {}
+  }
+
+  getPrompt(name: string): string | undefined {
+    return this.context.skill.prompts?.[name]
+  }
+
+  getTools(): SkillDefinition['tools'] {
+    return this.context.skill.tools || []
+  }
+
+  getHooks(): SkillDefinition['hooks'] {
+    return this.context.skill.hooks || []
+  }
+
+  /**
+   * Execute a named prompt from the skill.
+   * Returns the prompt text with any variable substitution applied.
+   */
+  async executePrompt(name: string, variables?: Record<string, string>): Promise<string> {
+    const prompt = this.getPrompt(name)
+    if (!prompt) {
+      throw new Error(`Prompt "${name}" not found in skill "${this.context.skill.name}"`)
+    }
+
+    let result = prompt
+    if (variables) {
+      for (const [key, value] of Object.entries(variables)) {
+        result = result.replaceAll(`\${${key}}`, value)
+      }
+    }
+
+    return result
+  }
+}

package/src/tools/agent/agent.ts

@@ -0,0 +1,51 @@
+import type { ToolDefinition } from '../../shared/index.ts'
+import { SubAgent, type SubAgentType } from '../../agent/sub-agent'
+
+const VALID_TYPES: SubAgentType[] = ['general', 'explore', 'plan', 'code-review']
+
+export const agentTool: ToolDefinition = {
+  name: 'Agent',
+  description:
+    'Launch a sub-agent to handle complex, multi-step tasks independently. Available types: general, explore, plan, code-review.',
+  category: 'agent',
+  permission: 'ask',
+  parameters: {
+    type: 'object',
+    properties: {
+      description: { type: 'string', description: 'Short description of the task' },
+      prompt: { type: 'string', description: 'The task for the agent to perform' },
+      subagent_type: {
+        type: 'string',
+        description: 'Type: general (default), explore (code search), plan (design), code-review',
+      },
+    },
+    required: ['description', 'prompt'],
+  },
+  async execute(params, ctx) {
+    const description = params.description as string
+    const prompt = params.prompt as string
+    const agentType = (params.subagent_type as SubAgentType) || 'general'
+
+    if (!VALID_TYPES.includes(agentType)) {
+      return {
+        success: false,
+        content: '',
+        error: `Invalid subagent_type "${agentType}". Valid types: ${VALID_TYPES.join(', ')}`,
+      }
+    }
+
+    const registry = ctx.registry
+    if (!registry) {
+      // No registry in context — return structured simulation
+      const sub = new SubAgent(
+        null as unknown as import('../../providers/registry').ProviderRegistry,
+      )
+      const result = await sub.execute(prompt, description, { type: agentType })
+      return { success: true, content: result }
+    }
+
+    const sub = new SubAgent(registry)
+    const result = await sub.execute(prompt, description, { type: agentType })
+    return { success: true, content: result }
+  },
+}

package/src/tools/agent/memory.ts

@@ -0,0 +1,51 @@
+import { readFileSync, writeFileSync, mkdirSync, existsSync, readdirSync } from 'node:fs'
+import { join } from 'node:path'
+import type { ToolDefinition } from '../../shared/index.ts'
+
+const MEMORY_DIR = join(process.env.HOME || '~', '.mipham', 'memory')
+
+export const memoryTool: ToolDefinition = {
+  name: 'Memory',
+  description: 'Read and write persistent memory files in ~/.mipham/memory/.',
+  category: 'agent',
+  permission: 'auto',
+  parameters: {
+    type: 'object',
+    properties: {
+      action: {
+        type: 'string',
+        enum: ['read', 'write', 'list'],
+        description: 'Action to perform',
+      },
+      name: { type: 'string', description: 'Memory file name (slug)' },
+      content: { type: 'string', description: 'Content to write (for write action)' },
+    },
+    required: ['action'],
+  },
+  async execute(params, _ctx) {
+    const action = params.action as string
+    mkdirSync(MEMORY_DIR, { recursive: true })
+
+    if (action === 'list') {
+      const files = readdirSync(MEMORY_DIR).filter((f) => f.endsWith('.md'))
+      return { success: true, content: files.join('\n') || '(no memories)' }
+    }
+
+    const name = params.name as string
+    if (!name) return { success: false, content: '', error: 'name is required' }
+    const filePath = join(MEMORY_DIR, `${name}.md`)
+
+    if (action === 'read') {
+      if (!existsSync(filePath))
+        return { success: false, content: '', error: `Memory "${name}" not found` }
+      return { success: true, content: readFileSync(filePath, 'utf-8') }
+    }
+
+    if (action === 'write') {
+      writeFileSync(filePath, params.content as string, 'utf-8')
+      return { success: true, content: `Memory "${name}" written` }
+    }
+
+    return { success: false, content: '', error: `Unknown action: ${action}` }
+  },
+}

package/src/tools/agent/plan.ts

@@ -0,0 +1,87 @@
+import { mkdirSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+import type { ToolDefinition } from '../../shared/index.ts'
+
+export const planTool: ToolDefinition = {
+  name: 'Plan',
+  description:
+    'Enter plan mode — read-only analysis and design. Creates a structured plan file in .mipham/plans/.',
+  category: 'agent',
+  permission: 'auto',
+  parameters: {
+    type: 'object',
+    properties: {
+      title: {
+        type: 'string',
+        description: 'Plan title (e.g., "Add user authentication")',
+      },
+      description: {
+        type: 'string',
+        description: 'Brief description of what the plan should cover',
+      },
+    },
+  },
+  async execute(params, ctx) {
+    const title = (params.title as string) || 'Implementation Plan'
+    const description = (params.description as string) || ''
+
+    const planDir = join(ctx.cwd, '.mipham', 'plans')
+    mkdirSync(planDir, { recursive: true })
+
+    const timestamp = new Date().toISOString().replace(/[:.]/g, '-').slice(0, 19)
+    const filename = `plan-${timestamp}.md`
+    const filepath = join(planDir, filename)
+
+    const content = [
+      `# ${title}`,
+      '',
+      `> Generated: ${new Date().toISOString()}`,
+      `> Status: Draft`,
+      description ? `> ${description}` : '',
+      '',
+      '## Overview',
+      '',
+      '[Describe what this plan aims to achieve]',
+      '',
+      '## Files to Modify',
+      '',
+      '| File | Change | Reason |',
+      '|------|--------|--------|',
+      '|      |        |        |',
+      '',
+      '## Implementation Steps',
+      '',
+      '1. ',
+      '2. ',
+      '3. ',
+      '',
+      '## Verification',
+      '',
+      '- [ ] Tests pass',
+      '- [ ] Typecheck passes',
+      '- [ ] Manual verification',
+      '',
+      '## Notes',
+      '',
+      '[Any additional context, risks, or dependencies]',
+    ].join('\n')
+
+    writeFileSync(filepath, content, 'utf-8')
+
+    return {
+      success: true,
+      content: [
+        `── Plan Mode Activated ──`,
+        ``,
+        `Plan file: ${filepath}`,
+        `Directory: ${planDir}`,
+        ``,
+        `The plan template has been created. Edit ${filename} to fill in the details.`,
+        `Use /no-plan to exit plan mode.`,
+        ``,
+        `Plan mode is read-only — the AI will analyze and design without`,
+        `executing code changes until you explicitly approve the plan.`,
+      ].join('\n'),
+    }
+  },
+}

package/src/tools/agent/skill.ts

@@ -0,0 +1,58 @@
+import type { ToolDefinition } from '../../shared/index.ts'
+
+export const skillTool: ToolDefinition = {
+  name: 'Skill',
+  description:
+    'Execute a skill (.SKILL.md or .mipham-skill.md) by name. Skills extend AI capabilities with specialized instructions.',
+  category: 'agent',
+  permission: 'auto',
+  parameters: {
+    type: 'object',
+    properties: {
+      skill: { type: 'string', description: 'Name of the skill to invoke' },
+      args: { type: 'string', description: 'Optional arguments for the skill' },
+    },
+    required: ['skill'],
+  },
+  async execute(params, ctx) {
+    const skillName = params.skill as string
+    const args = (params.args as string) || ''
+
+    // Try to load the skill via SkillsLoader if available
+    const loader = ctx.skillsLoader
+    if (loader) {
+      const skill = loader.get(skillName)
+      if (!skill) {
+        const available = loader
+          .list()
+          .map((s) => `  • ${s.name} (${s.type})`)
+          .join('\n')
+        return {
+          success: false,
+          content: '',
+          error: `Skill "${skillName}" not found.\n\nAvailable skills (${loader.list().length}):\n${available}\n\nUse /skills to browse, or create a .SKILL.md file in .mipham/skills/.`,
+        }
+      }
+
+      // Build skill invocation content
+      const lines: string[] = [
+        `── Skill Invoked: ${skill.name} ──`,
+        `Type: ${skill.type} | Version: ${skill.version}`,
+        skill.description ? `Description: ${skill.description}` : '',
+        args ? `Arguments: ${args}` : '',
+        '',
+        'The AI should now follow the instructions from this skill.',
+        'Skill content has been loaded into context.',
+      ].filter(Boolean)
+
+      return { success: true, content: lines.join('\n') }
+    }
+
+    // Fallback: no SkillsLoader in context
+    return {
+      success: false,
+      content: '',
+      error: `SkillsLoader not available. The skill "${skillName}" cannot be loaded.\n\nSkills are loaded from:\n  • skills/standard/*.SKILL.md (built-in)\n  • skills/mipham/*.mipham-skill.md (Mipham exclusive)\n  • .mipham/skills/ (project custom)`,
+    }
+  },
+}

package/src/tools/exec/bash.ts

@@ -0,0 +1,111 @@
+import type { ToolDefinition } from '../../shared/index.ts'
+
+// ── Dangerous command patterns ──
+const BLOCKED_PATTERNS = [
+  // Recursive root deletion without preserve-root safeguard
+  /\brm\s+-rf\s+\/(\s|$)/,
+  /\brm\s+-rf\s+\/\*\s*$/,
+  // Filesystem manipulation
+  /\bmkfs\./,
+  /\bdd\s+if=/,
+  // Fork bomb
+  /:\s*\(\s*\)\s*\{\s*:\s*\|/,
+  // Recursive root chmod
+  /\bchmod\s+.*777\s+\//,
+  // Direct block device write
+  />\s*\/dev\/sd[a-z]/,
+  // SSH private key theft
+  /\bcat\s+.*\/\.ssh\/id_/,
+]
+
+const BLOCKED_COMMANDS = [
+  'mkfs',
+  'mkfs.ext2',
+  'mkfs.ext3',
+  'mkfs.ext4',
+  'mkfs.xfs',
+  'mkfs.btrfs',
+  'mkfs.fat',
+  'mkfs.vfat',
+  'mkswap',
+]
+
+function isBlocked(command: string): string | null {
+  // Check exact blocked commands
+  const firstWord = command.trim().split(/\s+/)[0]
+  if (firstWord && BLOCKED_COMMANDS.includes(firstWord)) {
+    return `Command "${firstWord}" is blocked (destructive filesystem operation).`
+  }
+
+  // Check dangerous patterns
+  for (const pattern of BLOCKED_PATTERNS) {
+    if (pattern.test(command)) {
+      return `Command rejected by security policy. Pattern matched: ${pattern.source.slice(0, 40)}...`
+    }
+  }
+
+  return null // safe
+}
+
+export const bashTool: ToolDefinition = {
+  name: 'Bash',
+  description:
+    'Execute a bash command. Returns stdout and stderr. Timeout: 120s. Use with caution.',
+  category: 'exec',
+  permission: 'ask',
+  parameters: {
+    type: 'object',
+    properties: {
+      command: { type: 'string', description: 'The bash command to execute' },
+      description: {
+        type: 'string',
+        description: 'What this command does (for audit log)',
+      },
+      timeout: {
+        type: 'integer',
+        description: 'Timeout in milliseconds (max 600000)',
+      },
+    },
+    required: ['command'],
+  },
+  async execute(params, ctx) {
+    const command = params.command as string
+    const timeout = Math.min((params.timeout as number) || 120_000, 600_000)
+
+    // Security: check command against deny list
+    const blockedReason = isBlocked(command)
+    if (blockedReason) {
+      return { success: false, content: '', error: blockedReason }
+    }
+
+    try {
+      const proc = Bun.spawn(['bash', '-c', command], {
+        cwd: ctx.cwd,
+        stdout: 'pipe',
+        stderr: 'pipe',
+      })
+
+      const timer = setTimeout(() => proc.kill(), timeout)
+      const output = await new Response(proc.stdout).text()
+      const exitCode = await proc.exited
+      clearTimeout(timer)
+
+      if (exitCode !== 0) {
+        const stderr = await new Response(proc.stderr).text()
+        return {
+          success: false,
+          content: output.slice(0, 5_000),
+          error: `Exit code ${exitCode}: ${stderr.slice(0, 1_000)}`,
+        }
+      }
+
+      return { success: true, content: output.slice(0, 100_000) || '(no output)' }
+    } catch (err) {
+      return {
+        success: false,
+        content: '',
+        error: `Command failed: ${String(err)}`,
+      }
+    }
+  },
+}

package/src/tools/exec/git.ts

@@ -0,0 +1,63 @@
+import type { ToolDefinition } from '../../shared/index.ts'
+
+const DANGEROUS_COMMANDS = ['push --force', 'reset --hard', 'clean -fd', 'branch -D']
+
+export const gitTool: ToolDefinition = {
+  name: 'Git',
+  description: 'Execute git commands. Dangerous operations (force push, hard reset) are blocked.',
+  category: 'exec',
+  permission: 'auto',
+  parameters: {
+    type: 'object',
+    properties: {
+      command: {
+        type: 'string',
+        description: 'Git subcommand + args (e.g., "status", "log --oneline")',
+      },
+    },
+    required: ['command'],
+  },
+  async execute(params, ctx) {
+    const command = params.command as string
+
+    for (const dangerous of DANGEROUS_COMMANDS) {
+      if (command.includes(dangerous)) {
+        return {
+          success: false,
+          content: '',
+          error: `Dangerous git command blocked: "${dangerous}". Run manually if intended.`,
+        }
+      }
+    }
+
+    try {
+      const proc = Bun.spawn(['git', ...command.split(/\s+/)], {
+        cwd: ctx.cwd,
+        stdout: 'pipe',
+        stderr: 'pipe',
+      })
+      const output = await new Response(proc.stdout).text()
+      const exitCode = await proc.exited
+
+      if (exitCode !== 0) {
+        const stderr = await new Response(proc.stderr).text()
+        return {
+          success: false,
+          content: '',
+          error: `Git error (exit ${exitCode}): ${stderr.slice(0, 1000)}`,
+        }
+      }
+
+      return {
+        success: true,
+        content: output.slice(0, 50_000) || '(no output)',
+      }
+    } catch (err) {
+      return {
+        success: false,
+        content: '',
+        error: `Git execution failed: ${String(err)}`,
+      }
+    }
+  },
+}

package/src/tools/exec/task.ts

@@ -0,0 +1,69 @@
+import type { ToolDefinition } from '../../shared/index.ts'
+
+interface Task {
+  id: string
+  subject: string
+  description: string
+  status: 'pending' | 'in_progress' | 'completed'
+}
+
+const tasks = new Map<string, Task>()
+let taskCounter = 0
+
+export const taskTool: ToolDefinition = {
+  name: 'Task',
+  description: 'Create and manage structured task lists for tracking progress.',
+  category: 'exec',
+  permission: 'auto',
+  parameters: {
+    type: 'object',
+    properties: {
+      action: {
+        type: 'string',
+        enum: ['create', 'list', 'update'],
+        description: 'Action to perform',
+      },
+      subject: { type: 'string', description: 'Task subject (for create)' },
+      description: { type: 'string', description: 'Task description (for create)' },
+      taskId: { type: 'string', description: 'Task ID (for update)' },
+      status: {
+        type: 'string',
+        enum: ['pending', 'in_progress', 'completed'],
+        description: 'New status (for update)',
+      },
+    },
+    required: ['action'],
+  },
+  async execute(params, _ctx) {
+    const action = params.action as string
+
+    if (action === 'create') {
+      const id = String(++taskCounter)
+      const subject = (params.subject as string) || 'Untitled'
+      tasks.set(id, {
+        id,
+        subject,
+        description: (params.description as string) || '',
+        status: 'pending',
+      })
+      return { success: true, content: `Task #${id} created: ${subject}` }
+    }
+
+    if (action === 'list') {
+      const list = Array.from(tasks.values())
+        .map((t) => `[${t.status}] #${t.id}: ${t.subject}`)
+        .join('\n')
+      return { success: true, content: list || '(no tasks)' }
+    }
+
+    if (action === 'update') {
+      const taskId = params.taskId as string
+      const task = tasks.get(taskId)
+      if (!task) return { success: false, content: '', error: `Task #${taskId} not found` }
+      if (params.status) task.status = params.status as Task['status']
+      return { success: true, content: `Task #${taskId} updated: ${task.status}` }
+    }
+
+    return { success: false, content: '', error: `Unknown action: ${action}` }
+  },
+}

package/src/tools/file/edit.ts

@@ -0,0 +1,57 @@
+import { readFileSync, writeFileSync } from 'node:fs'
+import type { ToolDefinition } from '../../shared/index.ts'
+import { resolveSafe } from '../../security/path'
+
+export const editTool: ToolDefinition = {
+  name: 'Edit',
+  description:
+    'Perform exact string replacement in a file. old_string must match exactly and be unique.',
+  category: 'file',
+  permission: 'ask',
+  parameters: {
+    type: 'object',
+    properties: {
+      file_path: { type: 'string' },
+      old_string: { type: 'string' },
+      new_string: { type: 'string' },
+      replace_all: { type: 'boolean', default: false },
+    },
+    required: ['file_path', 'old_string', 'new_string'],
+  },
+  async execute(params, ctx) {
+    const filePath = resolveSafe(ctx.cwd, params.file_path as string)
+    const oldStr = params.old_string as string
+    const newStr = params.new_string as string
+    const replaceAll = params.replace_all as boolean
+
+    const content = readFileSync(filePath, 'utf-8')
+
+    if (replaceAll) {
+      if (!content.includes(oldStr)) {
+        return { success: false, content: '', error: 'old_string not found in file' }
+      }
+      const updated = content.replaceAll(oldStr, newStr)
+      writeFileSync(filePath, updated, 'utf-8')
+      const count = content.split(oldStr).length - 1
+      return { success: true, content: `Replaced ${count} occurrences in ${filePath}` }
+    }
+
+    const firstIndex = content.indexOf(oldStr)
+    if (firstIndex === -1) {
+      return { success: false, content: '', error: 'old_string not found in file' }
+    }
+    const secondIndex = content.indexOf(oldStr, firstIndex + 1)
+    if (secondIndex !== -1) {
+      return {
+        success: false,
+        content: '',
+        error: 'old_string is not unique in file. Use replace_all or make it more specific.',
+      }
+    }
+
+    const updated =
+      content.slice(0, firstIndex) + newStr + content.slice(firstIndex + oldStr.length)
+    writeFileSync(filePath, updated, 'utf-8')
+    return { success: true, content: `Replaced 1 occurrence in ${filePath}` }
+  },
+}

package/src/tools/file/glob.ts

@@ -0,0 +1,29 @@
+import { Glob } from 'bun'
+import type { ToolDefinition } from '../../shared/index.ts'
+import { resolveSafe } from '../../security/path'
+
+export const globTool: ToolDefinition = {
+  name: 'Glob',
+  description: 'Find files matching a glob pattern.',
+  category: 'file',
+  permission: 'auto',
+  parameters: {
+    type: 'object',
+    properties: {
+      pattern: { type: 'string', description: 'Glob pattern (e.g., "src/**/*.ts")' },
+      path: { type: 'string', description: 'Base directory' },
+    },
+    required: ['pattern'],
+  },
+  async execute(params, ctx) {
+    const pattern = params.pattern as string
+    const basePath = resolveSafe(ctx.cwd, (params.path as string) || '.')
+    const glob = new Glob(pattern)
+    const results: string[] = []
+    for await (const file of glob.scan({ cwd: basePath, absolute: true })) {
+      results.push(file)
+      if (results.length >= 500) break
+    }
+    return { success: true, content: results.join('\n') || '(no matches)' }
+  },
+}

package/src/tools/file/grep.ts

@@ -0,0 +1,52 @@
+import { $ } from 'bun'
+import type { ToolDefinition } from '../../shared/index.ts'
+import { resolveSafe } from '../../security/path'
+
+export const grepTool: ToolDefinition = {
+  name: 'Grep',
+  description: 'Search file contents using ripgrep. Fast regex search across files.',
+  category: 'file',
+  permission: 'auto',
+  parameters: {
+    type: 'object',
+    properties: {
+      pattern: { type: 'string', description: 'Regex pattern to search for' },
+      path: { type: 'string', description: 'Directory or file to search in' },
+      include: { type: 'string', description: 'File pattern to include (e.g., "*.ts")' },
+    },
+    required: ['pattern'],
+  },
+  async execute(params, ctx) {
+    const pattern = params.pattern as string
+    const searchPath = resolveSafe(ctx.cwd, (params.path as string) || '.')
+    const include = params.include as string | undefined
+
+    try {
+      const args = ['-n', '--heading', '--color=never', '-M', '500', pattern]
+      if (include) args.push('--glob', include)
+      args.push(searchPath)
+
+      const result = await $`rg ${args}`.cwd(ctx.cwd).quiet().text()
+      return { success: true, content: result || '(no matches)' }
+    } catch (err: unknown) {
+      const exitErr = err as { exitCode?: number }
+      if (exitErr.exitCode === 1) {
+        return { success: true, content: '(no matches)' }
+      }
+      // Fallback to grep
+      try {
+        const content = await $`grep -rn ${pattern} ${searchPath}`.cwd(ctx.cwd).quiet().text()
+        return {
+          success: true,
+          content: content.slice(0, 50000) || '(no matches)',
+        }
+      } catch {
+        return {
+          success: false,
+          content: '',
+          error: 'grep failed. Install ripgrep: brew install ripgrep',
+        }
+      }
+    }
+  },
+}