@bilig/headless 0.11.16 → 0.11.21
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 +91 -2
- package/package.json +4 -4
package/README.md
CHANGED
|
@@ -22,6 +22,46 @@ Requires Node `24+` and ESM imports.
|
|
|
22
22
|
npm install @bilig/headless
|
|
23
23
|
```
|
|
24
24
|
|
|
25
|
+
## Clean npm Sanity Check
|
|
26
|
+
|
|
27
|
+
Run this from an empty directory when you want to verify the published package
|
|
28
|
+
before cloning the repository:
|
|
29
|
+
|
|
30
|
+
```sh
|
|
31
|
+
mkdir bilig-headless-sanity
|
|
32
|
+
cd bilig-headless-sanity
|
|
33
|
+
npm init -y
|
|
34
|
+
npm install @bilig/headless
|
|
35
|
+
node --input-type=module <<'EOF'
|
|
36
|
+
import { WorkPaper } from '@bilig/headless'
|
|
37
|
+
|
|
38
|
+
const workbook = WorkPaper.buildFromSheets({
|
|
39
|
+
Revenue: [
|
|
40
|
+
['Units', 'Price', 'Revenue'],
|
|
41
|
+
[7, 6, '=A2*B2'],
|
|
42
|
+
],
|
|
43
|
+
})
|
|
44
|
+
|
|
45
|
+
const sheet = workbook.getSheetId('Revenue')
|
|
46
|
+
if (sheet === undefined) {
|
|
47
|
+
throw new Error('Revenue sheet was not created')
|
|
48
|
+
}
|
|
49
|
+
|
|
50
|
+
const cell = workbook.getCellValue({ sheet, row: 1, col: 2 })
|
|
51
|
+
if (typeof cell !== 'object' || cell === null || cell.value !== 42) {
|
|
52
|
+
throw new Error(`unexpected formula readback: ${JSON.stringify(cell)}`)
|
|
53
|
+
}
|
|
54
|
+
|
|
55
|
+
console.log({ revenue: cell.value, verified: true })
|
|
56
|
+
EOF
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
Expected output:
|
|
60
|
+
|
|
61
|
+
```json
|
|
62
|
+
{ "revenue": 42, "verified": true }
|
|
63
|
+
```
|
|
64
|
+
|
|
25
65
|
Inside this monorepo:
|
|
26
66
|
|
|
27
67
|
```sh
|
|
@@ -31,11 +71,31 @@ pnpm --filter @bilig/headless build
|
|
|
31
71
|
|
|
32
72
|
## Start Here
|
|
33
73
|
|
|
34
|
-
- Run the [
|
|
74
|
+
- Run the [clean npm sanity check](#clean-npm-sanity-check) before cloning, or
|
|
75
|
+
the [quickstart](#quickstart) for a one-file formula and persistence
|
|
35
76
|
smoke test.
|
|
36
77
|
- Try the runnable examples:
|
|
37
78
|
[`examples/headless-workpaper`](https://github.com/proompteng/bilig/tree/main/examples/headless-workpaper) and
|
|
38
|
-
[`npm run json-records`](https://github.com/proompteng/bilig/tree/main/examples/headless-workpaper#json-records-input)
|
|
79
|
+
[`npm run json-records`](https://github.com/proompteng/bilig/tree/main/examples/headless-workpaper#json-records-input)
|
|
80
|
+
for in-process records, or
|
|
81
|
+
[`npm run json-file`](https://github.com/proompteng/bilig/tree/main/examples/headless-workpaper#json-file-input)
|
|
82
|
+
for records already saved on disk, or
|
|
83
|
+
[`npm run formula-diagnostics`](https://github.com/proompteng/bilig/tree/main/examples/headless-workpaper#formula-diagnostics)
|
|
84
|
+
for structured formula error handling, or
|
|
85
|
+
[`npm run markdown-report`](https://github.com/proompteng/bilig/tree/main/examples/headless-workpaper#markdown-report-output)
|
|
86
|
+
for a calculated Markdown table, or
|
|
87
|
+
[`npm run snapshot-diff`](https://github.com/proompteng/bilig/tree/main/examples/headless-workpaper#snapshot-diff)
|
|
88
|
+
for before/after persisted-state comparison, or
|
|
89
|
+
[`npm run range-readback`](https://github.com/proompteng/bilig/tree/main/examples/headless-workpaper#range-readback)
|
|
90
|
+
for computed values and serialized formulas from the same range, or
|
|
91
|
+
[`npm run sheet-inspection`](https://github.com/proompteng/bilig/tree/main/examples/headless-workpaper#sheet-inspection)
|
|
92
|
+
for checking restored workbook shape before writes, or
|
|
93
|
+
[`npm run http-json-summary`](https://github.com/proompteng/bilig/tree/main/examples/headless-workpaper#http-json-summary)
|
|
94
|
+
for a no-framework Node HTTP boundary, or
|
|
95
|
+
[`npm run invoice-totals`](https://github.com/proompteng/bilig/tree/main/examples/headless-workpaper#invoice-totals)
|
|
96
|
+
for subtotal, tax, and total formula readback, or
|
|
97
|
+
[`npm run budget-variance`](https://github.com/proompteng/bilig/tree/main/examples/headless-workpaper#budget-variance-alerts)
|
|
98
|
+
for formula-backed budget variance alerts.
|
|
39
99
|
- Run the
|
|
40
100
|
[serverless WorkPaper API example](https://github.com/proompteng/bilig/tree/main/examples/serverless-workpaper-api)
|
|
41
101
|
when the workbook belongs behind an HTTP or agent-tool boundary.
|
|
@@ -53,6 +113,24 @@ pnpm --filter @bilig/headless build
|
|
|
53
113
|
- Star or bookmark the project:
|
|
54
114
|
<https://github.com/proompteng/bilig>.
|
|
55
115
|
|
|
116
|
+
## Which Example Should I Run?
|
|
117
|
+
|
|
118
|
+
The full example catalog lives in
|
|
119
|
+
[`examples/headless-workpaper/README.md`](https://github.com/proompteng/bilig/blob/main/examples/headless-workpaper/README.md).
|
|
120
|
+
|
|
121
|
+
| Need | Start with | Existing example |
|
|
122
|
+
| ------------------------------------ | --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
|
|
123
|
+
| 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) |
|
|
124
|
+
| 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) |
|
|
125
|
+
| Persist and restore a workbook | `npm run persistence` | [Persistence round trip](https://github.com/proompteng/bilig/tree/main/examples/headless-workpaper#persistence-round-trip) |
|
|
126
|
+
| Verify an agent writeback | `npm run agent:verify` | [Agent writeback verification](https://github.com/proompteng/bilig/tree/main/examples/headless-workpaper#agent-writeback-verification) |
|
|
127
|
+
| 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) |
|
|
128
|
+
| Flag budget variance rows | `npm run budget-variance` | [Budget variance alerts](https://github.com/proompteng/bilig/tree/main/examples/headless-workpaper#budget-variance-alerts) |
|
|
129
|
+
| 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) |
|
|
130
|
+
| Calculate invoice totals | `npm run invoice-totals` | [Invoice totals](https://github.com/proompteng/bilig/tree/main/examples/headless-workpaper#invoice-totals) |
|
|
131
|
+
| Inspect restored workbook shape | `npm run sheet-inspection` | [Sheet inspection](https://github.com/proompteng/bilig/tree/main/examples/headless-workpaper#sheet-inspection) |
|
|
132
|
+
| Compare computed values and formulas | `npm run range-readback` | [Range readback](https://github.com/proompteng/bilig/tree/main/examples/headless-workpaper#range-readback) |
|
|
133
|
+
|
|
56
134
|
## Production Status
|
|
57
135
|
|
|
58
136
|
Use this package in production for documented WorkPaper/headless API workflows:
|
|
@@ -135,6 +213,16 @@ Repository links:
|
|
|
135
213
|
[`examples/headless-workpaper`](https://github.com/proompteng/bilig/tree/main/examples/headless-workpaper)
|
|
136
214
|
- JSON records input example:
|
|
137
215
|
[`npm run json-records`](https://github.com/proompteng/bilig/tree/main/examples/headless-workpaper#json-records-input)
|
|
216
|
+
- Formula diagnostics example:
|
|
217
|
+
[`npm run formula-diagnostics`](https://github.com/proompteng/bilig/tree/main/examples/headless-workpaper#formula-diagnostics)
|
|
218
|
+
- Markdown report output example:
|
|
219
|
+
[`npm run markdown-report`](https://github.com/proompteng/bilig/tree/main/examples/headless-workpaper#markdown-report-output)
|
|
220
|
+
- Snapshot diff example:
|
|
221
|
+
[`npm run snapshot-diff`](https://github.com/proompteng/bilig/tree/main/examples/headless-workpaper#snapshot-diff)
|
|
222
|
+
- Range readback example:
|
|
223
|
+
[`npm run range-readback`](https://github.com/proompteng/bilig/tree/main/examples/headless-workpaper#range-readback)
|
|
224
|
+
- Sheet inspection example:
|
|
225
|
+
[`npm run sheet-inspection`](https://github.com/proompteng/bilig/tree/main/examples/headless-workpaper#sheet-inspection)
|
|
138
226
|
- serverless API route example:
|
|
139
227
|
[`examples/serverless-workpaper-api`](https://github.com/proompteng/bilig/tree/main/examples/serverless-workpaper-api)
|
|
140
228
|
- Node service recipe:
|
|
@@ -259,6 +347,7 @@ restores the workbook, and verifies the final result.
|
|
|
259
347
|
cd examples/headless-workpaper
|
|
260
348
|
npm install
|
|
261
349
|
npm start
|
|
350
|
+
npm run http-json-summary
|
|
262
351
|
npm run agent:tool-call
|
|
263
352
|
```
|
|
264
353
|
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@bilig/headless",
|
|
3
|
-
"version": "0.11.
|
|
3
|
+
"version": "0.11.21",
|
|
4
4
|
"description": "Headless spreadsheet engine for Node.js formulas, workbook JSON persistence, and service-side spreadsheet automation.",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"agent",
|
|
@@ -66,9 +66,9 @@
|
|
|
66
66
|
"build": "rm -rf dist tsconfig.tsbuildinfo && tsc -p tsconfig.json"
|
|
67
67
|
},
|
|
68
68
|
"dependencies": {
|
|
69
|
-
"@bilig/core": "0.11.
|
|
70
|
-
"@bilig/formula": "0.11.
|
|
71
|
-
"@bilig/protocol": "0.11.
|
|
69
|
+
"@bilig/core": "0.11.21",
|
|
70
|
+
"@bilig/formula": "0.11.21",
|
|
71
|
+
"@bilig/protocol": "0.11.21"
|
|
72
72
|
},
|
|
73
73
|
"engines": {
|
|
74
74
|
"node": ">=24.0.0"
|