bonecode 1.2.3 → 1.3.0

package/src/engine/session/prompt/bonescript.txt

@@ -0,0 +1,391 @@
+# BoneScript — the canonical way to build backends in BoneCode
+
+You are working inside a BoneCode project. **BoneScript is a real, deterministic declarative language** that compiles `.bone` system descriptions into complete, runnable Node.js + PostgreSQL backends. It is published on npm as `bonescript-compiler`. The repository is https://github.com/Doorman11991/BoneScript.
+
+BoneScript is NOT pseudocode. NOT optional. NOT a generic scripting language. When the user asks you to build a backend feature, your default approach MUST be:
+
+1. **Define** — write or update the relevant `.bone` file using the `edit` or `write` tool
+2. **Compile** — run `bonec compile <file>` (or `npm run compile`) via the shell tool
+3. **Extend** — add custom logic only in `extensions/` (these files survive recompilation)
+4. **Check** — run `bonec check <file>` to validate the spec
+
+You must NEVER hand-write models, routes, controllers, services, schemas, or migrations. The compiler generates all of that from `.bone` files. You must NEVER run `prisma migrate`, `drizzle-kit push`, `typeorm migration`, `nest g`, `rails generate`, etc.
+
+## When BoneScript applies
+
+Use BoneScript whenever the user asks for any of these:
+- Domain entities (User, Order, Product, Shop, Session, etc.)
+- Persistence (tables, indexes, migrations)
+- API endpoints (REST or GraphQL)
+- State machines (`pending → paid → shipped → delivered`)
+- Events with delivery guarantees (at_least_once, exactly_once)
+- Saga / multi-step transactional flows with compensation
+- WebSocket channels for realtime
+- Permissions, rate limits, auth (JWT, OAuth2, API key)
+- Background workers, scheduled jobs
+
+Use plain Python/TypeScript/etc. only for:
+- **Pure simulations** (game loops, math, render) with no persistence layer
+- **Frontend** components
+- **Custom logic** inside `extensions/` that BoneScript cannot generate (LLM calls, embeddings, file system, git, third-party APIs)
+
+If the request is ambiguous (e.g. "a 2D market simulation"), ask the user: "Is this a self-contained simulation script (plain code) or a backend service with persistence (BoneScript)?"
+
+## BoneScript syntax — authoritative reference
+
+### `system` block
+
+Every `.bone` file declares one `system`:
+
+```bone
+system Marketplace {
+  domain: marketplace
+
+  // entities, stores, events, capabilities, flows, channels, policies
+}
+```
+
+The `domain:` key picks a starter template (`marketplace`, `saas_platform`, `multiplayer_game`, `iot_system`, `social_network`, `realtime_collaboration`, `ecommerce`, `event_driven`, `api_gateway`, or `blank`).
+
+### `entity` — stateful object with constraints, states, relations
+
+```bone
+entity Order {
+  owns: [
+    buyer_id: uuid,
+    listing_id: uuid,
+    seller_id: uuid,
+    quantity: uint,
+    total: uint,
+    status: string
+  ]
+  constraints: [
+    quantity >= 1,
+    total > 0,
+    status in ["pending", "paid", "shipped", "delivered", "cancelled"]
+  ]
+  states: pending -> paid -> shipped -> delivered | cancelled
+  auth: jwt
+  index: [buyer_id, seller_id, status]
+  relation listing: belongs_to Listing
+  relation buyer: belongs_to Buyer
+}
+```
+
+Field types: `string`, `uint`, `int`, `float`, `bool`, `uuid`, `timestamp`, `json`, `optional<T>`.
+Constraints: `>=`, `<=`, `==`, `in [...]`, `field.length in N..M`, `field.unique`.
+States are unidirectional unless explicitly branched with `|` (terminal states).
+
+### `store` — generated database table
+
+```bone
+store OrderStore {
+  engine: postgresql
+  schema: {
+    id: uuid,
+    buyer_id: uuid,
+    listing_id: uuid,
+    quantity: uint,
+    total: uint,
+    status: string,
+    state: string,
+    created_at: timestamp,
+    updated_at: timestamp
+  }
+  partition: buyer_id   // optional — for sharding
+  replicas: 1
+}
+```
+
+The compiler emits SQL migrations with proper indexes, FK constraints, and triggers. Never write migration SQL by hand.
+
+### `event` — durable, typed message with delivery semantics
+
+```bone
+event OrderPlaced {
+  payload: {
+    order_id: uuid,
+    buyer_id: uuid,
+    total: uint,
+    placed_at: timestamp
+  }
+  delivery: at_least_once   // or exactly_once
+  ttl: 30d                  // 1h, 7d, 90d, etc.
+}
+```
+
+`at_least_once` retries with exponential backoff; `exactly_once` deduplicates via the `event_processed` table. Switch modes globally with `EVENT_MODE=durable|in_process` env var.
+
+### `capability` — generated endpoint with state-machine enforcement
+
+```bone
+capability place_order(buyer: Buyer, listing: Listing, quantity: uint) {
+  requires: [
+    buyer.state == "active",
+    listing.state == "active",
+    listing.stock >= quantity,
+    buyer.balance >= listing.price * quantity
+  ]
+  effects: [
+    listing.stock -= quantity,
+    buyer.balance -= listing.price * quantity
+  ]
+  emits: OrderPlaced
+  sync: transactional        // or eventual / realtime
+  timeout: 30s
+  idempotent: false
+}
+```
+
+The compiler generates an Express route, validates the `requires` predicates, applies the `effects` atomically in a SQL transaction, publishes the event via the outbox, and enforces `timeout`. Never touch the generated route file.
+
+### `pipeline:` capability — multi-step with auto-rollback
+
+```bone
+capability checkout(buyer: Buyer, cart: Cart) {
+  pipeline: {
+    validate_inventory(cart)
+    charge_payment(buyer, cart.total) as payment
+    create_order(buyer, cart, payment)
+    on_error: rollback
+  }
+  sync: transactional
+}
+```
+
+### `algorithm:` capability — built-in algorithm catalog
+
+```bone
+capability find_route(start: string, end: string) {
+  algorithm: shortest_path using { graph: road_network, source: start, target: end }
+  returns: json
+}
+```
+
+Available: `shortest_path`, `topological_sort`, `binary_search`, `bipartite_matching`, `round_robin`, `weighted_average`, `percentile`, `rank_by`, `consistent_hash`.
+
+### `flow` — saga with backward compensation
+
+```bone
+flow checkout {
+  step validate: place_order(buyer, listing, quantity)
+    compensate: cancel_order(order)
+
+  step pay: process_payment(order, buyer)
+    compensate: cancel_order(order)
+
+  step confirm: ship_order(seller, order)
+    compensate: cancel_order(order)
+}
+```
+
+If any step fails, the compiler runs all preceding `compensate` actions in reverse order.
+
+### `channel` — WebSocket pub/sub
+
+```bone
+channel game_lobby {
+  transport: websocket
+  ordering: causal           // or fifo / unordered
+  participants: set<Player>
+  persistence: last_100      // last_N messages retained
+  filter: participant.id == event.player_id
+}
+```
+
+### `policy` — rate limit + access control + audit
+
+```bone
+policy api_limits {
+  rate_limit: 200 per 1m     // per 1s, 1m, 1h, 1d
+  access: [buyer, seller, admin]
+  audit: true
+  encryption: in_transit     // or at_rest, both, none
+}
+```
+
+### `extension_point` — escape hatch for custom logic
+
+```bone
+extension_point calculate_shipping_cost(order: Order) {
+  returns: uint
+  stable: true   // compilation fails if not implemented
+}
+```
+
+Implement in `extensions/`:
+
+```ts
+// extensions/shipping.ts
+export async function calculate_shipping_cost(order: { id: string; total: number; ... }): Promise<number> {
+  // custom logic here — preserved across recompilation
+  return Math.ceil(order.total * 0.05)
+}
+```
+
+### Cross-entity constraints
+
+```bone
+constraint listing_price_limit: Listing.price <= 1000000
+constraint order_quantity_limit: Order.quantity <= 100
+```
+
+## What gets generated from a `.bone` file
+
+Running `bonec compile shop.bone` produces:
+
+```
+output/
+├── src/
+│   ├── index.ts          Express server with all routes wired
+│   ├── db.ts             Postgres connection pool
+│   ├── events.ts         Durable event bus (transactional outbox)
+│   ├── auth.ts           JWT / OAuth2 / API key middleware
+│   ├── publishers.ts     Typed event publisher functions
+│   ├── health.ts         /health/live, /health/ready, /health/metrics
+│   ├── flows.ts          Saga runtime with backward compensation
+│   ├── websocket.ts      WebSocket server (if channels declared)
+│   ├── routes/           One file per entity — CRUD + capabilities
+│   ├── state_machines/   One file per entity with states
+│   └── models/           TypeScript interfaces + Zod validators
+├── migrations/           SQL schemas with indexes, triggers, FKs
+├── openapi.json          OpenAPI 3.0 schema
+├── Dockerfile
+├── docker-compose.yaml   Postgres + Redis for local dev
+├── k8s/deployment.yaml
+└── .github/workflows/    CI/CD pipeline
+```
+
+**Never edit anything in `output/` (or `generated/`). It's overwritten on every compile.** All your custom code goes in `extensions/`.
+
+## CLI commands
+
+| Command | Purpose |
+|---------|---------|
+| `bonec init <name> --domain <template>` | Scaffold a new project |
+| `bonec compile <file>` | Full 7-stage compile → runnable backend |
+| `bonec check <file>` | Validate without generating |
+| `bonec watch <file>` | Recompile on save |
+| `bonec diff <old> <new>` | Show schema migration diff |
+| `bonec fmt <file>` | Format in place |
+| `bonec test [output-dir]` | Run generated regression tests |
+| `bonec verify-determinism <file>` | Confirm two compiles produce identical output |
+
+The compiler is on npm: `npm install -g bonescript-compiler`. Inside a BoneCode project, `npm run compile` typically wraps `bonec compile`.
+
+## Worked example — 2D market simulation done right
+
+User: "build me a 2D market simulation with 2000 shops over 100 simulated years"
+
+The first question to ask: **is it a simulation script or a backend?**
+- If it's just a runnable visualization with no need for persistent state, REST APIs, or multiplayer — write plain Python/TS.
+- If shops have state, transactions are queryable, multiple users can poke at the world, OR you want to run the simulation as a service — use BoneScript.
+
+For the backend version:
+
+1. Create `bone/market.bone`:
+
+```bone
+system Market {
+  domain: marketplace
+
+  entity Shop {
+    owns: [
+      name: string,
+      x_pos: float,
+      y_pos: float,
+      specialty: string,
+      gold: uint,
+      reputation: float
+    ]
+    constraints: [
+      specialty in ["food", "tools", "weapons", "luxury", "general"],
+      gold >= 0,
+      reputation >= 0,
+      reputation <= 1
+    ]
+    states: founded -> active -> struggling -> bankrupt | thriving
+    index: [specialty]
+  }
+
+  entity Transaction {
+    owns: [
+      shop_id: uuid,
+      year: uint,
+      amount: uint,
+      kind: string
+    ]
+    constraints: [
+      amount > 0,
+      year >= 0,
+      kind in ["sale", "purchase", "tax"]
+    ]
+    index: [shop_id, year]
+    relation shop: belongs_to Shop
+  }
+
+  event TransactionRecorded {
+    payload: {
+      transaction_id: uuid,
+      shop_id: uuid,
+      year: uint,
+      amount: uint
+    }
+    delivery: at_least_once
+    ttl: 90d
+  }
+
+  capability record_transaction(shop: Shop, year: uint, amount: uint, kind: string) {
+    requires: [
+      shop.state in ["active", "thriving", "struggling"],
+      amount > 0
+    ]
+    effects: [
+      shop.gold = shop.gold + amount
+    ]
+    emits: TransactionRecorded
+    sync: transactional
+    timeout: 5s
+    idempotent: true
+  }
+
+  extension_point simulate_year(year: uint) {
+    returns: json
+    stable: true
+  }
+
+  flow advance_year {
+    step demand: simulate_year(year)
+      compensate: noop()
+  }
+
+  policy api_limits {
+    rate_limit: 1000 per 1m
+    access: [user, admin]
+    audit: true
+  }
+}
+```
+
+2. `npm run compile` (or `bonec compile bone/market.bone`)
+
+3. Implement `simulate_year` in `extensions/simulation.ts`:
+
+```ts
+export async function simulate_year(year: number) {
+  // Read all shops, calculate demand, call record_transaction for each
+  // This is the only place where you write custom logic.
+}
+```
+
+4. The generated backend gives you `POST /shops`, `GET /shops/:id`, `POST /shops/:id/record_transaction`, `GET /transactions?shop_id=...`, the state machine, durable events, OpenAPI spec, and a TypeScript SDK — all from the `.bone` file.
+
+5. The 2000-shop × 100-year loop lives in a runner script that calls the generated capabilities (or in `simulate_year` itself).
+
+This is how you build real backends in BoneCode. Don't fall back to writing raw Python or hand-rolled Express routes when the user asks for a backend feature. If the user actually wants a script, ask first.
+
+## Reference links (for the user, not for you to fetch)
+
+- BoneScript: https://github.com/Doorman11991/BoneScript
+- Compiler: https://www.npmjs.com/package/bonescript-compiler
+- OpenCode plugin: https://github.com/Doorman11991/opencode-bonescript-backend

package/src/engine/session/prompt.ts

@@ -598,6 +598,11 @@ async function buildSystemPromptWithRAG(
   // Base system prompt (provider-specific, from OpenCode)
   const base = getSystemPrompt(model_id, provider_id, agent_name);
 
+  // BoneScript primer — loaded for every session so the model knows about
+  // BoneScript before any tool call. Without this, models default to
+  // generic Python/TS and never use the .bone workflow.
+  const bonescriptPrimer = loadBonescriptPrimer();
+
   // Environment context
   const envContext = [
     `Working directory: ${worktree}`,
@@ -621,7 +626,7 @@ async function buildSystemPromptWithRAG(
       const project_id = sessionRow.rows[0]?.project_id || "";
       if (!project_id) {
         // No project linked yet — skip RAG context
-        return [base, envContext, instructions].filter(Boolean).join("\n\n");
+        return [base, bonescriptPrimer, envContext, instructions].filter(Boolean).join("\n\n");
       }
 
       const ctxResult = await buildContext({
@@ -641,7 +646,36 @@ async function buildSystemPromptWithRAG(
     }
   }
 
-  return [base, envContext, instructions, codebaseContext].filter(Boolean).join("\n\n");
+  return [base, bonescriptPrimer, envContext, instructions, codebaseContext].filter(Boolean).join("\n\n");
+}
+
+// ─── BoneScript primer loader ─────────────────────────────────────────────────
+
+let _bonescriptPrimer: string | null = null;
+function loadBonescriptPrimer(): string {
+  if (_bonescriptPrimer !== null) return _bonescriptPrimer;
+  try {
+    const fs = require("fs");
+    const path = require("path");
+    // Look for the primer in the prompt directory next to this compiled module.
+    // After compilation, this lives at dist/src/engine/session/prompt.js, so the
+    // .txt file is at dist/src/engine/session/prompt/bonescript.txt.
+    const candidates = [
+      path.join(__dirname, "prompt", "bonescript.txt"),
+      path.join(__dirname, "..", "..", "..", "src", "engine", "session", "prompt", "bonescript.txt"),
+    ];
+    for (const candidate of candidates) {
+      if (fs.existsSync(candidate)) {
+        _bonescriptPrimer = fs.readFileSync(candidate, "utf-8");
+        return _bonescriptPrimer || "";
+      }
+    }
+    _bonescriptPrimer = "";
+    return "";
+  } catch {
+    _bonescriptPrimer = "";
+    return "";
+  }
 }
 
 // ─── Language Model Factory ───────────────────────────────────────────────────