chore: import upstream snapshot with attribution

sdk/node/README.md

@@ -0,0 +1,88 @@
+# @officecli/sdk
+
+A thin **async** Node.js client over [officecli](https://github.com/iOfficeAI/OfficeCLI)'s
+resident pipe. It does one thing: forward a command to the running resident and
+hand back the response. There is no second vocabulary to learn — a command is the
+same object you'd put in an officecli `batch` list.
+
+```bash
+npm install @officecli/sdk
+```
+
+Installing the SDK pulls `@officecli/officecli`, which bundles an auto-updating
+native binary — so the CLI comes with it and you don't manage it separately. If
+the binary is ever missing, the SDK provisions it on first use (downloads the
+bundled signed binary, or falls back to the official installer).
+
+## Usage
+
+```js
+const oc = require('@officecli/sdk');
+
+const doc = await oc.create('report.xlsx', ['--force']);
+try {
+  await doc.send({ command: 'set', path: '/Sheet1/A1', props: { text: 'Hello' } });
+  const a1 = await doc.send({ command: 'get', path: '/Sheet1/A1' }); // → envelope object
+  console.log(a1);
+
+  // Many writes in one round-trip:
+  await doc.batch([
+    { command: 'set', path: '/Sheet1/B1', props: { text: '42' } },
+    { command: 'set', path: '/Sheet1/C1', props: { text: 'world' } },
+  ]);
+} finally {
+  await doc.close(); // flushes to disk
+}
+```
+
+On Node ≥ 24 you can use `await using` and skip the explicit close:
+
+```js
+await using doc = await oc.open('existing.xlsx');
+await doc.send({ command: 'get', path: '/body/p[1]' });
+```
+
+## Two surfaces
+
+- **bootstrap** (infrequent): `create()` / `open()` spawn one CLI process.
+- **hot path**: `send()` / `batch()` are pure pipe round-trips, no per-command
+  process spawn.
+
+## API
+
+- `await create(path, args?, options?)` → `Document` — make a new file. Extra CLI
+  flags pass through verbatim (`['--force']`, `['--type', 'docx']`).
+- `await open(path, options?)` → `Document` — open an existing file.
+- `Document.send(item, asJson = true, timeoutMs?)` — forward one command.
+  `asJson = false` requests plain-text output (view/raw/dump).
+- `Document.batch(items, { force = true, stopOnError = false, timeoutMs? })`.
+- `Document.alive(timeoutMs?)` — is a resident serving this file?
+- `Document.close()` — stop the resident (flushes to disk).
+- `install()` — run the official installer (unix only).
+
+`options`: `{ binary?, timeoutMs?, autoInstall? }`. Pass `binary` to point at a
+specific officecli; `autoInstall: false` to disable provisioning a missing CLI.
+
+## Errors vs business outcomes
+
+Transport/process failures throw `OfficeCliError`. Business outcomes are **not**
+exceptions — they live in the returned envelope's `success` field, exactly like
+the CLI's exit code. Check `result.success` yourself.
+
+## Lifecycle
+
+```js
+// Owner — close on exit:
+const d = await oc.open(f);
+try { /* ... */ } finally { await d.close(); }
+
+// Borrow — leave a resident another program owns running:
+const d = await oc.open(f);
+await d.send(/* ... */); // no close()
+```
+
+A dead resident is transparently restarted and the command retried once. An
+alive-but-busy pipe raises `OfficeCliError` (retry, or `close()` and reopen) —
+the SDK never bypasses a live resident, which would race its save.
+
+Licensed under Apache-2.0.