{"id":47332832,"url":"https://github.com/proompteng/bilig","last_synced_at":"2026-06-02T05:00:59.382Z","repository":{"id":344142005,"uuid":"1180482213","full_name":"proompteng/bilig","owner":"proompteng","description":"Fast headless spreadsheet engine for Node.js formulas, workbook automation, WorkPaper JSON, and agent workflows.","archived":false,"fork":false,"pushed_at":"2026-05-15T05:02:37.000Z","size":48228,"stargazers_count":23,"open_issues_count":120,"forks_count":17,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-15T06:49:55.226Z","etag":null,"topics":["agent-tools","ai-agents","coding-agents","formula-engine","headless-spreadsheet","headless-workbook","langchain","mcp","model-context-protocol","nodejs","spreadsheet","spreadsheet-api","spreadsheet-automation","spreadsheet-engine","spreadsheet-formulas","typescript","vercel-ai-sdk","workbook-api","workbook-automation","xlsx"],"latest_commit_sha":null,"homepage":"https://proompteng.github.io/bilig/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/proompteng.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":"SUPPORT.md","governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-03-13T04:50:28.000Z","updated_at":"2026-05-15T05:01:25.000Z","dependencies_parsed_at":null,"dependency_job_id":"ef5f035f-2cf9-4d38-b0fc-2dd7cc98b3f6","html_url":"https://github.com/proompteng/bilig","commit_stats":null,"previous_names":["proompteng/bilig"],"tags_count":210,"template":false,"template_full_name":null,"purl":"pkg:github/proompteng/bilig","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/proompteng%2Fbilig","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/proompteng%2Fbilig/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/proompteng%2Fbilig/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/proompteng%2Fbilig/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/proompteng","download_url":"https://codeload.github.com/proompteng/bilig/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/proompteng%2Fbilig/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33095031,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-16T04:41:52.686Z","status":"ssl_error","status_checked_at":"2026-05-16T04:41:52.009Z","response_time":115,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-tools","ai-agents","coding-agents","formula-engine","headless-spreadsheet","headless-workbook","langchain","mcp","model-context-protocol","nodejs","spreadsheet","spreadsheet-api","spreadsheet-automation","spreadsheet-engine","spreadsheet-formulas","typescript","vercel-ai-sdk","workbook-api","workbook-automation","xlsx"],"created_at":"2026-03-17T21:22:44.630Z","updated_at":"2026-05-20T05:12:46.536Z","avatar_url":"https://github.com/proompteng.png","language":"TypeScript","funding_links":[],"categories":["Excel \u0026 Spreadsheet Integration","📊 Data Analysis \u0026 Business Intelligence","Databases","📦 Other"],"sub_categories":["Spreadsheets \u0026 No-Code"],"readme":"# bilig\n\n[![CI](https://github.com/proompteng/bilig/actions/workflows/ci.yml/badge.svg)](https://github.com/proompteng/bilig/actions/workflows/ci.yml)\n[![GitHub Repo stars](https://img.shields.io/github/stars/proompteng/bilig?style=social)](https://github.com/proompteng/bilig/stargazers)\n[![npm: bilig-workpaper](https://img.shields.io/npm/v/bilig-workpaper?label=bilig-workpaper)](https://www.npmjs.com/package/bilig-workpaper)\n[![npm: xlsx-formula-recalc](https://img.shields.io/npm/v/xlsx-formula-recalc?label=xlsx-formula-recalc)](https://www.npmjs.com/package/xlsx-formula-recalc)\n[![npm weekly downloads](https://img.shields.io/npm/dw/@bilig/headless?label=%40bilig%2Fheadless%20downloads)](https://www.npmjs.com/package/@bilig/headless)\n[![CodeQL](https://github.com/proompteng/bilig/actions/workflows/codeql.yml/badge.svg)](https://github.com/proompteng/bilig/actions/workflows/codeql.yml)\n[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/proompteng/bilig/badge)](https://scorecard.dev/viewer/?uri=github.com/proompteng/bilig)\n[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)\n\n**Formula workbooks for Node services and agent tools.**\n\nUse [`bilig-workpaper`](https://www.npmjs.com/package/bilig-workpaper) when a\ncalculation is easiest to review as cells and formulas, but it has to run in a\nNode service, queue worker, serverless route, test, or coding-agent tool. Use\n[`xlsx-formula-recalc`](https://www.npmjs.com/package/xlsx-formula-recalc) when\nthe immediate problem is \"I changed XLSX inputs in Node and need the formula\nresults now,\" including SheetJS / `xlsx` pipelines that already produce XLSX\nbytes. Use\n[`exceljs-formula-recalc`](https://www.npmjs.com/package/exceljs-formula-recalc)\nwhen the workbook is already moving through ExcelJS.\n\nThe scoped [`@bilig/headless`](https://www.npmjs.com/package/@bilig/headless)\npackage remains the fully qualified runtime package with bundled agent\nmetadata. The unscoped packages exist so people searching npm for WorkPaper,\nXLSX recalculation, ExcelJS formulas, SheetJS alternatives, or server-side\nspreadsheet formulas land on the narrow install path first.\n\nIt gives you a `WorkPaper`: build sheets, write inputs, recalculate, read the\ncell value, and save the workbook as JSON. No browser grid is involved.\nThe published package also carries `AGENTS.md` and `SKILL.md` so coding agents\ninspecting `node_modules/@bilig/headless` can find the write/read/persist loop\nlocally. The public docs expose the same path through\n[`AGENTS.md`](docs/AGENTS.md), [`skill.md`](docs/skill.md),\n[`docs/.well-known/agent.json`](docs/.well-known/agent.json),\n[`AI spreadsheet agent tool`](docs/ai-agent-spreadsheet-tool-node.md), and\n[`llms-full.txt`](docs/llms-full.txt).\n\nGood fits: pricing rules, budget checks, payout models, import validation, and\nagent tools that need read-after-write proof. Bad fits: manual spreadsheet\nediting, Office macros, desktop Excel automation, or one-off arithmetic where a\nworkbook would be ceremony.\n\nProject site: \u003chttps://proompteng.github.io/bilig/\u003e\n\n## Which Package Should I Install?\n\n| Problem you have right now                                                                      | Install                                      | First proof                                                                                  |\n| ----------------------------------------------------------------------------------------------- | -------------------------------------------- | -------------------------------------------------------------------------------------------- |\n| Formula workbook state inside a Node service or agent tool                                      | `npm install bilig-workpaper`                | [90-second Node quickstart](docs/try-bilig-headless-in-node.md)                              |\n| AI agent needs to edit workbook inputs and verify formula readback                              | `npm create @bilig/workpaper@latest pricing-agent -- --agent` | [AI spreadsheet agent tool](docs/ai-agent-spreadsheet-tool-node.md)          |\n| SheetJS / `xlsx` pipeline returns stale formula values after input edits                        | `npm install sheetjs-formula-recalc`         | [SheetJS formula result not updating](docs/sheetjs-formula-result-not-updating-node.md)       |\n| Generic XLSX bytes changed in Node; formula outputs must refresh before returning               | `npm install xlsx-formula-recalc`            | [XLSX formula recalculation in Node.js](docs/xlsx-formula-recalculation-node.md)             |\n| Existing ExcelJS workflow needs recalculated values, not stale cached results                   | `npm install exceljs exceljs-formula-recalc` | [ExcelJS formula recalculation in Node.js](docs/exceljs-formula-recalculation-node.md)       |\n| Full runtime package with agent metadata, MCP binary, provenance docs, and lower-level subpaths | `npm install @bilig/headless`                | [npm provenance and package trust](docs/npm-provenance-package-trust.md)                     |\n\n### Stale XLSX Formula Values? Run This First\n\nIf a Node job already has an XLSX file and only needs fresh formula values\nbefore returning, use the file-level recalculation package before evaluating\nthe broader WorkPaper runtime:\n\n```sh\nnpx --package sheetjs-formula-recalc sheetjs-recalc --demo --json\n\nnpx --package xlsx-formula-recalc xlsx-recalc --demo --json\n\nnpx --package xlsx-formula-recalc xlsx-recalc quote.xlsx \\\n  --set Inputs!B2=42 \\\n  --read Summary!B7 \\\n  --out quote.recalculated.xlsx \\\n  --json\n```\n\nIf the workbook is already in ExcelJS, keep that boundary and add\n`exceljs-formula-recalc`:\n\n```sh\nnpm install exceljs exceljs-formula-recalc\nnpx --package exceljs-formula-recalc exceljs-recalc --demo --json\n```\n\nFor one checkout proof across SheetJS/`xlsx`, `xlsx-populate`, and ExcelJS:\n\n```sh\nnpm --prefix examples/recalc-bridge-workflows install\nnpm --prefix examples/recalc-bridge-workflows run smoke\n```\n\n## Choose An Evaluation Path\n\n| If you are evaluating...      | Start here                                                                                                                                                                                                                | What should be true before you star, watch, or adopt                                                   |\n| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |\n| Basic fit                     | [Why use Bilig?](docs/why-use-bilig.md)                                                                                                                                                                                   | The problem is workbook-shaped business logic that needs API readback and persistence.                 |\n| Published npm package         | [90-second Node quickstart](docs/try-bilig-headless-in-node.md)                                                                                                                                                           | `bilig-workpaper` edits one input, recalculates, persists JSON, restores, and prints `verified: true`. |\n| XLSX or ExcelJS recalculation | [XLSX formula recalculation](docs/xlsx-formula-recalculation-node.md) and [ExcelJS formula recalculation](docs/exceljs-formula-recalculation-node.md)                                                                     | The package updates inputs, reads recalculated values, and exports or mutates the workbook boundary.   |\n| Backend service shape         | [Quote approval WorkPaper API](docs/quote-approval-workpaper-api.md)                                                                                                                                                      | A realistic route-style workflow returns formula readback and `restoredMatchesAfter: true`.            |\n| Agent or MCP tools            | [Headless WorkPaper agent handbook](docs/headless-workpaper-agent-handbook.md), [MCP spreadsheet tool server](docs/mcp-workpaper-tool-server.md), and [Claude Desktop MCPB bundle](docs/claude-desktop-mcpb-workpaper.md) | The agent installs a tool path, gets a copy-paste handoff prompt, then proves write/readback/persist.  |\n| Agent-owned XLSX files        | [Agent XLSX recalculation without LibreOffice](docs/agent-xlsx-formula-recalculation-without-libreoffice.md)                                                                                                              | A tool can edit XLSX inputs, recalculate, export, reimport, and return `verified: true`.               |\n| Public technical review       | [Show HN maintainer note](docs/show-hn-formula-workbooks-node-services.md)                                                                                                                                                | One shareable page has the npm check, benchmark caveat, known limits, and feedback ask.                |\n| Trust and performance         | [npm provenance](docs/npm-provenance-package-trust.md) and [benchmark evidence](docs/what-workpaper-benchmark-proves.md)                                                                                                  | npm shows SLSA provenance, and benchmark claims match the checked artifact.                            |\n| Almost a fit                  | [adoption blocker form](https://github.com/proompteng/bilig/discussions/new?category=general)                                                                                                                             | Name the formula, import/export, persistence, framework, MCP, package, or benchmark gap.               |\n| Formula or XLSX bug           | [formula bug clinic](docs/formula-bug-clinic.md)                                                                                                                                                                          | Share a reduced public case that can become a test, example, corpus fixture, or docs proof.            |\n| Real workbook blocked         | [submit a workbook fixture](docs/submit-workbook-fixture.md)                                                                                                                                                              | Use the structured form when a reduced workbook is ready.                                              |\n\nReduced workbook already in hand? Generate the paste-ready fixture report in\none command:\n\n```sh\nnpm exec --package @bilig/headless@0.37.2 -- bilig-formula-clinic ./reduced.xlsx --cells \"Summary!B7,Inputs!B2\"\n```\n\nHanding a spreadsheet task to another coding agent? Start with the\n[agent handoff prompt](docs/headless-workpaper-agent-handbook.md#copy-paste-prompt-for-another-agent)\nbefore opening Excel, LibreOffice, Google Sheets, or a screenshot UI.\nTo prove the package-owned agent loop without cloning the repo or downloading a\nTypeScript file:\n\n```sh\nnpm exec --package @bilig/headless@0.37.2 -- bilig-agent-challenge\nnpm exec --package @bilig/headless@0.37.2 -- bilig-mcp-challenge\n```\n\nAgent tools that support skill manifests can start from\n[`skill.md`](docs/skill.md) or the well-known index at\n[`docs/.well-known/agent-skills/index.json`](docs/.well-known/agent-skills/index.json).\nClaude Desktop users can also install the released MCPB bundle directly:\n\u003chttps://github.com/proompteng/bilig/releases/download/libraries-v0.37.2/bilig-workpaper.mcpb\u003e.\nIf you need a copy-paste eval for another tool host, use the\n[agent workbook challenge](docs/agent-workbook-challenge.md): one input edit,\none dependent formula readback, one serialized restore, and a `verified: true`\nproof object.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/assets/github-social-preview.png\" alt=\"bilig headless workbook runtime for formulas in TypeScript\" /\u003e\n\u003c/p\u003e\n\n## Try It In 90 Seconds\n\nThis uses the published npm package. It builds a workbook, changes one input,\nreads the calculated value, saves JSON, restores the workbook, and prints the\nsame value again.\n\n```sh\nmkdir bilig-headless-eval\ncd bilig-headless-eval\nnpm init -y\nnpm pkg set type=module\nnpm install bilig-workpaper\nnpm install -D tsx typescript @types/node\ncurl -fsSLo quickstart.ts https://proompteng.github.io/bilig/npm-eval.ts\nnpx tsx quickstart.ts\n```\n\nExpected output:\n\n```json\n{\n  \"before\": 24000,\n  \"after\": 38400,\n  \"afterRestore\": 38400,\n  \"sheets\": [\"Inputs\", \"Summary\"],\n  \"bytes\": 999,\n  \"verified\": true,\n  \"nextStep\": \"If this proof matches your service or agent workflow, star or bookmark Bilig: https://github.com/proompteng/bilig/stargazers\"\n}\n```\n\nThe TypeScript file is maintained in\n[`examples/headless-workpaper/npm-eval.ts`](examples/headless-workpaper/npm-eval.ts).\nThe exact byte count can change between package versions; `verified: true` and\nmatching `after`/`afterRestore` values are the check.\n\nFor a route-shaped quote approval API today, run the maintained example:\n\n```sh\ngit clone --depth 1 https://github.com/proompteng/bilig.git\ncd bilig\npnpm --dir examples/serverless-workpaper-api install --ignore-workspace\npnpm --dir examples/serverless-workpaper-api run smoke\n```\n\nFor a generated project from a blank directory, run\n`npm create @bilig/workpaper@latest pricing-workpaper` through the\n`@bilig/create-workpaper` package. The package source lives in\n[`packages/create-workpaper`](packages/create-workpaper), and the publish gate\nis documented in [create a Bilig WorkPaper starter](docs/create-bilig-workpaper.md).\nFor an agent-ready project with `AGENTS.md`, MCP client configs, and an\n`agent:verify` script, run\n`npm create @bilig/workpaper@latest pricing-agent -- --agent`.\n\nIf that proof matches a service or agent workflow you maintain, the useful next\nstep is concrete feedback: [star or bookmark the repo](https://github.com/proompteng/bilig/stargazers),\nthen open or answer one adoption blocker in\n[Discussions](https://github.com/proompteng/bilig/discussions/new?category=general):\nformula coverage, stale XLSX cached values, persistence shape, MCP/agent\nwriteback, or benchmark coverage.\n\n## TypeScript API Shape\n\nMost integrations are just this: build a workbook, write an input, read the\ncalculated value, and save the workbook state.\n\n```ts\nimport { WorkPaper, exportWorkPaperDocument, serializeWorkPaperDocument } from 'bilig-workpaper'\n\nconst workbook = WorkPaper.buildFromSheets({\n  Inputs: [\n    ['Metric', 'Value'],\n    ['Customers', 20],\n    ['Average revenue', 1200],\n  ],\n  Summary: [\n    ['Metric', 'Value'],\n    ['Revenue', '=Inputs!B2*Inputs!B3'],\n  ],\n})\n\nconst inputs = workbook.getSheetId('Inputs')\nconst summary = workbook.getSheetId('Summary')\nif (inputs === undefined || summary === undefined) {\n  throw new Error('Workbook is missing required sheets')\n}\n\nworkbook.setCellContents({ sheet: inputs, row: 1, col: 1 }, 32)\n\nconst revenue = workbook.getCellDisplayValue({ sheet: summary, row: 1, col: 1 })\nconst saved = serializeWorkPaperDocument(exportWorkPaperDocument(workbook, { includeConfig: true }))\n\nconsole.log({ revenue, savedBytes: saved.length })\n```\n\n## When To Reach For It\n\nUse `@bilig/headless` when:\n\n- a Node service owns a workbook-shaped calculation;\n- an agent needs tools such as `readRange` and `setInputCell`, with computed\n  before/after values instead of screenshots;\n- tests need deterministic spreadsheet state and formula readback;\n- a workflow needs to save the edited workbook as JSON and restore it later.\n\nUse something else when you need a visual spreadsheet grid, Office macros,\ndesktop Excel automation, or a one-off arithmetic helper. Do not treat embedded\nXLSX cached formula values as truth; use the Excel oracle workflow when accuracy\nmatters.\n\n## Package Boundary\n\n\u003c!-- headless-package-footprint:start --\u003e\n\nCurrent checked npm footprint for `@bilig/headless@0.37.2`:\n\n- Pack dry run: `499 kB` tarball, `3.00 MB` unpacked, `495` package entries.\n- Boundary: the main import is the WorkPaper formula/JSON runtime; XLSX\n  import/export stays behind the `@bilig/headless/xlsx` subpath; MCP is the\n  `bilig-workpaper-mcp` binary wrapper; reduced workbook reports use the\n  `bilig-formula-clinic` binary.\n- Cold-start gate: Node imports the main entrypoint, builds a two-sheet\n  WorkPaper, and reads `24000` under `1000 ms` without importing\n  the XLSX subpath.\n- Runtime: Node `\u003e=22.0.0`; Node 22 compatibility is covered by the runtime package workflow.\n\u003c!-- headless-package-footprint:end --\u003e\n\n## Published Package Trust\n\n`@bilig/headless` is published with npm registry signatures and SLSA provenance\nattestations. Verify the package version you are about to adopt:\n\n```sh\nnpm view @bilig/headless@latest version dist.attestations dist.signatures --json\n```\n\nAfter installing, npm can verify the current dependency tree:\n\n```sh\nnpm audit signatures\n```\n\nThe current package trust path is documented in\n[npm provenance and package trust](docs/npm-provenance-package-trust.md).\nRepository security posture is tracked by\n[OpenSSF Scorecard](https://scorecard.dev/viewer/?uri=github.com/proompteng/bilig)\nand uploaded to GitHub code scanning on every `main` update.\n\n## Start Here\n\nUse the shortest path that proves the package against a real job.\n\n1. Run the [90-second npm eval](#try-it-in-90-seconds) in a blank project.\n2. Run the flagship\n   [serverless WorkPaper API](examples/serverless-workpaper-api) example:\n   `npm run quote-approval-api`.\n3. If the workflow starts with an XLSX file, run the\n   [XLSX formula recalculation in Node](examples/xlsx-recalculation-node):\n   `npm start`.\n4. If an agent needs workbook tools, start with the\n   [headless WorkPaper agent handbook](docs/headless-workpaper-agent-handbook.md),\n   then use the [MCP server guide](docs/mcp-workpaper-tool-server.md) when the\n   caller is an MCP client.\n5. If a real workbook almost works, start with the\n   [formula bug clinic](docs/formula-bug-clinic.md). Then submit a\n   [reduced public fixture](docs/submit-workbook-fixture.md) so the blocker can\n   become a test, example, or corpus case instead of private feedback.\n   Form:\n   \u003chttps://github.com/proompteng/bilig/issues/new?template=workbook_fixture.yml\u003e.\n   Discussion:\n   \u003chttps://github.com/proompteng/bilig/discussions/414\u003e.\n\nThe rest of the docs are an index, not a prerequisite.\n\nFor comparison and integration details, use the\n[plain-language fit guide](docs/why-use-bilig.md),\n[screenshot automation boundary](docs/stop-driving-spreadsheets-with-screenshots.md),\n[Google Sheets API boundary](docs/google-sheets-api-alternative-node-workpaper.md),\n[workbook automation examples](docs/workbook-automation-examples-node.md),\nthe [formula workbooks proof page](docs/formula-workbooks-node-services-agent-tools.md),\nthe [Node spreadsheet formula engine guide](docs/node-spreadsheet-formula-engine.md),\n[server-side spreadsheet automation](docs/server-side-spreadsheet-automation-node.md),\n[framework adapters](docs/node-framework-workpaper-adapters.md),\n[formula bug clinic](docs/formula-bug-clinic.md),\n[workbook fixture submissions](docs/submit-workbook-fixture.md),\n[OpenAI Agents SDK tools](docs/openai-agents-sdk-workpaper-tool.md),\n[AI SDK and LangChain tools](docs/vercel-ai-sdk-langchain-spreadsheet-tool.md),\n[CrewAI adapter](docs/crewai-workpaper-spreadsheet-tool.md),\nthe [headless WorkPaper agent handbook](docs/headless-workpaper-agent-handbook.md),\nthe [MCP server guide](docs/mcp-workpaper-tool-server.md),\n[spreadsheet MCP server comparison](docs/spreadsheet-mcp-server-comparison.md),\n[MCP directory status](docs/mcp-spreadsheet-server-directory.md),\n[MCP client setup](docs/mcp-client-setup.md),\n[Claude Desktop MCPB bundle](docs/claude-desktop-mcpb-workpaper.md),\n[npm provenance and package trust](docs/npm-provenance-package-trust.md),\n[JavaScript library comparison](docs/javascript-spreadsheet-library-headless-node.md),\n[headless spreadsheet engine for Node services and agents](docs/headless-spreadsheet-engine-node-services-agents.md),\n[XLSX formula recalculation in Node.js](docs/xlsx-formula-recalculation-node.md),\n[agent XLSX formula recalculation without LibreOffice](docs/agent-xlsx-formula-recalculation-without-libreoffice.md),\n[Excel file as a Node calculation engine](docs/excel-file-calculation-engine-node.md),\n[stale XLSX formula cache in Node.js](docs/stale-xlsx-formula-cache-node.md),\n[SheetJS formula result not updating in Node.js](docs/sheetjs-formula-result-not-updating-node.md),\n[Microsoft Graph Excel recalculation in Node.js](docs/microsoft-graph-excel-recalculation-node.md),\n[xlsx-calc alternative for Node workbook recalculation](docs/xlsx-calc-alternative-node-workbook-recalculation.md),\n[ExcelJS formula recalculation in Node.js](docs/exceljs-formula-recalculation-node.md),\n[ExcelJS shared formulas in Node.js](docs/exceljs-shared-formula-recalculation-node.md),\n[SheetJS/ExcelJS boundary](docs/sheetjs-exceljs-alternative-formula-workbook-api.md),\nand [headless engine comparison](docs/headless-spreadsheet-engine-comparison.md).\n\nUseful deeper examples: [invoice totals](examples/headless-workpaper#invoice-totals),\n[budget variance alerts](examples/headless-workpaper#budget-variance-alerts),\n[fulfillment capacity plan](examples/headless-workpaper#fulfillment-capacity-plan),\n[quote approval threshold](examples/headless-workpaper#quote-approval-threshold),\n[subscription MRR forecast](examples/headless-workpaper#subscription-mrr-forecast),\n[agent framework adapters](examples/headless-workpaper#agent-framework-adapters),\n[MCP tool server shape](examples/headless-workpaper#mcp-tool-server-shape),\n[XLSX formula recalculation in Node](examples/xlsx-recalculation-node),\nand [serverless quote approval](examples/serverless-workpaper-api). Run\n`npm run quote-approval-api`, `npm run agent:openai-agents-sdk`,\n`npm run agent:framework-adapters`,\n`npm run agent:mcp-tools`, `npm run agent:mcp-transcript`,\n`npm run agent:mcp-file-transcript`, `npm run agent:mcp-stdio`, or\n`npm exec --package @bilig/headless@0.37.2 -- bilig-workpaper-mcp` when that is the\npath you are evaluating.\n\nThe serverless example also includes `npm run next-route-handler`,\n`npm run next-server-action`, `npm run next-server-action-formdata`,\n`npm run framework-adapters`, and `npm run persistence-adapters` for\nframework-specific boundary checks.\n\nThe MCP server is also listed in the official registry:\n\u003chttps://registry.modelcontextprotocol.io/v0.1/servers?search=io.github.proompteng%2Fbilig-workpaper\u003e.\nClients that support Streamable HTTP MCP can also smoke-test the stateless\nhosted endpoint at `https://bilig.proompteng.ai/mcp`; use the local stdio server\nwhen the agent needs to persist a project WorkPaper JSON file.\n\n## Examples You Can Run\n\nThe runnable examples are TypeScript files. Some source imports end in `.js`\nbecause Node ESM resolves compiled package output that way; the files you edit\nand run are still `.ts`.\n\nFrom a cloned checkout:\n\n```sh\npnpm --dir examples/headless-workpaper install --ignore-workspace\npnpm --dir examples/headless-workpaper run start\npnpm --dir examples/headless-workpaper run json-records\npnpm --dir examples/headless-workpaper run csv-shaped\npnpm --dir examples/headless-workpaper run invoice-totals\npnpm --dir examples/headless-workpaper run budget-variance\npnpm --dir examples/headless-workpaper run fulfillment-capacity\npnpm --dir examples/headless-workpaper run quote-approval\npnpm --dir examples/headless-workpaper run subscription-mrr\npnpm --dir examples/headless-workpaper run persistence\n```\n\nThe most useful entry points:\n\n- [JSON records input](examples/headless-workpaper#json-records-input)\n- [CSV shaped input](examples/headless-workpaper#csv-shaped-input)\n- [invoice totals](examples/headless-workpaper#invoice-totals)\n- [budget variance alerts](examples/headless-workpaper#budget-variance-alerts)\n- [fulfillment capacity plan](examples/headless-workpaper#fulfillment-capacity-plan)\n- [quote approval threshold](examples/headless-workpaper#quote-approval-threshold)\n- [subscription MRR forecast](examples/headless-workpaper#subscription-mrr-forecast)\n- [SheetJS, xlsx-populate, and ExcelJS recalculation bridge](examples/recalc-bridge-workflows)\n\nFor agent tools:\n\n```sh\npnpm --dir examples/headless-workpaper run agent:verify\npnpm --dir examples/headless-workpaper run agent:tool-call\npnpm --dir examples/headless-workpaper run agent:openai-agents-sdk\npnpm --dir examples/headless-workpaper run agent:openai-responses\npnpm --dir examples/headless-workpaper run agent:ai-sdk-generate-text\npnpm --dir examples/headless-workpaper run agent:ai-sdk-stream-text\npnpm --dir examples/headless-workpaper run agent:framework-adapters\npnpm --dir examples/headless-workpaper run agent:mcp-tools\npnpm --dir examples/headless-workpaper run agent:mcp-file-transcript\npnpm --dir examples/headless-workpaper run agent:mcp-stdio\n```\n\nThe AI SDK example uses\n[`ai-sdk-generate-text-tool-smoke.ts`](examples/headless-workpaper/ai-sdk-generate-text-tool-smoke.ts).\nThe OpenAI Agents SDK guide is\n[`docs/openai-agents-sdk-workpaper-tool.md`](docs/openai-agents-sdk-workpaper-tool.md).\nThe OpenAI Responses guide is\n[`docs/openai-responses-workpaper-tool-call.md`](docs/openai-responses-workpaper-tool-call.md).\nThe agent framework guide is\n[`docs/vercel-ai-sdk-langchain-spreadsheet-tool.md`](docs/vercel-ai-sdk-langchain-spreadsheet-tool.md).\n\nThe package also ships the MCP stdio binary:\n\n```sh\nnpm exec --package @bilig/headless@0.37.2 -- bilig-agent-challenge\nnpm exec --package @bilig/headless@0.37.2 -- bilig-formula-clinic ./reduced.xlsx --cells \"Summary!B7,Inputs!B2\"\nnpm exec --package @bilig/headless@0.37.2 -- bilig-mcp-challenge\nnpm exec --package @bilig/headless@0.37.2 -- bilig-workpaper-mcp\nnpm exec --package @bilig/headless@0.37.2 -- bilig-workpaper-mcp --workpaper ./pricing.workpaper.json --init-demo-workpaper --writable\ndocker build --target bilig-workpaper-mcp -t bilig-workpaper-mcp:local .\n```\n\n`bilig-agent-challenge` prints the same edit, formula readback, WorkPaper JSON\nexport, restore, and `verified: true` proof object used by the agent workbook\nchallenge page.\n\n`bilig-mcp-challenge` proves the file-backed MCP path end to end: initialize\nJSON-RPC, list tools/resources/prompts, edit `Inputs!B3`, read recalculated\n`Summary!B3`, export the WorkPaper JSON, restart from disk, and return\n`verified: true`.\n\n`bilig-formula-clinic` imports a reduced XLSX locally, samples formulas, reads\nrequested cells through WorkPaper, and prints a Markdown issue body. It does not\nupload workbook contents.\n\nWithout `--workpaper`, the binary starts the built-in demo workbook. With\n`--workpaper`, it loads your persisted WorkPaper JSON and exposes\n`list_sheets`, `read_range`, `read_cell`, `set_cell_contents`,\n`get_cell_display_value`, `export_workpaper_document`, and `validate_formula`;\n`--writable` persists `set_cell_contents` edits back to the same file. It also\nexposes MCP resources and prompts for `bilig://workpaper/agent-handoff`,\n`bilig://workpaper/current-document`, `edit_and_verify_workpaper`, and\n`debug_workpaper_formula`, so capable clients can discover the workflow before\ncalling tools.\nThe Docker target is for MCP directory scanners: it seeds a demo WorkPaper JSON\ninside the image and starts the file-backed `--writable` tool surface so\n`tools/list`, `resources/list`, and `prompts/list` return the general WorkPaper\nagent surface without cloning this monorepo. For remote MCP clients, the app\nruntime exposes `https://bilig.proompteng.ai/mcp` as a stateless JSON-only\nStreamable HTTP endpoint for tool discovery and write/readback smoke tests.\n\nIt is published in the official MCP Registry as\n`io.github.proompteng/bilig-workpaper`:\n\u003chttps://registry.modelcontextprotocol.io/v0.1/servers?search=io.github.proompteng%2Fbilig-workpaper\u003e.\nIt is also live on Glama with `Try in Browser`, A-grade tool pages, and all\nseven file-backed WorkPaper tools:\n\u003chttps://glama.ai/mcp/servers/proompteng/bilig\u003e.\n\n## Proof You Can Reproduce\n\n- The 90-second TypeScript check above edits one input, restores the saved JSON\n  document, and verifies the dependent formula result.\n- For a production-shaped evaluator path, run the\n  [quote approval WorkPaper API proof](docs/quote-approval-workpaper-api.md).\n  It starts from an empty Node directory, downloads one maintained TypeScript\n  route smoke, writes quote inputs, recalculates an approval decision, persists\n  JSON, and verifies restored readback.\n- For an XLSX formula recalculation example, run\n  [`examples/xlsx-recalculation-node`](examples/xlsx-recalculation-node). It\n  imports a generated XLSX pricing workbook, edits input cells, reads the\n  recalculated approval decision, exports XLSX, reimports it, and verifies the\n  formulas survived the round trip. The public decision page is\n  [XLSX formula recalculation in Node.js](docs/xlsx-formula-recalculation-node.md).\n- For a shorter public decision page, read\n  [formula workbooks for Node services and agent tools](docs/formula-workbooks-node-services-agent-tools.md).\n  It compresses the WorkPaper boundary, MCP file-backed mode, benchmark caveat,\n  and alternative-tool guidance into one shareable evaluator path.\n- For HN, Lobsters, Reddit, or newsletter review, use the\n  [Show HN maintainer note](docs/show-hn-formula-workbooks-node-services.md).\n  It keeps the empty npm-project command, `verified: true` output, benchmark\n  caveat, known limits, and feedback ask together.\n- Run `pnpm workpaper:bench:competitive:check`. The checked-in artifact shows\n  [`100/100` comparable WorkPaper mean wins](docs/what-workpaper-benchmark-proves.md)\n  and no p95 holdouts; the narrowest p95 win is\n  `aggregate-overlapping-sliding-window-wide` at `0.946x`.\n- The benchmark card is generated from that artifact:\n  [`docs/assets/workpaper-benchmark-card.png`](docs/assets/workpaper-benchmark-card.png).\n- Read the [compatibility limits](docs/where-bilig-is-not-excel-compatible-yet.md)\n  before importing real Excel workbooks.\n- Use the\n  [production adoption checklist](docs/production-adoption-checklist-headless-workpaper.md)\n  before promoting a WorkPaper-backed workflow beyond evaluation.\n- For XLSX accuracy audits, use the\n  [Excel oracle harness](docs/xlsx-corpus-verifier-walkthrough.md#run-the-excel-oracle-harness).\n  It separates import success, timeouts, stale cached formula values, and fresh\n  Microsoft Excel recalculation results.\n- The WorkPaper MCP server is listed in the\n  [official MCP Registry](https://registry.modelcontextprotocol.io/v0.1/servers?search=io.github.proompteng%2Fbilig-workpaper)\n  and on [Glama](https://glama.ai/mcp/servers/proompteng/bilig). The\n  [directory status page](docs/mcp-spreadsheet-server-directory.md) keeps the\n  npm command, remote endpoint, static MCP server card, and directory evidence\n  in one place.\n- Public feedback threads:\n  [workflow questions](https://github.com/proompteng/bilig/discussions/157),\n  [service examples](https://github.com/proompteng/bilig/discussions/213),\n  [persistence adapters](https://github.com/proompteng/bilig/discussions/307),\n  [JavaScript spreadsheet library guide](https://github.com/proompteng/bilig/discussions/308),\n  [OpenAI Responses tool calls](https://github.com/proompteng/bilig/discussions/335),\n  and [benchmark critique](https://github.com/proompteng/bilig/discussions/340).\n\nIf the 90-second check matches a problem you have, star or bookmark the repo:\n\u003chttps://github.com/proompteng/bilig/stargazers\u003e.\nIf you are evaluating `@bilig/headless` for production and want release\nnotifications, watch releases:\n\u003chttps://github.com/proompteng/bilig/subscription\u003e.\n\n## XLSX Accuracy Policy\n\nCached formula values embedded in `.xlsx` files are cache diagnostics, not an\naccuracy verdict. A Bilig correctness bug should only be claimed when the\nexpected value came from a fresh Excel recalculation oracle.\n\n```sh\nOUT=.cache/excel-oracle-evaluation\npnpm workpaper:xlsx-oracle -- prepare-oracle /path/to/xlsx-corpus \"$OUT\"\npnpm workpaper:xlsx-oracle -- evaluate-cache /path/to/xlsx-corpus \"$OUT\"\npnpm workpaper:xlsx-oracle -- evaluate-oracle /path/to/xlsx-corpus \"$OUT/recalculated\" \"$OUT\"\npnpm workpaper:xlsx-oracle -- summarize \"$OUT\"\n```\n\n`evaluate-cache` writes `cache-diagnostic.json` and stays non-authoritative.\n`evaluate-oracle` writes `excel-oracle-report.json`, and `summarize` writes\n`summary.md`. If Excel automation is unavailable, cells are classified as\n`missing_excel_oracle` instead of being promoted to bugs.\n\n## What Is In This Repo\n\n- `packages/headless`: WorkPaper runtime and npm package.\n- `packages/excel-import`: XLSX import/export boundary. Install both packages\n  with `pnpm add @bilig/headless @bilig/excel-import` when you need file import\n  and export.\n- `packages/formula`: formula parser, binder, compiler, and evaluator.\n- `packages/core`: workbook engine, snapshots, mutation flow, and scheduler.\n- `packages/grid` and `apps/web`: browser spreadsheet shell.\n- `apps/bilig`: fullstack monolith runtime, API surface, and static asset\n  server.\n- `packages/renderer`: React workbook renderer.\n- `packages/protocol`, `packages/binary-protocol`, `packages/agent-api`, and\n  `packages/worker-transport`: protocol and integration boundaries.\n- `packages/wasm-kernel`: AssemblyScript/WASM numeric fast path.\n- `packages/benchmarks`: benchmark harness and performance contracts.\n\nFor XLSX import/export from TypeScript:\n\n```ts\nimport { WorkPaper } from '@bilig/headless'\nimport { exportXlsx, importXlsx } from '@bilig/excel-import'\n```\n\nUse `WorkPaper.buildFromSnapshot(imported.snapshot)` after import and\n`workbook.exportSnapshot()` before `exportXlsx()`.\n\n## Local Development\n\nUse Node `24+`, Bun, and `pnpm@10.32.1`.\n\n```sh\npnpm install\npnpm dev:web\npnpm dev:web-local\npnpm dev:sync\n```\n\nFor a full local preflight:\n\n```sh\npnpm lint\npnpm typecheck\npnpm test\npnpm test:browser\npnpm run ci\n```\n\nGenerated sources and public evidence are checked:\n\n```sh\npnpm protocol:check\npnpm formula-inventory:check\npnpm workspace-resolution:check\npnpm workpaper:bench:competitive:check\npnpm docs:discovery:check\n```\n\n## For Coding Agents\n\nStart with the public package boundary unless the task is explicitly engine\nwork.\n\n1. Read `packages/headless/README.md` before touching WorkPaper behavior.\n2. Read `docs/AGENTS.md`, `docs/skill.md`, or `docs/llms-full.txt` when\n   building an agent-facing integration from outside the repo.\n3. Use public exports from `@bilig/headless`; do not reach into `src/` or\n   `dist/` when writing consumer examples.\n4. Keep examples TypeScript-first.\n5. Do not call stale XLSX cached formula values an accuracy oracle.\n6. Add focused tests before changing formulas, persistence, range bounds,\n   config rebuilds, events, row/column moves, or sheet lifecycle.\n7. Run the focused package tests first, then broaden to `pnpm run ci`.\n\n## Contributing\n\nRead [CONTRIBUTING.md](CONTRIBUTING.md) before opening a PR. If this is your\nfirst patch, start with the\n[new contributor guide](docs/new-contributor-guide.md) and then claim a scoped\nstarter issue.\n\nGood first patches usually fit one of these shapes:\n\n- formula fixtures with clear expected behavior;\n- small WorkPaper examples that prove a real service or agent workflow;\n- focused correctness fixes with regression tests;\n- grid accessibility and keyboard-behavior improvements;\n- docs that turn an existing architecture note into a runnable command.\n\nThe shortest public on-ramp is the\n[`starter issues`](docs/starter-issues.md) queue. It keeps code/test picks,\nexample tasks, adapters, and focused docs work in one current list, with small\nacceptance commands for first patches.\n\nIf this is your first contribution to `bilig`, use the\n[`first-timers-only`](https://github.com/proompteng/bilig/issues?q=is%3Aissue%20state%3Aopen%20label%3Afirst-timers-only)\nfilter.\n\n## Security And Support\n\nRead [SECURITY.md](SECURITY.md) before sharing vulnerability details, private\nworkbook data, tokens, credentials, or exploit reproductions. Security reports\nshould use GitHub private vulnerability reporting when available, or\n\u003csecurity@proompteng.ai\u003e when the private flow is not visible.\n\nUse [SUPPORT.md](SUPPORT.md) for the fastest public support path. Good reports\ninclude the package version, Node version, OS, exact formula or workbook input,\nexpected value, actual value, and the smallest command or script that reproduces\nthe issue.\n\n## CI\n\nForgejo Actions is the primary CI surface via\n`.forgejo/workflows/forgejo-ci.yml`. GitHub Actions mirrors the verification\ncontract in `.github/workflows/ci.yml`.\n\nThe strict gate includes frozen lockfile install, full `pnpm run ci`, artifact\nbudget checks, browser smoke, and tracked-file cleanliness checks.\n\n## License\n\nMIT.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fproompteng%2Fbilig","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fproompteng%2Fbilig","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fproompteng%2Fbilig/lists"}