bonecode 1.2.2 → 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 ───────────────────────────────────────────────────

package/src/tui.ts

@@ -393,19 +393,78 @@ interface ToolTrack {
  *   "text"  — pass deltas through verbatim (with partial-fence detection)
  *   "fence" — buffer everything; emit marker on close fence
  */
+/**
+ * Apply lightweight inline markdown styling to a streamed chunk.
+ *
+ * - `# `, `## `, `### ` at line-start become bold colored headers
+ * - `**text**` becomes bold
+ * - `` `code` `` becomes inverted gray
+ * - `- ` and `* ` at line-start become a bullet
+ *
+ * Operates per-line on the chunk. Cross-chunk markdown (a `**` opening in one
+ * delta and closing in another) is not handled — we just leave those raw.
+ * That's acceptable because it's rare and the model's output is still readable.
+ */
+function applyInlineMarkdown(text: string): string {
+  if (!text) return text;
+  // Split on newlines so we can match line-anchored patterns (headers, bullets)
+  const lines = text.split("\n");
+  const styled = lines.map((line) => {
+    // Headers
+    let m = line.match(/^(#{1,6})\s+(.*)$/);
+    if (m) {
+      const level = m[1].length;
+      const content = m[2];
+      if (level === 1) return `${CYAN}${BOLD}${content}${R}`;
+      if (level === 2) return `${CYAN}${BOLD}${content}${R}`;
+      if (level === 3) return `${WHITE}${BOLD}${content}${R}`;
+      return `${WHITE}${content}${R}`;
+    }
+    // Bullets at line start
+    m = line.match(/^(\s*)[-*]\s+(.*)$/);
+    if (m) {
+      line = `${m[1]}${GRAY}•${R} ${m[2]}`;
+    }
+    // Numbered lists
+    m = line.match(/^(\s*)(\d+\.)\s+(.*)$/);
+    if (m) {
+      line = `${m[1]}${GRAY}${m[2]}${R} ${m[3]}`;
+    }
+    // Bold (**text**)
+    line = line.replace(/\*\*([^*]+)\*\*/g, `${BOLD}$1${R}`);
+    // Inline code (`code`)
+    line = line.replace(/`([^`]+)`/g, `${GRAY}$1${R}`);
+    return line;
+  });
+  return styled.join("\n");
+}
+
+/**
+ * Stateful code-fence collapser.
+ *
+ * Replaces ```lang ... ``` blocks with a one-line marker
+ * "  ┃ code: lang, N lines" so streaming code blocks don't flood the TUI.
+ *
+ * State:
+ *   "text"  — pass through verbatim (with partial-fence buffering)
+ *   "fence" — silently buffer body; emit final marker on close
+ *
+ * Newline handling:
+ *   We strip up to one trailing newline before the opening fence and one
+ *   leading newline after the closing fence so the marker sits on its own
+ *   line without doubling blank lines around it.
+ */
 function makeCodeFenceCollapser() {
   let mode: "text" | "fence" = "text";
   let lang = "";
-  let buffered = ""; // bytes accumulated inside a fence
-  let pending = "";  // partial-fence buffer (when we see backticks but don't know yet)
-
-  const lines = (s: string) => s.split("\n").length;
+  let buffered = "";
+  let pending = "";
 
-  function flushPending(): string {
-    const out = pending;
-    pending = "";
-    return out;
-  }
+  const countLines = (s: string) => {
+    if (!s) return 0;
+    const trimmed = s.replace(/^\n+/, "").replace(/\n+$/, "");
+    return trimmed ? trimmed.split("\n").length : 0;
+  };
 
   return {
     feed(chunk: string): string {
@@ -416,23 +475,26 @@ function makeCodeFenceCollapser() {
 
       while (i < buf.length) {
         if (mode === "text") {
-          // Look for ``` to enter fence mode
           const fenceIdx = buf.indexOf("```", i);
           if (fenceIdx === -1) {
-            // No fence in remaining text — emit it all, but hold the last 2 chars
-            // in case they're part of an upcoming fence.
+            // No fence in remaining text. Hold last 2 chars in case they're
+            // the start of an upcoming fence.
             const safeEnd = Math.max(i, buf.length - 2);
             result += buf.slice(i, safeEnd);
             pending = buf.slice(safeEnd);
             i = buf.length;
             break;
           }
-          // Emit text up to the fence
-          result += buf.slice(i, fenceIdx);
-          // Read the language (everything until newline)
+          // Emit text up to the fence, but trim a single trailing newline so
+          // the marker sits on its own line without extra blank space.
+          let preFence = buf.slice(i, fenceIdx);
+          if (preFence.endsWith("\n")) preFence = preFence.slice(0, -1);
+          result += preFence;
+
+          // Read the language declaration (everything up to the next newline).
           const nlIdx = buf.indexOf("\n", fenceIdx + 3);
           if (nlIdx === -1) {
-            // Don't have the full opening line yet — buffer
+            // Opening line not complete yet — buffer for next feed.
             pending = buf.slice(fenceIdx);
             i = buf.length;
             break;
@@ -441,31 +503,36 @@ function makeCodeFenceCollapser() {
           i = nlIdx + 1;
           mode = "fence";
           buffered = "";
-          // Print a leading marker (will be amended when we close)
-          result += `${GRAY}┃ code: ${lang}…${R}`;
+          // Don't emit anything yet — the final marker is written when we
+          // see the closing fence so we have the line count.
           continue;
         }
 
         // mode === "fence" — look for closing ```
         const closeIdx = buf.indexOf("```", i);
         if (closeIdx === -1) {
+          // No close fence yet — buffer the body.
           buffered += buf.slice(i);
-          // Hold last 2 chars in case they're part of an upcoming close fence
+          // Hold last 2 chars in case they're part of an upcoming close fence.
           const safeEnd = Math.max(i, buf.length - 2);
           buffered = buffered.slice(0, buffered.length - (buf.length - safeEnd));
           pending = buf.slice(safeEnd);
           i = buf.length;
           break;
         }
-        // Closing fence found
+
+        // Closing fence found.
         buffered += buf.slice(i, closeIdx);
-        const lineCount = lines(buffered.replace(/\n+$/, ""));
-        // Replace the placeholder we already wrote with the final marker.
-        // Carriage return + clear line + reprint marker.
-        result += `\r${ESC}[2K   ${GRAY}┃ code: ${lang}, ${lineCount} line${lineCount === 1 ? "" : "s"}${R}\n`;
+        const lineCount = countLines(buffered);
+        // Emit the marker on its own line with leading and trailing newlines.
+        // The outer indenter will prepend "   " to each line break.
+        result += `\n${GRAY}┃ code: ${lang}, ${lineCount} line${lineCount === 1 ? "" : "s"}${R}`;
         i = closeIdx + 3;
-        // Skip optional newline after closing fence
+        // Skip a single newline immediately after the close fence to avoid
+        // doubling blank lines.
         if (buf[i] === "\n") i++;
+        // Add a trailing newline so the next text starts on a fresh line.
+        result += "\n";
         mode = "text";
         lang = "";
         buffered = "";
@@ -474,12 +541,12 @@ function makeCodeFenceCollapser() {
       return result;
     },
     flush(): string {
-      const tail = flushPending();
+      const tail = pending;
+      pending = "";
       if (mode === "fence") {
-        // Stream ended mid-fence — close it with an approximate count
-        const lineCount = lines(buffered.replace(/\n+$/, ""));
+        const lineCount = countLines(buffered);
         mode = "text";
-        return tail + `\r${ESC}[2K   ${GRAY}┃ code: ${lang}, ${lineCount}+ lines${R}\n`;
+        return tail + `\n${GRAY}┃ code: ${lang}, ${lineCount}+ lines${R}\n`;
       }
       return tail;
     },
@@ -563,8 +630,10 @@ async function streamPrompt(opts: {
             // code blocks appear as "[code: lang]" placeholders instead of
             // dumping raw source.
             const piece = collapseCodeFences(text);
+            // Apply lightweight markdown styling (headers, bold, inline code)
+            const styled = applyInlineMarkdown(piece);
             // Print with leading-newline indenting (so each new line gets the 3-space prefix)
-            const indented = piece.replace(/\n/g, `\n   `);
+            const indented = styled.replace(/\n/g, `\n   `);
             out(indented);
             fullText += text;
             continue;
@@ -727,6 +796,22 @@ export async function runTUI(opts: {
   port: number; token: string; model: string;
   provider: string; worktree: string; sessionId?: string;
 }): Promise<void> {
+  // Force UTF-8 output on Windows so emoji and box-drawing chars render
+  // correctly. Without this, console code page 437/850 corrupts multi-byte
+  // sequences into "??" or mojibake.
+  if (process.platform === "win32") {
+    try {
+      // Set output encoding for stdout/stderr
+      (process.stdout as any).setEncoding?.("utf-8");
+      (process.stderr as any).setEncoding?.("utf-8");
+      // Switch the console to UTF-8 (code page 65001)
+      const { execSync } = require("child_process");
+      execSync("chcp 65001", { stdio: "ignore" });
+    } catch {
+      // chcp not available — that's fine, we tried
+    }
+  }
+
   let { model, provider } = opts;
   const { port, token, worktree } = opts;
   let sessionId = opts.sessionId || null;