geolibre-wasm 0.1.0

package/README.md

@@ -0,0 +1,60 @@
+# geolibre-wasm
+
+The [`whitebox_next_gen`](https://github.com/jblindsay/whitebox_next_gen) pure-Rust
+geospatial tool suite, **plus new [GeoLibre](https://github.com/opengeos/GeoLibre)
+tools**, compiled to WebAssembly (WASI) and runnable entirely in the browser,
+Node, Deno, or any bundler. No server, no Python, no native install.
+
+Source repo: [opengeos/geolibre-rust](https://github.com/opengeos/geolibre-rust).
+
+## Install
+
+```bash
+npm install geolibre-wasm
+```
+
+It has a single runtime dependency, [`@bjorn3/browser_wasi_shim`](https://github.com/bjorn3/browser_wasi_shim),
+which runs the WASI binary over an in-memory filesystem.
+
+## Usage
+
+```js
+import { runTool, listTools, listManifests } from "geolibre-wasm/tools";
+
+// every available tool id
+const tools = await listTools();
+
+// run a tool: inputs go into an in-memory /work dir; new files come back out
+const { exitCode, stdout, files } = await runTool("slope", {
+  args: ["--input=/work/dem.tif", "--output=/work/slope.tif", "--units=degrees"],
+  input: { "dem.tif": demBytes }, // Uint8Array
+});
+const slopeCog = files["slope.tif"]; // Uint8Array (Cloud Optimized GeoTIFF)
+```
+
+Inputs are placed under `/work` (keyed by filename); any file a tool writes is
+returned in `files`. Raster outputs are Cloud Optimized GeoTIFFs; vector outputs
+are GeoJSON.
+
+## API
+
+| Export | Description |
+|---|---|
+| `initTools(source?)` | Compile the WASI runner once. Omit `source` in browsers/bundlers; pass wasm bytes or a URL/Response in Node. |
+| `listTools(): Promise<string[]>` | Every available tool id. |
+| `listManifests(): Promise<ToolManifest[]>` | All tool manifests (parameter schemas), for building UIs offline. |
+| `runTool(tool, { args?, input? }): Promise<ToolResult>` | Run one tool over the in-memory filesystem. |
+
+`ToolResult` is `{ exitCode: number, stdout: string[], files: Record<string, Uint8Array> }`.
+
+## Notes
+
+- Bundler users (Vite, etc.): exclude this package from dependency pre-bundling
+  so the `new URL("./geolibre-cli.wasm", import.meta.url)` reference is preserved
+  (e.g. Vite's `optimizeDeps.exclude`).
+- Bounded by WebAssembly's ~4 GiB memory and single-threaded execution; use a
+  server-side path for very large data.
+
+## License
+
+MIT OR Apache-2.0

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "geolibre-wasm",
+  "type": "module",
+  "version": "0.1.0",
+  "description": "Pure-Rust geospatial toolkit (whitebox_next_gen) compiled to WebAssembly (WASI) for GeoLibre's in-browser tool execution",
+  "license": "MIT OR Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/opengeos/geolibre-rust"
+  },
+  "homepage": "https://github.com/opengeos/geolibre-rust",
+  "keywords": ["geospatial", "wasm", "wasi", "gis", "geotiff", "geolibre", "whitebox"],
+  "files": [
+    "geolibre-cli.wasm",
+    "tools.mjs",
+    "tools.d.ts",
+    "README.md"
+  ],
+  "exports": {
+    ".": {
+      "types": "./tools.d.ts",
+      "default": "./tools.mjs"
+    },
+    "./tools": {
+      "types": "./tools.d.ts",
+      "default": "./tools.mjs"
+    }
+  },
+  "dependencies": {
+    "@bjorn3/browser_wasi_shim": "^0.4.2"
+  }
+}

package/tools.d.ts

@@ -0,0 +1,44 @@
+/** Result of running a tool. */
+export interface ToolResult {
+  /** Process exit code (0 = success). */
+  exitCode: number;
+  /** Captured stdout/stderr lines. */
+  stdout: string[];
+  /** New files the tool wrote, keyed by filename (e.g. the --output path's basename). */
+  files: Record<string, Uint8Array>;
+}
+
+export interface RunToolOptions {
+  /** CLI args, e.g. ["--input=/work/dem.tif", "--output=/work/out.tif", "--units=degrees"]. */
+  args?: string[];
+  /** Input files placed under /work, keyed by filename. */
+  input?: Record<string, Uint8Array>;
+}
+
+/** A single parameter in a tool manifest. */
+export interface ToolParam {
+  name: string;
+  [key: string]: unknown;
+}
+
+/** A tool's metadata and parameter schema. */
+export interface ToolManifest {
+  id: string;
+  display_name: string;
+  summary: string;
+  params: ToolParam[];
+  [key: string]: unknown;
+}
+
+/** Compile the WASI tool runner once. Omit `source` in browsers/bundlers; pass
+ *  the wasm bytes or a URL/Response in Node. */
+export function initTools(source?: URL | Response | BufferSource | string): Promise<WebAssembly.Module>;
+
+/** List every available tool id. */
+export function listTools(): Promise<string[]>;
+
+/** Fetch every tool manifest (parameter schemas), for building UIs offline. */
+export function listManifests(): Promise<ToolManifest[]>;
+
+/** Run one tool over an in-memory filesystem. */
+export function runTool(tool: string, opts?: RunToolOptions): Promise<ToolResult>;

package/tools.mjs

@@ -0,0 +1,93 @@
+// geolibre-wasm - run the whitebox_next_gen geospatial tool suite from
+// JavaScript. The tools are the WASI binary `geolibre-cli.wasm`; this module
+// executes them through a WASI shim with an in-memory filesystem, so they run in
+// browsers, Node, Deno, and bundlers without a real disk. Raster outputs are
+// Cloud Optimized GeoTIFFs.
+//
+//   import { runTool, listTools } from "geolibre-wasm/tools";
+//   const { files } = await runTool("slope", {
+//     args: ["--input=/work/dem.tif", "--output=/work/slope.tif", "--units=degrees"],
+//     input: { "dem.tif": demBytes },   // Uint8Array, placed under /work
+//   });
+//   const slopeCog = files["slope.tif"];  // Uint8Array
+import { WASI, File, OpenFile, ConsoleStdout, PreopenDirectory } from "@bjorn3/browser_wasi_shim";
+
+let _module = null;
+
+/**
+ * Compile the WASI tool runner once. In browsers/bundlers it loads the bundled
+ * `geolibre-cli.wasm` relative to this module. In Node (no fetch of file URLs),
+ * pass the wasm bytes or a URL/Response explicitly.
+ * @param {URL|Response|BufferSource|string} [source]
+ * @returns {Promise<WebAssembly.Module>}
+ */
+export async function initTools(source) {
+  if (_module) return _module;
+  if (!source) source = new URL("./geolibre-cli.wasm", import.meta.url);
+  if (source instanceof Uint8Array || source instanceof ArrayBuffer) {
+    _module = await WebAssembly.compile(source);
+  } else if (source instanceof Response) {
+    _module = await WebAssembly.compileStreaming(source);
+  } else {
+    _module = await WebAssembly.compileStreaming(fetch(source));
+  }
+  return _module;
+}
+
+async function exec(argv, inputFiles) {
+  const mod = await initTools();
+  const inNames = new Set(Object.keys(inputFiles));
+  const contents = new Map(
+    Object.entries(inputFiles).map(([k, v]) => [k, new File(new Uint8Array(v))]));
+  const work = new PreopenDirectory("/work", contents);
+  const stdout = [];
+  const fds = [
+    new OpenFile(new File(new Uint8Array())),
+    ConsoleStdout.lineBuffered((s) => stdout.push(s)),
+    ConsoleStdout.lineBuffered((s) => stdout.push(s)),
+    work,
+  ];
+  const wasi = new WASI(["geolibre", ...argv], [], fds, { debug: false });
+  const inst = await WebAssembly.instantiate(mod, { wasi_snapshot_preview1: wasi.wasiImport });
+  let exitCode = 0;
+  try { exitCode = wasi.start(inst); }
+  catch (e) { if (e && e.constructor && e.constructor.name === "WASIProcExit") exitCode = e.code; else throw e; }
+  const files = {};
+  for (const [name, entry] of work.dir.contents) {
+    if (entry.data && !inNames.has(name)) files[name] = entry.data;
+  }
+  return { exitCode, stdout, files };
+}
+
+/**
+ * List every available tool id.
+ * @returns {Promise<string[]>}
+ */
+export async function listTools() {
+  const { stdout } = await exec(["list"], {});
+  return stdout.map((s) => s.trim()).filter(Boolean);
+}
+
+/**
+ * Fetch every tool manifest (id, display name, parameter schema, license tier).
+ * Lets a host build tool dialogs fully offline, without a server.
+ * @returns {Promise<object[]>}
+ */
+export async function listManifests() {
+  const { stdout } = await exec(["manifests"], {});
+  return JSON.parse(stdout.join(""));
+}
+
+/**
+ * Run one tool over an in-memory filesystem.
+ * @param {string} tool  tool id, e.g. "slope" (see {@link listTools})
+ * @param {object} [opts]
+ * @param {string[]} [opts.args]  CLI args, e.g. ["--input=/work/dem.tif","--output=/work/out.tif","--units=degrees"]
+ * @param {Object<string, Uint8Array>} [opts.input]  files placed under /work (key = filename)
+ * @returns {Promise<{exitCode:number, stdout:string[], files:Object<string,Uint8Array>}>}
+ *   `files` contains any new files the tool wrote (e.g. the --output path).
+ */
+export async function runTool(tool, opts = {}) {
+  const { args = [], input = {} } = opts;
+  return exec([tool, ...args], input);
+}