opencode-bonescript-backend

An OpenCode plugin that makes BoneScript the default way to build backends. When you ask the agent to create models, APIs, state machines, workflows, or realtime channels, it uses BoneScript instead of writing raw code by hand.

Requires BoneScript — the declarative DSL that compiles system descriptions into complete, runnable Node.js backends.
→ github.com/Doorman11991/BoneScript

What it does

• Intercepts write and bash tool calls that look like backend work (writing to models/, routes/, running prisma migrate, etc.) and redirects the agent to the BoneScript workflow
• Injects workflow guidance into AGENTS.md so every session knows the spec-first approach
• Auto-validates .bone files with bonec check whenever one is saved
• Registers 8 custom tools the agent can call to work with BoneScript specs

Prerequisites

1. Install BoneScript CLI

npm install -g bonescript
# or
bun add -g bonescript

Verify:

bonec --version

2. OpenCode 1.x — the plugin uses the @opencode-ai/plugin SDK and requires OpenCode's Bun-based plugin loader.

Installation

Option A — Project-level (recommended for team use)

Copy the plugin source into your project's plugin directory. OpenCode loads all .ts files from .opencode/plugins/ automatically at startup — no build step needed, Bun handles transpilation.

your-project/
└── .opencode/
    └── plugins/
        ├── index.ts        ← main plugin
        ├── detect.ts       ← backend-intent detection
        └── tools/
            ├── bonescript_init.ts
            ├── bonescript_compile.ts
            ├── bonescript_watch.ts
            ├── bonescript_check.ts
            ├── bonescript_diff.ts
            ├── bonescript_edit.ts
            ├── bonescript_implement_extension.ts
            └── bonescript_analyze.ts

Copy from this repo:

cp -r bonescript-backend-plugin/src/* your-project/.opencode/plugins/

Option B — Global (applies to all projects)

cp -r bonescript-backend-plugin/src/* ~/.config/opencode/plugins/

Option C — npm

Install from npm and add to your project's opencode.json:

{
  "plugin": ["opencode-bonescript-backend"]
}

OpenCode installs it automatically via Bun at startup. No separate npm install needed — OpenCode handles it.

Or install manually:

npm install opencode-bonescript-backend
# or
bun add opencode-bonescript-backend

Verifying it loaded

Start OpenCode with log output:

opencode run "hello" --print-logs --log-level DEBUG 2>&1 | grep -i bonescript

You should see:

INFO  service=bonescript-backend-plugin  BoneScript plugin loaded — interceptor active
INFO  service=tool.registry  status=completed  bonescript_init
INFO  service=tool.registry  status=completed  bonescript_compile
... (all 8 tools)

You'll also see a BoneScript Backend Workflow section appear in your AGENTS.md — that's the plugin writing its guidance into the workspace rules so every session picks it up automatically.

The workflow

The plugin enforces a single pattern for all backend work:

1. DEFINE   → describe the feature in a .bone spec file
2. COMPILE  → bonec compile  (generates the full backend skeleton)
3. EXTEND   → add custom logic in extensions/ only
4. CHECK    → bonec check    (validate at any time)

Never edit files inside generated/. They are overwritten on every compile.
All custom logic lives in extensions/. Those files are never touched by the compiler.

Tools

The plugin adds 8 tools the agent can call:

bonescript_init

Scaffold a new BoneScript project. Supports domain templates so you get a pre-populated spec instead of starting blank.

Templates:
  saas_platform          multi-tenant SaaS with subscriptions, orgs, users
  marketplace            buyers, sellers, listings, orders, payments
  realtime_collaboration documents, presence, cursors, channels
  api_gateway            rate-limiting, auth, routing, upstream proxies
  event_driven           event bus, consumers, producers, dead-letter queues
  ecommerce              products, cart, checkout, inventory, fulfillment
  social_network         profiles, posts, follows, feeds, notifications
  blank                  empty scaffold

Example prompt:

"Set up a new marketplace backend"

The agent calls bonescript_init with template: "marketplace", which runs bonec init --template marketplace and gives you a fully populated .bone spec to start from.

bonescript_edit

Smart-edit a .bone file using structured operations. You don't need to know the exact BoneScript syntax — just describe what you want.

Operations:

| Operation | What it does | |-----------|-------------| | add_entity | Add a new data model | | add_field | Add a field to an existing entity | | add_api | Add REST/GraphQL endpoint definitions | | add_state_machine | Add lifecycle states and transitions to an entity | | add_channel | Add a realtime pub/sub channel | | add_workflow | Add a multi-step async workflow | | add_relation | Add a relation between entities | | remove_block | Remove a named block | | replace_block | Replace a named block with new content | | append_raw | Append raw BoneScript syntax |

Example prompt:

"Add a Product entity with name, price, and stock fields"

The agent calls bonescript_edit with operation: "add_entity" and the entity definition. No raw file editing.

bonescript_compile

Compile all .bone files into a runnable Node.js backend. Runs bonec compile.

Generates:

• Entity models and database migrations
• API route handlers
• State machine logic
• Realtime channel handlers
• Workflow orchestration

Example prompt:

"Compile the spec"

bonescript_watch

Start the compiler in watch mode. Recompiles automatically whenever a .bone file is saved. Runs as a background process and returns the PID.

Example prompt:

"Start watching for changes"

bonescript_check

Validate .bone files without generating any output. Catches syntax errors, invalid relations, incomplete state machines, etc. Runs bonec check.

The plugin also runs this automatically whenever you save a .bone file.

Example prompt:

"Check my spec for errors"

bonescript_diff

Preview what the next compile would change — new files, updated files, removed files — without writing anything. Runs bonec diff.

Example prompt:

"Show me what would change if I compile now"

bonescript_implement_extension

Create or edit a file in the extensions/ folder. These files are the only place for custom business logic and are never overwritten by the compiler.

Generates typed templates with the correct hook signatures:

| Extension type | When it runs | |---------------|-------------| | beforeCreate / afterCreate | Around record creation | | beforeUpdate / afterUpdate | Around record updates | | beforeDelete | Before record deletion | | customRoute | Custom API endpoints | | stateTransitionGuard | Control state machine transitions | | channelAuth | Authorize realtime subscriptions | | workflowStep | Implement workflow step logic |

Example prompt:

"Add a beforeCreate hook for User that hashes the password"

The agent calls bonescript_implement_extension with extensionType: "beforeCreate" and targetName: "User", creating extensions/User.beforeCreate.ts with the right function signature pre-filled.

bonescript_analyze

Read all .bone files and produce a structured summary of the system — entities, APIs, state machines, channels, workflows, and relations.

Example prompt:

"Explain what's in this BoneScript project" "What entities do we have?" "Show me all the state machines"

The interceptor

The plugin watches every write and bash tool call the agent makes. If it looks like backend work, the call is cancelled and the agent is redirected to BoneScript.

Triggers a redirect:

| Signal | Examples | |--------|---------| | Writing to backend paths | models/User.ts, routes/users.ts, controllers/, migrations/, schemas/ | | Backend file extensions | *.model.ts, *.entity.ts, *.controller.ts, *.service.ts | | ORM content in files | @Entity, @Column, model User { (Prisma), mongoose.Schema( | | ORM commands | prisma migrate, drizzle-kit push, typeorm migration, knex migrate | | Scaffolding commands | nest g resource, rails generate model |

Never intercepted:

• .bone files (always allowed)
• extensions/ files (always allowed)
• generated/ files (compiler output)
• Test files (*.test.ts, *.spec.ts)
• Frontend code, config files, documentation

Example session

User: "Add a User entity with email and password, and a REST API for it"

Agent:
  1. Calls bonescript_edit (add_entity) → adds User entity to domain.bone
  2. Calls bonescript_edit (add_api)    → adds UserAPI to domain.bone
  3. Calls bonescript_compile           → generates the full backend
  4. Calls bonescript_implement_extension (beforeCreate, User)
     → creates extensions/User.beforeCreate.ts for password hashing

User: "Add order status tracking with pending → confirmed → shipped → delivered states"

Agent:
  1. Calls bonescript_edit (add_state_machine) → adds OrderStatus state machine
  2. Calls bonescript_compile                  → regenerates backend with state machine
  3. Calls bonescript_implement_extension (stateTransitionGuard, Order)
     → creates extensions/Order.stateTransitionGuard.ts

User: "Show me what's in the spec"

Agent:
  1. Calls bonescript_analyze → returns full breakdown of entities, APIs, state machines

Project structure after setup

your-project/
├── domain.bone              ← Your spec (edit this)
├── extensions/              ← Your custom logic (edit this)
│   ├── User.beforeCreate.ts
│   └── Order.stateTransitionGuard.ts
├── generated/               ← Never edit — overwritten on compile
│   ├── models/
│   ├── routes/
│   ├── state-machines/
│   ├── channels/
│   └── workflows/
├── AGENTS.md                ← BoneScript guidance (written by plugin)
└── .opencode/
    └── plugins/             ← Plugin source lives here

Troubleshooting

Plugin not loading

Check that the files are in .opencode/plugins/ (project-level) or ~/.config/opencode/plugins/ (global). Run with --print-logs --log-level DEBUG and grep for bonescript.

bonec not found

Install BoneScript: npm install -g bonescript

Interceptor blocking something it shouldn't

The safe-path allowlist covers .bone, extensions/, generated/, and test files. If something legitimate is being blocked, check detect.ts and add the path pattern to SAFE_PATH_PATTERNS.

bonec diff not available

Upgrade BoneScript: npm install -g bonescript@latest

Building from source

cd bonescript-backend-plugin
bun install
bun run build       # compiles to dist/
bun run typecheck   # type-check without emitting

Output goes to dist/. For local plugin use, copy src/ directly — OpenCode's Bun loader handles TypeScript natively.

License

MIT