@openverb/ide

The OpenVerb verb library for AI-native IDEs and coding environments.

93 verbs across 17 categories — built on the openverb core protocol.

npm install @openverb/ide openverb

What This Is

@openverb/ide is a domain-specific verb library for the OpenVerb protocol. It provides:

• openverb.ide.json — 93 verb definitions in the core VerbLibrary format (params, returns, destructive, requires_confirmation)
• An IDE executor — wraps core createExecutor() with policy enforcement, batch execution, and audit receipts
• A policy engine — control exactly what AI is allowed to do (allow / deny / require_confirmation)
• A prompt generator — turn the verb library into ready-to-paste AI system prompts or tool-call schemas

It depends on openverb as a peer dependency and uses its types (Verb, Action, ActionResult, VerbHandler) throughout — no type duplication.

Quick Start

import { ideLibrary, createIDEExecutor, aiSafePolicy } from '@openverb/ide'
import fs from 'fs/promises'
import path from 'path'

const executor = createIDEExecutor(
  ideLibrary,
  {
    create_file: async (params) => {
      await fs.mkdir(path.dirname(params.path), { recursive: true })
      await fs.writeFile(params.path, params.content ?? '')
      return { verb: 'create_file', status: 'success', data: { path: params.path } }
    },
    update_file: async (params) => {
      await fs.writeFile(params.path, params.content)
      return { verb: 'update_file', status: 'success', data: { path: params.path } }
    },
    delete_file: async (params) => {
      await fs.unlink(params.path)
      return { verb: 'delete_file', status: 'success', data: { deleted: true } }
    }
  },
  { policy: aiSafePolicy() }
)

const receipt = await executor.executeBatch([
  { verb: 'create_file', params: { path: 'src/components/Button.tsx', content: 'export function Button({ children }) { return <button>{children}</button> }' } },
  { verb: 'create_file', params: { path: 'src/app/page.tsx', content: "import { Button } from '../components/Button'\nexport default function Page() { return <Button>Click</Button> }" } }
])

console.log(receipt.success)   // true
console.log(receipt.summary)   // "2 succeeded"

AI Integration

What the AI returns

Prompt your model to return a JSON array of actions:

[
  { "verb": "scaffold_from_template", "params": { "templateId": "nextjs-saas", "projectName": "MyApp" } },
  { "verb": "update_file", "params": { "path": "src/app/page.tsx", "content": "..." } }
]

Parsing AI responses

import { parseAIResponse, createIDEExecutor, ideLibrary, aiSafePolicy } from '@openverb/ide'

const raw = await callYourModel(prompt)

const parsed = parseAIResponse(raw)
if (!parsed.success) {
  console.error(parsed.error)
  return
}

const executor = createIDEExecutor(ideLibrary, myHandlers, { policy: aiSafePolicy() })
const receipt = await executor.executeBatch(parsed.actions!)

parseAIResponse handles JSON arrays, { commands: [...] } objects, and markdown-fenced code blocks.

Verb Library

93 verbs across 17 categories:

| Category | Count | Key Verbs | |----------|-------|-----------| | file | 13 | create_file, update_file, delete_file, apply_patch, generate_project_structure | | editor | 11 | open_file, show_diff, accept_diff, preview_diff, get_editor_state | | git | 10 | commit_changes, create_branch, push_repo, pull_repo, get_git_status | | preview | 8 | start_preview, build_project, deploy_project, capture_screenshot | | project | 4 | create_project, export_project, clone_repo, restore_session | | diagnostics | 5 | get_errors, run_typecheck, run_linter, format_file | | scaffold | 6 | scaffold_from_template, apply_template_layer, list_templates, create_template | | terminal | 4 | run_command, install_package, stop_process, read_terminal_output | | dependencies | 4 | install_dependency, remove_dependency, audit_dependencies | | environment | 3 | set_env_key, read_env_keys, remove_env_key | | testing | 3 | run_tests, run_unit_test, run_e2e_test | | database | 5 | run_migration, seed_database, reset_database, inspect_schema | | security | 3 | scan_secrets, scan_vulnerabilities, redact_secret | | search | 4 | search_files, search_text, search_symbols, find_references | | refactor | 3 | rename_symbol, extract_component, extract_function, explain_code | | collaboration | 2 | add_comment, create_checkpoint | | audit | 3 | emit_receipt, list_action_history, undo_action, redo_action |

Browse the library

import { ideLibrary, ideRegistry, getVerbsByCategory, getCategories, getVerb } from '@openverb/ide'

// The full VerbLibrary object (pass to core utilities)
ideLibrary.namespace  // "openverb.ide"
ideLibrary.verbs      // Verb[]

// Look up a verb
getVerb('create_file')
// { name: 'create_file', category: 'file', params: { path: { required: true, ... }, ... }, ... }

// Category filtering
getVerbsByCategory('git')   // all git verbs
getCategories()              // all 17 category names

Use with core utilities directly

import { buildRegistry, validateAction } from 'openverb'
import { ideLibrary } from '@openverb/ide'

const registry = buildRegistry(ideLibrary)
const result = validateAction(
  { verb: 'create_file', params: { path: 'x.ts' } },
  registry['create_file']
)
// { valid: true }

Scaffold Verbs — The Hybrid Model

The scaffold category enables a faster, more consistent approach:

Old: AI generates 30 files from scratch → slow, inconsistent, expensive

New: AI scaffolds from a template (instant) → then patches custom parts

// Instead of 30 create_file actions:
[
  { verb: 'scaffold_from_template', params: { templateId: 'nextjs-saas', projectName: 'MyApp' } },
  // → generates the entire boilerplate deterministically

  { verb: 'apply_patch', params: { path: 'src/app/page.tsx', patch: '...' } }
  // → AI only touches the 20% that's custom
]

Key scaffold verbs:

• scaffold_from_template — generate a full project from a template
• apply_template_layer — add a feature layer to an existing project (auth, payments, etc.)
• preview_template — show the file tree without creating anything
• list_templates — list available templates by category
• create_template — save the current project as a reusable template

Policy

import { createIDEExecutor, ideLibrary, aiSafePolicy, conservativePolicy, readOnlyPolicy, permissivePolicy, createPolicy } from '@openverb/ide'

// Built-in presets
aiSafePolicy()         // allows file ops, blocks terminal/deploy/db-reset
permissivePolicy()     // allows everything (trusted env only)
readOnlyPolicy(new Set(['read_file', 'list_tree', 'get_git_status']))

// Fluent builder
const policy = createPolicy()
  .deny('run_command', 'Shell commands disabled')
  .deny('reset_database', 'DB reset requires manual intervention')
  .requireConfirmation('deploy_project', 'Deployments need approval')
  .build()

const executor = createIDEExecutor(ideLibrary, handlers, { policy })

Policy decisions: allow | deny | require_confirmation

When require_confirmation fires, the action is returned with skipped: true and skipReason — your UI can surface this to the user before retrying.

Prompt Generator

import { ideLibrary, generateSystemPrompt, fileOnlyPrompt, toToolCallSchemas, xmlPrompt } from '@openverb/ide'

// Full IDE system prompt (markdown)
const prompt = generateSystemPrompt(ideLibrary)

// File-only prompt (for simple code editors)
const prompt = fileOnlyPrompt(ideLibrary, 'Always prefer TypeScript.')

// XML style (recommended for Claude)
const prompt = xmlPrompt(ideLibrary, { categories: ['file', 'git', 'scaffold'] })

// OpenAI/Anthropic tool-call schemas
const tools = toToolCallSchemas(ideLibrary, ['create_file', 'update_file', 'apply_patch'])

FolderCopilot Example

import { parseAIResponse, createIDEExecutor, ideLibrary, aiSafePolicy, formatBatchResult } from '@openverb/ide'

const executor = createIDEExecutor(
  ideLibrary,
  {
    create_file:              (p, ctx) => projectFS.createFile(ctx.projectId, p.path, p.content),
    update_file:              (p, ctx) => projectFS.updateFile(ctx.projectId, p.path, p.content),
    delete_file:              (p, ctx) => projectFS.deleteFile(ctx.projectId, p.path),
    apply_patch:              (p, ctx) => projectFS.applyPatch(ctx.projectId, p.path, p.patch),
    generate_project_structure: (p, ctx) => projectFS.bulkCreate(ctx.projectId, p.files),
    scaffold_from_template:   (p, ctx) => templateEngine.scaffold(ctx.projectId, p.templateId, p.variables),
  },
  {
    policy: aiSafePolicy(),
    onAfter: (action, result) => db.auditLog.create({ ...result, projectId: context.projectId })
  }
)

async function handleAIMessage(message: string, projectId: string) {
  const aiResponse = await callModel(message)
  const parsed = parseAIResponse(aiResponse)
  if (!parsed.success) throw new Error(parsed.error)

  const receipt = await executor.executeBatch(parsed.actions!)
  console.log(formatBatchResult(receipt))
  return receipt
}

Architecture

@openverb/ide
├── openverb.ide.json   — 93 verb definitions (VerbLibrary format, uses core Verb schema)
└── src/
    ├── library.ts      — loads ideLibrary via core loadLibrary(), buildRegistry()
    ├── executor.ts     — wraps core createExecutor() with policy, batching, receipts
    ├── policy.ts       — allow/deny/require_confirmation rules using core Action/Verb types
    └── prompt.ts       — system prompt and tool-call schema generators

Peer dependency: openverb (core protocol types and utilities)

License

MIT