Merge pull request #17 from artiz/claude/nodejs-bun-typescript-bindings-8pk2wk

ci(node): make npm-publish tag optional (default: latest master)

Author: artiz

.github/workflows/ci.yml

@@ -33,7 +33,7 @@ jobs:
     name: fmt · clippy (pinned)
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v5
 
       - uses: dtolnay/rust-toolchain@master
         with:
@@ -52,7 +52,7 @@ jobs:
     name: test (stable)
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v5
 
       # Tests stay on the current stable so they catch real compiler breakage.
       - uses: dtolnay/rust-toolchain@stable
@@ -75,7 +75,7 @@ jobs:
     permissions:
       contents: write # push the version-bump commit + tag
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v5
         with:
           fetch-depth: 0 # full history + tags, for the semantic version bump
           # Push the release commit + tag as an admin PAT so it satisfies the

.github/workflows/npm-publish.yml

@@ -5,10 +5,12 @@
 # package plus per-platform `optionalDependencies` (fleischwolf-<triple>) via
 # napi-rs and publishes them all.
 #
-# Trigger: manual only (workflow_dispatch). Pick the release tag to build — the
-# workflow checks out that tag and publishes the npm version derived from it, so
-# npm releases stay decoupled from the crates.io release on every master push.
-# Run it from the Actions tab (or `gh workflow run npm-publish.yml -f tag=v0.7.0`).
+# Trigger: manual only (workflow_dispatch). By default it builds the latest
+# master (the version in the workspace Cargo.toml); optionally pass a release
+# tag to build that instead. Either way the workflow checks out the chosen ref
+# and publishes, so npm releases stay decoupled from the crates.io release on
+# every master push. Run it from the Actions tab (or
+# `gh workflow run npm-publish.yml`, optionally `-f tag=v0.7.0`).
 #
 # Requires one repository secret: NPM_TOKEN — an npm automation token with
 # publish rights to `fleischwolf` and the `fleischwolf-*` platform packages.
@@ -19,15 +21,16 @@ on:
   workflow_dispatch:
     inputs:
       tag:
-        description: "Release tag to build and publish (e.g. v0.7.0)."
-        required: true
+        description: "Release tag to build (e.g. v0.7.0). Blank = latest master."
+        required: false
+        default: ""
       version:
-        description: "Override the npm version (e.g. 0.7.0). Blank = derive from the tag."
+        description: "Override the npm version (e.g. 0.7.0). Blank = tag, or workspace version on master."
         required: false
         default: ""
 
 concurrency:
-  group: npm-publish-${{ inputs.tag }}
+  group: npm-publish-${{ inputs.tag || github.ref }}
   cancel-in-progress: false
 
 defaults:
@@ -48,16 +51,19 @@ jobs:
           # ONNX/ort build). Requires the arm64 runner image to be available.
           - target: aarch64-unknown-linux-gnu
             host: ubuntu-24.04-arm
-          - target: x86_64-apple-darwin
-            host: macos-13
-          - target: aarch64-apple-darwin
-            host: macos-14
+          # macOS (darwin) prebuilds are omitted: GitHub-hosted macOS runners are
+          # blocked in this environment, and darwin can't be cross-compiled on
+          # Linux (needs the Apple SDK). macOS users build from source. To re-add
+          # when macOS runners are available, add the darwin targets back here AND
+          # to `napi.triples.additional` in package.json:
+          #   - { target: aarch64-apple-darwin, host: macos-14 }
+          #   - { target: x86_64-apple-darwin,  host: macos-14 }  # cross via --target
           - target: x86_64-pc-windows-msvc
             host: windows-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v5
         with:
-          ref: ${{ inputs.tag }}
+          ref: ${{ inputs.tag || github.ref }}
 
       - uses: dtolnay/rust-toolchain@stable
         with:
@@ -69,7 +75,7 @@ jobs:
           key: ${{ matrix.target }}
           workspaces: "."
 
-      - uses: actions/setup-node@v4
+      - uses: actions/setup-node@v5
         with:
           node-version: 20
 
@@ -88,7 +94,7 @@ jobs:
         run: npx napi build --platform --release --target ${{ matrix.target }} --js native.js --dts native.d.ts
 
       - name: Upload prebuilt binary
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v5
         with:
           name: bindings-${{ matrix.target }}
           path: crates/fleischwolf-node/fleischwolf.*.node
@@ -98,7 +104,7 @@ jobs:
       # linux-x64 build) for the publish job to include in the main package.
       - name: Upload JS binding
         if: matrix.target == 'x86_64-unknown-linux-gnu'
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v5
         with:
           name: js-binding
           path: |
@@ -111,11 +117,11 @@ jobs:
     needs: build
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v5
         with:
-          ref: ${{ inputs.tag }}
+          ref: ${{ inputs.tag || github.ref }}
 
-      - uses: actions/setup-node@v4
+      - uses: actions/setup-node@v5
         with:
           node-version: 20
           registry-url: "https://registry.npmjs.org"
@@ -125,26 +131,33 @@ jobs:
 
       # Prebuilt binaries → artifacts/<name>/fleischwolf.<triple>.node
       - name: Download prebuilt binaries
-        uses: actions/download-artifact@v4
+        uses: actions/download-artifact@v5
         with:
           pattern: bindings-*
           path: crates/fleischwolf-node/artifacts
 
       # The JS loader + types → the package root.
       - name: Download JS binding
-        uses: actions/download-artifact@v4
+        uses: actions/download-artifact@v5
         with:
           name: js-binding
           path: crates/fleischwolf-node
 
-      # Version = the explicit override, else the selected tag with its leading `v`.
+      # Version = the explicit override, else the selected tag (sans leading `v`),
+      # else the workspace version from the root Cargo.toml (latest-master run).
       - name: Resolve version
         id: ver
         run: |
           v="${{ inputs.version }}"
-          if [ -z "$v" ]; then v="${{ inputs.tag }}"; v="${v#v}"; fi
+          if [ -z "$v" ]; then
+            if [ -n "${{ inputs.tag }}" ]; then
+              v="${{ inputs.tag }}"; v="${v#v}"
+            else
+              v="$(grep -m1 '^version = ' ../../Cargo.toml | sed -E 's/.*"([^"]+)".*/\1/')"
+            fi
+          fi
           echo "version=$v" >> "$GITHUB_OUTPUT"
-          echo "Publishing fleischwolf@$v from tag ${{ inputs.tag }}"
+          echo "Publishing fleischwolf@$v (ref: ${{ inputs.tag || github.ref }})"
 
       # Skip cleanly if this version is already on npm (idempotent re-runs).
       - name: Check if already published

README.md

@@ -154,32 +154,45 @@ The CLI streams Markdown by default (`--no-stream` opts back into buffering;
 
 ## Node.js / Bun bindings
 
-Native TypeScript bindings live in
-[`crates/fleischwolf-node`](./crates/fleischwolf-node) (built with
-[napi-rs](https://napi.rs)). They ship a real `.node` addon that loads in both
-Node.js and Bun (Bun implements N-API — same binary, no rebuild), exposing the
-converter with the same knobs as the Rust API: Markdown / docling JSON output,
-`strict` mode, image modes, allowed-format restriction, `fetchImages`, sync +
-async (`Promise`) calls, and a `streamFileMarkdown` async generator.
+Fleischwolf ships as an npm package, [**`fleischwolf`**](https://www.npmjs.com/package/fleischwolf)
+— native TypeScript bindings (built with [napi-rs](https://napi.rs)) that live in
+[`crates/fleischwolf-node`](./crates/fleischwolf-node). It's a real `.node` addon
+that loads in both Node.js and Bun (Bun implements N-API — same binary, no
+rebuild), exposing the converter with the same knobs as the Rust API: Markdown /
+docling JSON output, `strict` mode, image modes, allowed-format restriction,
+`fetchImages`, sync + async (`Promise`) calls, and a `streamFileMarkdown` async
+generator.
+
+Install — no Rust toolchain needed, the prebuilt binary for your platform (Linux
+x64/arm64, Windows x64) is pulled in automatically:
 
 ```bash
-cd crates/fleischwolf-node && npm install && npm run build
+npm install fleischwolf   # or: bun add fleischwolf
 ```
 
 ```ts
-import { convertFile, convertFileAsync, streamFileMarkdown } from 'fleischwolf'
+import { convert, convertFile, convertFileAsync } from 'fleischwolf'
 
-const { content } = convertFile('report.docx')          // Markdown
-const json = await convertFileAsync('paper.pdf', { to: 'json' })
-for await (const chunk of streamFileMarkdown('paper.pdf')) process.stdout.write(chunk)
+// in-memory bytes → Markdown
+const md = convert({ name: 'notes.md', data: Buffer.from('# Hello\n\nWorld **bold**') })
+console.log(md.content)
+
+// a file → Markdown or docling JSON (format detected from the extension)
+const { content } = convertFile('report.docx')
+const json = await convertFileAsync('report.docx', { to: 'json' })
 ```
 
-Declarative formats work out of the box. The PDF/image pipeline needs pdfium +
-the ONNX models (not bundled), so it throws until you call `installDependencies()`
-— which auto-downloads pdfium/OCR and fetches the layout/TableFormer ONNX from a
-`modelsUrl` you host. A reusable `Pipeline` keeps those models warm across many
-PDFs. See [`crates/fleischwolf-node/README.md`](./crates/fleischwolf-node/README.md)
-for the full API and runnable Node + Bun examples.
+Declarative formats (Markdown, HTML, DOCX, XLSX, …) work out of the box. The
+PDF/image pipeline needs pdfium + the ONNX models (not bundled), so it throws
+until you call `installDependencies()` — which auto-downloads pdfium/OCR and
+fetches the layout/TableFormer ONNX from a `modelsUrl` you host. A reusable
+`Pipeline` keeps those models warm across many PDFs.
+
+Runnable Node + Bun examples are in
+[`crates/fleischwolf-node/examples`](./crates/fleischwolf-node/examples)
+(`npm install && node node-basic.mjs`). See
+[`crates/fleischwolf-node/README.md`](./crates/fleischwolf-node/README.md) for
+the full API.
 
 ## Testing
 

crates/fleischwolf-node/README.md

@@ -19,12 +19,13 @@ needed to use the package:
 npm install fleischwolf   # or: bun add fleischwolf
 ```
 
-Prebuilt platforms: Linux x64 / arm64 (glibc), macOS x64 / arm64, Windows x64.
-The right binary is pulled in automatically as a platform-specific
-`optionalDependency` (`fleischwolf-<triple>`). Releases are published to npm by
+Prebuilt platforms: Linux x64 / arm64 (glibc) and Windows x64. (macOS isn't
+prebuilt — build from source, see below.) The right binary is pulled in
+automatically as a platform-specific `optionalDependency` (`fleischwolf-<triple>`). Releases are published to npm by
 manually running the `npm publish` workflow
-(`.github/workflows/npm-publish.yml`) for a chosen release tag — decoupled from
-the crates.io release.
+(`.github/workflows/npm-publish.yml`) — by default it builds the latest master
+(the workspace version); optionally pass a release tag to build that instead.
+Decoupled from the crates.io release.
 
 ## Build from source
 
@@ -226,16 +227,23 @@ Full TypeScript types are generated into `index.d.ts` / `native.d.ts`.
 
 ## Examples
 
+The [`examples/`](examples) folder is a self-contained project that depends on
+the published `fleischwolf` package — `npm install` there, then run any of them:
+
+```bash
+cd examples
+npm install
+node node-basic.mjs        # ESM: file, bytes, JSON, reuse
+bun run bun-basic.ts       # Bun + TypeScript: async + streaming
+node pdf-pipeline.mjs       # installDependencies + warm Pipeline for PDFs
+```
+
 - [`examples/node-basic.mjs`](examples/node-basic.mjs) — Node.js (ESM): file, bytes, JSON, reuse.
 - [`examples/bun-basic.ts`](examples/bun-basic.ts) — Bun + TypeScript, with async and streaming.
 - [`examples/pdf-pipeline.mjs`](examples/pdf-pipeline.mjs) — `installDependencies` + warm `Pipeline` for PDFs.
 
-```bash
-npm run build          # once
-node examples/node-basic.mjs
-bun run examples/bun-basic.ts
-node test/smoke.mjs    # or: bun test/smoke.mjs
-```
+The smoke test exercises the locally-built addon instead: `npm run build` once at
+the package root, then `node test/smoke.mjs` (or `bun test/smoke.mjs`).
 
 ## License
 

crates/fleischwolf-node/examples/.gitignore

@@ -0,0 +1,4 @@
+node_modules/
+package-lock.json
+bun.lockb
+artifacts/

crates/fleischwolf-node/examples/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "fleischwolf-examples",
+  "version": "0.0.0",
+  "private": true,
+  "description": "Runnable examples for the fleischwolf npm package. Run `npm install` here, then the scripts below.",
+  "type": "module",
+  "scripts": {
+    "start": "node node-basic.mjs",
+    "node": "node node-basic.mjs",
+    "bun": "bun run bun-basic.ts",
+    "pdf": "node pdf-pipeline.mjs"
+  },
+  "dependencies": {
+    "fleischwolf": "^0.6.1"
+  }
+}

crates/fleischwolf-node/package.json

@@ -35,8 +35,6 @@
       "additional": [
         "x86_64-unknown-linux-gnu",
         "aarch64-unknown-linux-gnu",
-        "x86_64-apple-darwin",
-        "aarch64-apple-darwin",
         "x86_64-pc-windows-msvc"
       ]
     }
@@ -59,8 +57,8 @@
     "prepublishOnly": "napi prepublish -t npm --skip-gh-release",
     "version": "napi version",
     "test": "node test/smoke.mjs",
-    "example": "node examples/node-basic.mjs",
-    "example:bun": "bun run examples/bun-basic.ts"
+    "example": "npm --prefix examples install && node examples/node-basic.mjs",
+    "example:bun": "npm --prefix examples install && bun run examples/bun-basic.ts"
   },
   "devDependencies": {
     "@napi-rs/cli": "^2.18.4"