Bilig

Keep the workbook model. Run the rule in Node.

Bilig is a TypeScript-native, headless WorkPaper runtime for Node.js services, tests, and AI agents. Set inputs, recalculate formulas, read computed outputs, persist WorkPaper JSON, restore it, and verify the result—without driving Excel or a browser grid.

Docs · Quick start · TypeScript API · MCP · Examples · Discussions

[!NOTE] Bilig is a headless workbook runtime, not a visual spreadsheet app or a claim of full Excel compatibility. If an .xlsx file is your contract, start with the compatibility report.

Quick Start

Node runtime

Prove the published package before installing it:

npm exec --yes --package @bilig/workpaper@latest -- bilig-evaluate --door workpaper-service --json

The evaluator edits Inputs!B2, recalculates Summary!B2, saves the WorkPaper, restores it, and compares the restored value:

{
  "schemaVersion": "bilig-evaluator.v1",
  "door": "workpaper-service",
  "evidence": {
    "editedCell": "Inputs!B2",
    "dependentCell": "Summary!B2",
    "before": 24000,
    "after": 38400,
    "afterRestore": 38400
  },
  "verified": true
}

verified: true means the write, formula readback, JSON export, and restored readback all passed. It is stronger evidence than a successful write call.

Use It From TypeScript

npm install @bilig/workpaper

import { buildA1WorkPaper } from '@bilig/workpaper'

const pricing = buildA1WorkPaper({
  Inputs: [
    ['Metric', 'Value'],
    ['Units', 20],
    ['Price', 1200],
  ],
  Summary: [
    ['Metric', 'Value'],
    ['Revenue', '=Inputs!B2*Inputs!B3'],
  ],
})

const proof = pricing.editAndReadback('Inputs!B2', 32, {
  readbackRange: 'Summary!B2',
})

console.log(proof.afterReadback.displayValues[0]?.[0]) // 38400
console.log(proof.verified) // true

pricing.dispose()

For ordinary operations, use set(), setMany(), readMany(), display(),