@hologit/holo-tree 0.0.1

package/README.md

@@ -0,0 +1,125 @@
+# holo-tree-napi
+
+Node.js native binding for [`holo-tree`](../holo-tree) — mutable in-memory git
+trees via [gitoxide](https://github.com/GitoxideLabs/gitoxide), with no `git`
+subprocess.
+
+This crate exposes the narrow slice of holo-tree that record-oriented consumers
+(notably [gitsheets](https://github.com/JarvusInnovations/gitsheets)) need for an
+upsert→commit path. It is intentionally a thin pass-through; it is also the first
+integrated consumer of the new Rust libs, so it doubles as a hardening vehicle —
+rough edges in holo-tree's API are recorded as `Phase-C finding` notes in the
+source and fixed upstream rather than worked around here.
+
+## API
+
+```js
+const { Repo, emptyTreeHash } = require('@hologit/holo-tree');
+
+const repo = Repo.open('/path/to/repo/.git');
+
+const tree = repo.createTreeFromRef('HEAD'); // or repo.createTree() for empty
+tree.writeChild('data/widgets/1.toml', 'id = 1\n'); // hash blob + deep insert
+const treeHash = tree.write(); // flush dirty subtrees → ODB, returns tree hash
+
+const commit = repo.commitTree(treeHash, [parentHash], 'add widget 1');
+repo.updateRef('refs/heads/main', commit);
+
+const bytes = repo.createTreeFromRef(commit).readBlob('data/widgets/1.toml');
+```
+
+Conventions: object ids cross the boundary as lowercase 40-char hex strings;
+blob content crosses as `Buffer` (binary-safe).
+
+### Surface
+
+| Method | holo-tree call | Notes |
+|---|---|---|
+| `Repo.open(gitDir)` | `gix::open().into_sync()` | factory |
+| `repo.createTreeFromRef(ref)` → `Tree` | `repo::create_tree_from_ref` | resolves ref→commit→tree |
+| `repo.createTree()` → `Tree` | `MutableTree::empty` | |
+| `repo.commitTree(treeHash, parents[], msg)` → hash | `repo::commit_tree` | uses git-config identity |
+| `repo.updateRef(ref, hash)` | `repo::update_ref` | |
+| `tree.writeChild(path, text)` → hash | `MutableTree::write_child` | UTF-8 text |
+| `tree.writeChildBytes(path, buf)` → hash | `MutableTree::write_child_bytes` | binary |
+| `tree.readBlob(path)` → `Buffer\|null` | `MutableTree::read_blob` | |
+| `tree.deleteChildDeep(path)` → bool | `MutableTree::delete_child_deep` | |
+| `tree.write()` → treeHash | `MutableTree::write` | |
+| `emptyTreeHash()` → hash | `tree::empty_tree_id` | module fn |
+
+## Building
+
+Requires a Rust toolchain and `@napi-rs/cli` (a devDependency):
+
+```sh
+npm install
+npm run build:debug   # or: npm run build   (release)
+npm test              # node --test against a scratch git repo
+```
+
+`napi build` emits `holo-tree.<triple>.node`. The generated `index.js` loader
+and `index.d.ts` types **are committed**; only the `.node` binaries are
+git-ignored (built per-platform in CI).
+
+## Publishing
+
+Published as the scoped package **`@hologit/holo-tree`** with per-platform
+prebuilt binaries shipped as `optionalDependencies`:
+
+| Platform package | Triple | Built on |
+| --- | --- | --- |
+| `@hologit/holo-tree-linux-x64-gnu` | `x86_64-unknown-linux-gnu` | ubuntu-latest |
+| `@hologit/holo-tree-darwin-arm64` | `aarch64-apple-darwin` | macos-latest |
+| `@hologit/holo-tree-win32-x64-msvc` | `x86_64-pc-windows-msvc` | windows-latest |
+
+Each target builds **natively** on its runner — no cross-compilation. The
+`.github/workflows/holo-tree-napi.yml` workflow builds + smoke-tests all three on
+every PR touching the binding, and on a `holo-tree-v*` tag it builds then
+publishes.
+
+Auth is **npm trusted publishing (OIDC)** — no tokens, matching hologit's
+`publish-npm.yml`. Trusted publishing is configured *per package*, and a package
+can't get a trusted publisher until it exists — so the four packages need a
+**one-time manual bootstrap** before automated releases work.
+
+### One-time bootstrap (manual first publish, then configure trusted publishing)
+
+The four packages all start at an early version (currently `0.0.1`). They must
+exist on npm before trusted publishing can be turned on.
+
+1. **Get the prebuilt binaries.** Run the `holo-tree-napi` workflow (push the
+   branch / open a PR, or trigger `workflow_dispatch`) and download its three
+   `bindings-*` artifacts — they hold the `.node` for each platform. A single
+   machine can't build all three natively, so use the CI artifacts.
+
+2. **Publish all four manually**, logged in as an `@hologit` org member
+   (`npm login`):
+
+   ```sh
+   cd holo-tree-napi
+   npm install
+   npx napi artifacts --dir <downloaded-artifacts-dir>   # → npm/<triple>/*.node
+   # platform packages first, then the main package:
+   for d in npm/*/ ; do ( cd "$d" && npm publish --access public ); done
+   npm publish --access public --ignore-scripts          # main; skip the napi
+                                                         # prepublish GH-release hook
+   ```
+
+3. **Turn on trusted publishing** on npmjs.com for **each** of the four packages
+   → Settings → Trusted Publisher → GitHub Actions, repo
+   `JarvusInnovations/hologit`, workflow `holo-tree-napi.yml`.
+
+### Releases (after bootstrap — fully automated, tokenless)
+
+```sh
+git tag holo-tree-v0.1.0 && git push origin holo-tree-v0.1.0
+```
+
+The tag drives the published version; CI builds all three platforms, then
+publishes via OIDC (provenance + a GitHub release). No secret needed.
+
+To add or drop a platform later, edit `napi.triples.additional` +
+`optionalDependencies` in `package.json`, run `napi create-npm-dir -t .`, add the
+matching matrix entry in the workflow, and (since it's a new package) bootstrap
+
++ trust that one package too.

package/index.d.ts

@@ -0,0 +1,77 @@
+/* tslint:disable */
+/* eslint-disable */
+
+/* auto-generated by NAPI-RS */
+
+/** Git's well-known empty-tree hash (`4b825dc6…`). */
+export declare function emptyTreeHash(): string
+/**
+ * A commit identity (author or committer). `timeSeconds`/`offsetMinutes` are
+ * optional; when omitted the current wall-clock time at UTC is used. Pass them
+ * explicitly to reproduce a specific commit (e.g. match `git commit-tree`
+ * under pinned `GIT_AUTHOR_DATE`/`GIT_COMMITTER_DATE`).
+ */
+export interface Signature {
+  name: string
+  email: string
+  timeSeconds?: number
+  offsetMinutes?: number
+}
+/**
+ * A handle to a git repository, backed by gix.
+ *
+ * Stored as a `ThreadSafeRepository` so the handle is `Send + Sync` and can be
+ * cheaply cloned into each `Tree`; every call derives a thread-local
+ * `gix::Repository` via `to_thread_local()`.
+ */
+export declare class Repo {
+  /**
+   * Open a repository at `gitDir` (a `.git` directory, or any path gix can
+   * discover a repo from).
+   */
+  static open(gitDir: string): Repo
+  /**
+   * Resolve a ref (branch, tag, or commit hash) to its tree and return a
+   * mutable, in-memory view of it.
+   */
+  createTreeFromRef(gitRef: string): Tree
+  /** Create a fresh empty, mutable in-memory tree rooted at this repo. */
+  createTree(): Tree
+  /**
+   * Write a commit object pointing at `treeHash` with `parents`. `author`
+   * and `committer` are optional; each falls back to the repo's configured
+   * identity, then a "holo-tree" default. Returns the new commit hash.
+   */
+  commitTree(treeHash: string, parents: Array<string>, message: string, author?: Signature | undefined | null, committer?: Signature | undefined | null): string
+  /** Point a ref at an object hash. */
+  updateRef(refname: string, hash: string): void
+}
+/**
+ * A mutable, in-memory git tree.
+ *
+ * Holds its own clone of the repo handle so JS callers don't thread a repo
+ * argument through every call.
+ *
+ * Phase-C finding #1: holo-tree's `MutableTree` takes `&gix::Repository` on
+ * nearly every method and keeps a *thread-local* tree cache. We smooth the
+ * first half here (the handle lives on the `Tree`) but NOT the second: each
+ * call does `to_thread_local()`, and whether holo-tree's thread-local cache
+ * stays warm across libuv-dispatched calls is the open ergonomics question to
+ * resolve upstream (e.g. a repo-bound tree handle, or an explicit session/
+ * cache object the consumer owns).
+ */
+export declare class Tree {
+  /**
+   * Hash `content` (UTF-8 text) as a blob and insert it at `path`, creating
+   * intermediate trees as needed. Returns the blob hash.
+   */
+  writeChild(path: string, content: string): string
+  /** Hash raw bytes as a blob and insert at `path`. Binary-safe. */
+  writeChildBytes(path: string, content: Buffer): string
+  /** Read a blob's bytes at `path`, or `null` if no blob exists there. */
+  readBlob(path: string): Buffer | null
+  /** Delete a child at a deep `path`. Returns whether it existed. */
+  deleteChildDeep(path: string): boolean
+  /** Flush dirty subtrees to the ODB and return the resulting tree hash. */
+  write(): string
+}

package/index.js

@@ -0,0 +1,317 @@
+/* tslint:disable */
+/* eslint-disable */
+/* prettier-ignore */
+
+/* auto-generated by NAPI-RS */
+
+const { existsSync, readFileSync } = require('fs')
+const { join } = require('path')
+
+const { platform, arch } = process
+
+let nativeBinding = null
+let localFileExisted = false
+let loadError = null
+
+function isMusl() {
+  // For Node 10
+  if (!process.report || typeof process.report.getReport !== 'function') {
+    try {
+      const lddPath = require('child_process').execSync('which ldd').toString().trim()
+      return readFileSync(lddPath, 'utf8').includes('musl')
+    } catch (e) {
+      return true
+    }
+  } else {
+    const { glibcVersionRuntime } = process.report.getReport().header
+    return !glibcVersionRuntime
+  }
+}
+
+switch (platform) {
+  case 'android':
+    switch (arch) {
+      case 'arm64':
+        localFileExisted = existsSync(join(__dirname, 'holo-tree.android-arm64.node'))
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./holo-tree.android-arm64.node')
+          } else {
+            nativeBinding = require('@hologit/holo-tree-android-arm64')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      case 'arm':
+        localFileExisted = existsSync(join(__dirname, 'holo-tree.android-arm-eabi.node'))
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./holo-tree.android-arm-eabi.node')
+          } else {
+            nativeBinding = require('@hologit/holo-tree-android-arm-eabi')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      default:
+        throw new Error(`Unsupported architecture on Android ${arch}`)
+    }
+    break
+  case 'win32':
+    switch (arch) {
+      case 'x64':
+        localFileExisted = existsSync(
+          join(__dirname, 'holo-tree.win32-x64-msvc.node')
+        )
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./holo-tree.win32-x64-msvc.node')
+          } else {
+            nativeBinding = require('@hologit/holo-tree-win32-x64-msvc')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      case 'ia32':
+        localFileExisted = existsSync(
+          join(__dirname, 'holo-tree.win32-ia32-msvc.node')
+        )
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./holo-tree.win32-ia32-msvc.node')
+          } else {
+            nativeBinding = require('@hologit/holo-tree-win32-ia32-msvc')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      case 'arm64':
+        localFileExisted = existsSync(
+          join(__dirname, 'holo-tree.win32-arm64-msvc.node')
+        )
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./holo-tree.win32-arm64-msvc.node')
+          } else {
+            nativeBinding = require('@hologit/holo-tree-win32-arm64-msvc')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      default:
+        throw new Error(`Unsupported architecture on Windows: ${arch}`)
+    }
+    break
+  case 'darwin':
+    localFileExisted = existsSync(join(__dirname, 'holo-tree.darwin-universal.node'))
+    try {
+      if (localFileExisted) {
+        nativeBinding = require('./holo-tree.darwin-universal.node')
+      } else {
+        nativeBinding = require('@hologit/holo-tree-darwin-universal')
+      }
+      break
+    } catch {}
+    switch (arch) {
+      case 'x64':
+        localFileExisted = existsSync(join(__dirname, 'holo-tree.darwin-x64.node'))
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./holo-tree.darwin-x64.node')
+          } else {
+            nativeBinding = require('@hologit/holo-tree-darwin-x64')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      case 'arm64':
+        localFileExisted = existsSync(
+          join(__dirname, 'holo-tree.darwin-arm64.node')
+        )
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./holo-tree.darwin-arm64.node')
+          } else {
+            nativeBinding = require('@hologit/holo-tree-darwin-arm64')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      default:
+        throw new Error(`Unsupported architecture on macOS: ${arch}`)
+    }
+    break
+  case 'freebsd':
+    if (arch !== 'x64') {
+      throw new Error(`Unsupported architecture on FreeBSD: ${arch}`)
+    }
+    localFileExisted = existsSync(join(__dirname, 'holo-tree.freebsd-x64.node'))
+    try {
+      if (localFileExisted) {
+        nativeBinding = require('./holo-tree.freebsd-x64.node')
+      } else {
+        nativeBinding = require('@hologit/holo-tree-freebsd-x64')
+      }
+    } catch (e) {
+      loadError = e
+    }
+    break
+  case 'linux':
+    switch (arch) {
+      case 'x64':
+        if (isMusl()) {
+          localFileExisted = existsSync(
+            join(__dirname, 'holo-tree.linux-x64-musl.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./holo-tree.linux-x64-musl.node')
+            } else {
+              nativeBinding = require('@hologit/holo-tree-linux-x64-musl')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        } else {
+          localFileExisted = existsSync(
+            join(__dirname, 'holo-tree.linux-x64-gnu.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./holo-tree.linux-x64-gnu.node')
+            } else {
+              nativeBinding = require('@hologit/holo-tree-linux-x64-gnu')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        }
+        break
+      case 'arm64':
+        if (isMusl()) {
+          localFileExisted = existsSync(
+            join(__dirname, 'holo-tree.linux-arm64-musl.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./holo-tree.linux-arm64-musl.node')
+            } else {
+              nativeBinding = require('@hologit/holo-tree-linux-arm64-musl')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        } else {
+          localFileExisted = existsSync(
+            join(__dirname, 'holo-tree.linux-arm64-gnu.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./holo-tree.linux-arm64-gnu.node')
+            } else {
+              nativeBinding = require('@hologit/holo-tree-linux-arm64-gnu')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        }
+        break
+      case 'arm':
+        if (isMusl()) {
+          localFileExisted = existsSync(
+            join(__dirname, 'holo-tree.linux-arm-musleabihf.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./holo-tree.linux-arm-musleabihf.node')
+            } else {
+              nativeBinding = require('@hologit/holo-tree-linux-arm-musleabihf')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        } else {
+          localFileExisted = existsSync(
+            join(__dirname, 'holo-tree.linux-arm-gnueabihf.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./holo-tree.linux-arm-gnueabihf.node')
+            } else {
+              nativeBinding = require('@hologit/holo-tree-linux-arm-gnueabihf')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        }
+        break
+      case 'riscv64':
+        if (isMusl()) {
+          localFileExisted = existsSync(
+            join(__dirname, 'holo-tree.linux-riscv64-musl.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./holo-tree.linux-riscv64-musl.node')
+            } else {
+              nativeBinding = require('@hologit/holo-tree-linux-riscv64-musl')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        } else {
+          localFileExisted = existsSync(
+            join(__dirname, 'holo-tree.linux-riscv64-gnu.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./holo-tree.linux-riscv64-gnu.node')
+            } else {
+              nativeBinding = require('@hologit/holo-tree-linux-riscv64-gnu')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        }
+        break
+      case 's390x':
+        localFileExisted = existsSync(
+          join(__dirname, 'holo-tree.linux-s390x-gnu.node')
+        )
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./holo-tree.linux-s390x-gnu.node')
+          } else {
+            nativeBinding = require('@hologit/holo-tree-linux-s390x-gnu')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      default:
+        throw new Error(`Unsupported architecture on Linux: ${arch}`)
+    }
+    break
+  default:
+    throw new Error(`Unsupported OS: ${platform}, architecture: ${arch}`)
+}
+
+if (!nativeBinding) {
+  if (loadError) {
+    throw loadError
+  }
+  throw new Error(`Failed to load native binding`)
+}
+
+const { emptyTreeHash, Repo, Tree } = nativeBinding
+
+module.exports.emptyTreeHash = emptyTreeHash
+module.exports.Repo = Repo
+module.exports.Tree = Tree

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@hologit/holo-tree",
+  "version": "0.0.1",
+  "description": "Node.js native binding for holo-tree — mutable in-memory git trees via gix",
+  "main": "index.js",
+  "types": "index.d.ts",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/JarvusInnovations/hologit.git",
+    "directory": "holo-tree-napi"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "napi": {
+    "name": "holo-tree",
+    "triples": {
+      "defaults": false,
+      "additional": [
+        "x86_64-unknown-linux-gnu",
+        "aarch64-apple-darwin",
+        "x86_64-pc-windows-msvc"
+      ]
+    }
+  },
+  "files": [
+    "index.js",
+    "index.d.ts"
+  ],
+  "optionalDependencies": {
+    "@hologit/holo-tree-linux-x64-gnu": "0.0.1",
+    "@hologit/holo-tree-darwin-arm64": "0.0.1",
+    "@hologit/holo-tree-win32-x64-msvc": "0.0.1"
+  },
+  "scripts": {
+    "artifacts": "napi artifacts",
+    "build": "napi build --platform --release",
+    "build:debug": "napi build --platform",
+    "prepublishOnly": "napi prepublish -t npm",
+    "test": "node --test test/",
+    "version": "napi version"
+  },
+  "devDependencies": {
+    "@napi-rs/cli": "^2.18.4"
+  }
+}