@bilig/headless 0.11.28 → 0.11.30
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +85 -70
- package/package.json +12 -6
package/README.md
CHANGED
|
@@ -6,13 +6,32 @@
|
|
|
6
6
|
[](https://github.com/proompteng/bilig/stargazers)
|
|
7
7
|
[](https://github.com/proompteng/bilig/blob/main/LICENSE)
|
|
8
8
|
|
|
9
|
-
`@bilig/headless`
|
|
10
|
-
|
|
11
|
-
|
|
9
|
+
`@bilig/headless` is the `bilig` spreadsheet engine without the browser UI.
|
|
10
|
+
It lets Node.js programs build workbooks, write formulas, read calculated
|
|
11
|
+
cells, and save or restore the workbook as JSON.
|
|
12
12
|
|
|
13
|
-
Use it
|
|
14
|
-
|
|
15
|
-
|
|
13
|
+
Use it when spreadsheet logic belongs inside a service, test suite, local-first
|
|
14
|
+
app, queue worker, or coding-agent tool. It gives code a workbook boundary with
|
|
15
|
+
stable sheet names, cell addresses, formulas, and persisted state.
|
|
16
|
+
|
|
17
|
+
It is not Excel desktop automation and it is not a visual grid. XLSX import and
|
|
18
|
+
export live in the repository import/export packages; this package executes the
|
|
19
|
+
validated WorkPaper model once data is in workbook form.
|
|
20
|
+
|
|
21
|
+
## Current Public Proof
|
|
22
|
+
|
|
23
|
+
- Live growth snapshot:
|
|
24
|
+
<https://proompteng.github.io/bilig/community-growth-snapshot.html>
|
|
25
|
+
- Latest checked-in snapshot: `24` GitHub stars, `13,427` npm downloads in the
|
|
26
|
+
last week, `30` open `good first issue` tickets, `5` GitHub Discussions, and
|
|
27
|
+
`393` recent repository views.
|
|
28
|
+
- Benchmark evidence:
|
|
29
|
+
[`46/46` comparable WorkPaper mean wins](https://github.com/proompteng/bilig/blob/main/docs/what-workpaper-benchmark-proves.md),
|
|
30
|
+
with the p95 caveat documented instead of hidden.
|
|
31
|
+
|
|
32
|
+
If the sanity check below saves you a workbook-automation spike, star or
|
|
33
|
+
bookmark the repo after you see the verification output:
|
|
34
|
+
<https://github.com/proompteng/bilig/stargazers>.
|
|
16
35
|
|
|
17
36
|
## Install
|
|
18
37
|
|
|
@@ -71,76 +90,61 @@ pnpm --filter @bilig/headless build
|
|
|
71
90
|
|
|
72
91
|
## Start Here
|
|
73
92
|
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
[
|
|
82
|
-
|
|
83
|
-
[`npm run json-
|
|
84
|
-
|
|
85
|
-
[`npm run
|
|
86
|
-
|
|
87
|
-
[`npm run
|
|
88
|
-
|
|
89
|
-
[
|
|
90
|
-
|
|
91
|
-
[`
|
|
92
|
-
|
|
93
|
-
[`npm run sheet-inspection`](https://github.com/proompteng/bilig/tree/main/examples/headless-workpaper#sheet-inspection)
|
|
94
|
-
for checking restored workbook shape before writes, or
|
|
95
|
-
[`npm run http-json-summary`](https://github.com/proompteng/bilig/tree/main/examples/headless-workpaper#http-json-summary)
|
|
96
|
-
for a no-framework Node HTTP boundary, or
|
|
97
|
-
[`npm run invoice-totals`](https://github.com/proompteng/bilig/tree/main/examples/headless-workpaper#invoice-totals)
|
|
98
|
-
for subtotal, tax, and total formula readback, or
|
|
99
|
-
[`npm run budget-variance`](https://github.com/proompteng/bilig/tree/main/examples/headless-workpaper#budget-variance-alerts)
|
|
100
|
-
for formula-backed budget variance alerts, or
|
|
101
|
-
[`npm run subscription-mrr`](https://github.com/proompteng/bilig/tree/main/examples/headless-workpaper#subscription-mrr-forecast)
|
|
102
|
-
for churn, expansion, and ending MRR formulas, or
|
|
103
|
-
[`npm run quote-approval`](https://github.com/proompteng/bilig/tree/main/examples/headless-workpaper#quote-approval-threshold)
|
|
104
|
-
for formula-backed quote discount approvals, or
|
|
105
|
-
[`npm run fulfillment-capacity`](https://github.com/proompteng/bilig/tree/main/examples/headless-workpaper#fulfillment-capacity-plan)
|
|
106
|
-
for order volume, labor hours, and capacity gap formulas.
|
|
107
|
-
- Run the
|
|
108
|
-
[serverless WorkPaper API example](https://github.com/proompteng/bilig/tree/main/examples/serverless-workpaper-api)
|
|
109
|
-
when the workbook belongs behind an HTTP or agent-tool boundary.
|
|
110
|
-
- Build a small service from the
|
|
111
|
-
[Node service recipe](https://github.com/proompteng/bilig/blob/main/docs/node-service-workpaper-recipe.md).
|
|
112
|
-
- Put the same workbook boundary behind a
|
|
113
|
-
[serverless API route](https://github.com/proompteng/bilig/blob/main/docs/serverless-workpaper-api-route.md).
|
|
114
|
-
- Check the
|
|
115
|
-
[compatibility boundaries](https://github.com/proompteng/bilig/blob/main/docs/where-bilig-is-not-excel-compatible-yet.md)
|
|
116
|
-
before assuming full Excel parity.
|
|
117
|
-
- Compare against other engines with the
|
|
93
|
+
Pick the path that matches the job:
|
|
94
|
+
|
|
95
|
+
- Prove the package works from npm:
|
|
96
|
+
[clean npm sanity check](#clean-npm-sanity-check).
|
|
97
|
+
- Decide if this package fits a backend formula workload:
|
|
98
|
+
[Node.js spreadsheet formula engine guide](https://proompteng.github.io/bilig/node-spreadsheet-formula-engine.html).
|
|
99
|
+
- Test formula edits plus persistence:
|
|
100
|
+
[quickstart](#quickstart).
|
|
101
|
+
- Convert API records into workbook output:
|
|
102
|
+
[`npm run json-records`](https://github.com/proompteng/bilig/tree/main/examples/headless-workpaper#json-records-input).
|
|
103
|
+
- Wrap workbook edits as agent tools:
|
|
104
|
+
[`npm run agent:tool-call`](https://github.com/proompteng/bilig/tree/main/examples/headless-workpaper#agent-tool-call-loop).
|
|
105
|
+
- Adapt the same WorkPaper tools to agent frameworks:
|
|
106
|
+
[`npm run agent:framework-adapters`](https://github.com/proompteng/bilig/tree/main/examples/headless-workpaper#agent-framework-adapters).
|
|
107
|
+
- Map WorkPaper tools to Vercel AI SDK and LangChain:
|
|
108
|
+
[framework adapter guide](https://proompteng.github.io/bilig/vercel-ai-sdk-langchain-spreadsheet-tool.html).
|
|
109
|
+
- Put WorkPaper behind HTTP:
|
|
110
|
+
[`examples/serverless-workpaper-api`](https://github.com/proompteng/bilig/tree/main/examples/serverless-workpaper-api).
|
|
111
|
+
- Compare engines before adopting:
|
|
118
112
|
[SheetJS and ExcelJS comparison](https://github.com/proompteng/bilig/blob/main/docs/sheetjs-exceljs-alternative-formula-workbook-api.md),
|
|
119
|
-
[HyperFormula comparison](https://github.com/proompteng/bilig/blob/main/docs/hyperformula-alternative-headless-workpaper.md)
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
113
|
+
[HyperFormula comparison](https://github.com/proompteng/bilig/blob/main/docs/hyperformula-alternative-headless-workpaper.md),
|
|
114
|
+
[headless spreadsheet engine comparison](https://github.com/proompteng/bilig/blob/main/docs/headless-spreadsheet-engine-comparison.md),
|
|
115
|
+
and
|
|
116
|
+
[benchmark explainer](https://github.com/proompteng/bilig/blob/main/docs/what-workpaper-benchmark-proves.md).
|
|
117
|
+
|
|
118
|
+
For more workflows, read the
|
|
119
|
+
[five Node workbook automation examples](https://github.com/proompteng/bilig/blob/main/docs/workbook-automation-examples-node.md),
|
|
120
|
+
the [Node service recipe](https://github.com/proompteng/bilig/blob/main/docs/node-service-workpaper-recipe.md),
|
|
121
|
+
the [serverless API route walkthrough](https://github.com/proompteng/bilig/blob/main/docs/serverless-workpaper-api-route.md),
|
|
122
|
+
and the
|
|
123
|
+
[compatibility boundaries](https://github.com/proompteng/bilig/blob/main/docs/where-bilig-is-not-excel-compatible-yet.md).
|
|
124
|
+
|
|
125
|
+
Star or bookmark the project: <https://github.com/proompteng/bilig>.
|
|
123
126
|
|
|
124
127
|
## Which Example Should I Run?
|
|
125
128
|
|
|
126
129
|
The full example catalog lives in
|
|
127
130
|
[`examples/headless-workpaper/README.md`](https://github.com/proompteng/bilig/blob/main/examples/headless-workpaper/README.md).
|
|
128
131
|
|
|
129
|
-
| Need | Start with
|
|
130
|
-
| ------------------------------------ |
|
|
131
|
-
| Evaluate formulas from API records | `npm run json-records`
|
|
132
|
-
| Load records already saved on disk | `npm run json-file`
|
|
133
|
-
| Persist and restore a workbook | `npm run persistence`
|
|
134
|
-
| Verify an agent writeback | `npm run agent:verify`
|
|
135
|
-
| Wrap WorkPaper operations as tools | `npm run agent:tool-call`
|
|
136
|
-
|
|
|
137
|
-
|
|
|
138
|
-
| Check
|
|
139
|
-
|
|
|
140
|
-
|
|
|
141
|
-
|
|
|
142
|
-
|
|
|
143
|
-
|
|
|
132
|
+
| Need | Start with | Existing example |
|
|
133
|
+
| ------------------------------------ | ---------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
|
|
134
|
+
| Evaluate formulas from API records | `npm run json-records` | [JSON records input](https://github.com/proompteng/bilig/tree/main/examples/headless-workpaper#json-records-input) |
|
|
135
|
+
| Load records already saved on disk | `npm run json-file` | [JSON file input](https://github.com/proompteng/bilig/tree/main/examples/headless-workpaper#json-file-input) |
|
|
136
|
+
| Persist and restore a workbook | `npm run persistence` | [Persistence round trip](https://github.com/proompteng/bilig/tree/main/examples/headless-workpaper#persistence-round-trip) |
|
|
137
|
+
| Verify an agent writeback | `npm run agent:verify` | [Agent writeback verification](https://github.com/proompteng/bilig/tree/main/examples/headless-workpaper#agent-writeback-verification) |
|
|
138
|
+
| Wrap WorkPaper operations as tools | `npm run agent:tool-call` | [Agent tool call loop](https://github.com/proompteng/bilig/tree/main/examples/headless-workpaper#agent-tool-call-loop) |
|
|
139
|
+
| Adapt tools to agent frameworks | `npm run agent:framework-adapters` | [Agent framework adapters](https://github.com/proompteng/bilig/tree/main/examples/headless-workpaper#agent-framework-adapters) |
|
|
140
|
+
| Flag budget variance rows | `npm run budget-variance` | [Budget variance alerts](https://github.com/proompteng/bilig/tree/main/examples/headless-workpaper#budget-variance-alerts) |
|
|
141
|
+
| Check fulfillment capacity | `npm run fulfillment-capacity` | [Fulfillment capacity plan](https://github.com/proompteng/bilig/tree/main/examples/headless-workpaper#fulfillment-capacity-plan) |
|
|
142
|
+
| Check quote approval threshold | `npm run quote-approval` | [Quote approval threshold](https://github.com/proompteng/bilig/tree/main/examples/headless-workpaper#quote-approval-threshold) |
|
|
143
|
+
| Forecast subscription MRR | `npm run subscription-mrr` | [Subscription MRR forecast](https://github.com/proompteng/bilig/tree/main/examples/headless-workpaper#subscription-mrr-forecast) |
|
|
144
|
+
| Return workbook results over HTTP | `npm run http-json-summary` | [HTTP JSON summary](https://github.com/proompteng/bilig/tree/main/examples/headless-workpaper#http-json-summary) |
|
|
145
|
+
| Calculate invoice totals | `npm run invoice-totals` | [Invoice totals](https://github.com/proompteng/bilig/tree/main/examples/headless-workpaper#invoice-totals) |
|
|
146
|
+
| Inspect restored workbook shape | `npm run sheet-inspection` | [Sheet inspection](https://github.com/proompteng/bilig/tree/main/examples/headless-workpaper#sheet-inspection) |
|
|
147
|
+
| Compare computed values and formulas | `npm run range-readback` | [Range readback](https://github.com/proompteng/bilig/tree/main/examples/headless-workpaper#range-readback) |
|
|
144
148
|
|
|
145
149
|
## Production Status
|
|
146
150
|
|
|
@@ -154,9 +158,11 @@ Current release posture:
|
|
|
154
158
|
- Full local CI passed after the latest headless hardening work, including unit,
|
|
155
159
|
contract, fuzz, browser, clean-diff, release-budget, runtime-publish, and
|
|
156
160
|
WorkPaper competitive benchmark gates.
|
|
157
|
-
- The checked-in competitive artifact generated on `2026-05-
|
|
161
|
+
- The checked-in competitive artifact generated on `2026-05-08T15:00:27.603Z`
|
|
158
162
|
shows `46/46` comparable WorkPaper mean wins against HyperFormula-style
|
|
159
163
|
workloads: `38/38` public and `8/8` holdout.
|
|
164
|
+
- The shareable benchmark card is generated from that artifact:
|
|
165
|
+
[`docs/assets/workpaper-benchmark-card.png`](https://github.com/proompteng/bilig/blob/main/docs/assets/workpaper-benchmark-card.png).
|
|
160
166
|
- The public benchmark evidence note explains the measured workload families,
|
|
161
167
|
engine metadata, exclusions, and the current p95 nuance:
|
|
162
168
|
[`docs/headless-workpaper-benchmark-evidence.md`](https://github.com/proompteng/bilig/blob/main/docs/headless-workpaper-benchmark-evidence.md).
|
|
@@ -222,6 +228,8 @@ Repository links:
|
|
|
222
228
|
- npm: <https://www.npmjs.com/package/@bilig/headless>
|
|
223
229
|
- runnable example:
|
|
224
230
|
[`examples/headless-workpaper`](https://github.com/proompteng/bilig/tree/main/examples/headless-workpaper)
|
|
231
|
+
- agent framework adapters example:
|
|
232
|
+
[`npm run agent:framework-adapters`](https://github.com/proompteng/bilig/tree/main/examples/headless-workpaper#agent-framework-adapters)
|
|
225
233
|
- JSON records input example:
|
|
226
234
|
[`npm run json-records`](https://github.com/proompteng/bilig/tree/main/examples/headless-workpaper#json-records-input)
|
|
227
235
|
- Formula diagnostics example:
|
|
@@ -256,6 +264,8 @@ Repository links:
|
|
|
256
264
|
[`docs/hyperformula-alternative-headless-workpaper.md`](https://github.com/proompteng/bilig/blob/main/docs/hyperformula-alternative-headless-workpaper.md)
|
|
257
265
|
- SheetJS and ExcelJS comparison:
|
|
258
266
|
[`docs/sheetjs-exceljs-alternative-formula-workbook-api.md`](https://github.com/proompteng/bilig/blob/main/docs/sheetjs-exceljs-alternative-formula-workbook-api.md)
|
|
267
|
+
- broader headless spreadsheet engine comparison:
|
|
268
|
+
[`docs/headless-spreadsheet-engine-comparison.md`](https://github.com/proompteng/bilig/blob/main/docs/headless-spreadsheet-engine-comparison.md)
|
|
259
269
|
- local benchmark walkthrough:
|
|
260
270
|
[`docs/local-workpaper-benchmark-walkthrough.md`](https://github.com/proompteng/bilig/blob/main/docs/local-workpaper-benchmark-walkthrough.md)
|
|
261
271
|
- XLOOKUP exact fixture walkthrough:
|
|
@@ -360,6 +370,7 @@ npm install
|
|
|
360
370
|
npm start
|
|
361
371
|
npm run http-json-summary
|
|
362
372
|
npm run agent:tool-call
|
|
373
|
+
npm run agent:framework-adapters
|
|
363
374
|
```
|
|
364
375
|
|
|
365
376
|
For the agent-specific writeback proof, run:
|
|
@@ -376,6 +387,10 @@ outputs survived the round trip.
|
|
|
376
387
|
`readRange`, `setInputCell`, computed before/after values, formula contracts,
|
|
377
388
|
persistence bytes, and restored readback equality.
|
|
378
389
|
|
|
390
|
+
`npm run agent:framework-adapters` maps the same validated WorkPaper operations
|
|
391
|
+
into Vercel AI SDK and LangChain-style tool objects without adding either
|
|
392
|
+
framework as an example dependency.
|
|
393
|
+
|
|
379
394
|
For a framework-neutral recipe that wraps WorkPaper operations as agent-callable
|
|
380
395
|
tools, see
|
|
381
396
|
[`docs/agent-workpaper-tool-calling-recipe.md`](https://github.com/proompteng/bilig/blob/main/docs/agent-workpaper-tool-calling-recipe.md).
|
package/package.json
CHANGED
|
@@ -1,11 +1,13 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@bilig/headless",
|
|
3
|
-
"version": "0.11.
|
|
4
|
-
"description": "Headless spreadsheet engine for Node.js formulas, workbook JSON persistence, and service-side spreadsheet automation.",
|
|
3
|
+
"version": "0.11.30",
|
|
4
|
+
"description": "Headless spreadsheet engine for Node.js formulas, agent tools, workbook JSON persistence, and service-side spreadsheet automation.",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"agent",
|
|
7
|
+
"agent-tools",
|
|
7
8
|
"agents",
|
|
8
9
|
"ai-agents",
|
|
10
|
+
"ai-sdk",
|
|
9
11
|
"ai-spreadsheet",
|
|
10
12
|
"automation",
|
|
11
13
|
"bilig",
|
|
@@ -18,6 +20,7 @@
|
|
|
18
20
|
"headless-spreadsheet",
|
|
19
21
|
"headless-workbook",
|
|
20
22
|
"hyperformula",
|
|
23
|
+
"langchain",
|
|
21
24
|
"local-first",
|
|
22
25
|
"node",
|
|
23
26
|
"node-spreadsheet",
|
|
@@ -27,12 +30,15 @@
|
|
|
27
30
|
"spreadsheet-automation",
|
|
28
31
|
"spreadsheet-engine",
|
|
29
32
|
"spreadsheet-formulas",
|
|
33
|
+
"vercel-ai-sdk",
|
|
30
34
|
"workbook",
|
|
31
35
|
"workbook-api",
|
|
32
36
|
"workbook-automation",
|
|
33
37
|
"workbook-engine",
|
|
34
38
|
"workbook-state",
|
|
35
|
-
"workpaper"
|
|
39
|
+
"workpaper",
|
|
40
|
+
"workpaper-json",
|
|
41
|
+
"xlsx"
|
|
36
42
|
],
|
|
37
43
|
"homepage": "https://proompteng.github.io/bilig/",
|
|
38
44
|
"bugs": {
|
|
@@ -66,9 +72,9 @@
|
|
|
66
72
|
"build": "rm -rf dist tsconfig.tsbuildinfo && tsc -p tsconfig.json"
|
|
67
73
|
},
|
|
68
74
|
"dependencies": {
|
|
69
|
-
"@bilig/core": "0.11.
|
|
70
|
-
"@bilig/formula": "0.11.
|
|
71
|
-
"@bilig/protocol": "0.11.
|
|
75
|
+
"@bilig/core": "0.11.30",
|
|
76
|
+
"@bilig/formula": "0.11.30",
|
|
77
|
+
"@bilig/protocol": "0.11.30"
|
|
72
78
|
},
|
|
73
79
|
"engines": {
|
|
74
80
|
"node": ">=24.0.0"
|