feat: implement TypeScript bindings for NVIDIA Management Library

Provides type-safe access to NVML for GPU monitoring, replacing
inefficient nvidia-smi CLI calls with direct library access via
Koffi FFI.

Features:
- Nvml namespace for library initialization and system queries
- Device class with methods for memory, temperature, power,
  utilization, and process monitoring
- Result<T> type for safe error handling without exceptions
- Lazy function binding for optimal performance
- Comprehensive type definitions for all NVML structures

Includes:
- Unit tests with NVML mocks (no GPU required)
- API documentation and usage examples
- ESLint and TypeScript configuration
- GitHub Actions CI workflow

---
Signed-off-by: Guillaume Moutier <guimou@users.noreply.github.com>
Co-authored-by: Claude

Author: guimou

.github/workflows/ci.yml

@@ -0,0 +1,52 @@
+name: CI
+
+on:
+  push:
+    branches: [main, dev]
+  pull_request:
+    branches: [main]
+
+jobs:
+  build-and-test:
+    runs-on: ubuntu-latest
+
+    strategy:
+      matrix:
+        node-version: [22.x]
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js ${{ matrix.node-version }}
+        uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node-version }}
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run linter
+        run: npm run lint
+
+      - name: Run type check
+        run: npm run typecheck
+
+      - name: Build
+        run: npm run build
+
+      - name: Run unit tests
+        run: npm run test:unit
+
+  # Integration tests would require a GPU runner
+  # integration-test:
+  #   runs-on: [self-hosted, gpu]
+  #   steps:
+  #     - uses: actions/checkout@v4
+  #     - uses: actions/setup-node@v4
+  #       with:
+  #         node-version: 22.x
+  #     - run: npm ci
+  #     - run: npm run build
+  #     - run: npm run test:integration

.gitignore

@@ -0,0 +1,45 @@
+# Dependencies
+node_modules/
+
+# Build output
+dist/
+
+# Test coverage
+coverage/
+
+# IDE and editors
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# OS files
+.DS_Store
+Thumbs.db
+
+# Logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# Environment files
+.env
+.env.local
+.env.*.local
+
+# Temporary files
+tmp/
+temp/
+*.tmp
+
+# Lock files (optional - uncomment if you want to ignore)
+# package-lock.json
+# yarn.lock
+
+# TypeScript cache
+*.tsbuildinfo
+
+# Claude
+.claude

CHANGELOG.md

@@ -0,0 +1,35 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-01-20
+
+### Added
+
+- **Nvml namespace** for library initialization and system queries
+  - `init()` / `shutdown()` for lifecycle management
+  - `getDriverVersion()` and `getNvmlVersion()` for version info
+  - `getDeviceCount()` and `getDeviceByIndex()` for device enumeration
+- **Device class** with comprehensive GPU monitoring methods
+  - Memory info (`getMemoryInfo()`)
+  - Temperature (`getTemperature()`)
+  - Power usage and limits (`getPowerUsage()`, `getPowerLimit()`)
+  - GPU/memory utilization (`getUtilization()`)
+  - Clock speeds (`getClockInfo()`)
+  - P-state and compute mode (`getPState()`, `getComputeMode()`)
+  - Running processes (`getRunningProcesses()`)
+  - Device identification (`getName()`, `getUuid()`, `getSerial()`)
+- **Result<T> type** for safe error handling without exceptions
+  - `ok()` / `err()` constructors
+  - `unwrap()` / `unwrapOr()` helpers
+  - `isOk()` / `isErr()` type guards
+- **Lazy function binding** for optimal startup performance
+- **Comprehensive type definitions** for all NVML structures and enums
+- **Unit tests** with NVML mocks (no GPU required to run)
+- **API documentation** with usage examples
+- **GitHub Actions CI** workflow for automated testing
+
+[0.1.0]: https://github.com/rh-aiservices-bu/ts-nvml/releases/tag/v0.1.0

CLAUDE.md

@@ -0,0 +1,96 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+ts-nvml is a TypeScript binding for NVIDIA Management Library (NVML). It provides direct access to GPU monitoring functions via Koffi FFI, replacing inefficient nvidia-smi CLI calls.
+
+## Commands
+
+```bash
+# Install dependencies
+npm install
+
+# Build TypeScript
+npm run build
+
+# Type check without emitting
+npm run typecheck
+
+# Run tests
+npm test
+
+# Run example (requires NVIDIA GPU)
+npx tsx examples/basic-usage.ts
+```
+
+## Architecture
+
+```
+src/
+├── index.ts              # Public API exports
+├── nvml.ts               # Nvml namespace (init, shutdown, system queries)
+├── device.ts             # Device class with query methods
+├── types/
+│   ├── enums.ts          # NvmlReturn, NvmlPState, NvmlComputeMode, etc.
+│   ├── structs.ts        # MemoryInfo, GpuStatus, SystemSnapshot, etc.
+│   └── result.ts         # Result<T> type and NvmlError
+├── bindings/
+│   ├── library.ts        # Koffi library loading
+│   ├── types.ts          # Koffi struct definitions (nvmlMemory_t, etc.)
+│   ├── init.ts           # nvmlInit, nvmlShutdown bindings
+│   └── device.ts         # Device query bindings (memory, temp, power, etc.)
+└── utils/
+    └── library-path.ts   # NVML library discovery
+```
+
+## Key Patterns
+
+### Result Type for Error Handling
+All query methods return `Result<T>` instead of throwing:
+```typescript
+const result = device.getMemoryInfo();
+if (result.ok) {
+  console.log(result.value.total);
+} else {
+  console.error(result.error.message);
+}
+
+// Or use unwrap() to throw on error
+const memory = unwrap(device.getMemoryInfo());
+```
+
+### Lazy Function Binding
+NVML functions are bound lazily on first use to avoid loading the library at import time:
+```typescript
+let _nvmlInit: NvmlFunc | null = null;
+function getNvmlInit(): NvmlFunc {
+  if (!_nvmlInit) {
+    _nvmlInit = getLibrary().func('int nvmlInit_v2()') as NvmlFunc;
+  }
+  return _nvmlInit;
+}
+```
+
+### Koffi Output Parameters
+Primitive outputs use arrays, structs use objects:
+```typescript
+// Primitive: use array wrapper
+const count = [0];
+getDeviceGetCount()(count);  // count[0] now has value
+
+// Struct: use object
+const memory = { total: 0n, free: 0n, used: 0n };
+getDeviceGetMemoryInfo()(device, memory);  // memory now populated
+```
+
+## Testing
+
+- Unit tests don't require a GPU (use mocks)
+- Integration tests require an NVIDIA GPU with drivers installed
+- The NVML library path can be overridden via `NVML_LIBRARY_PATH` env var
+
+## License
+
+Apache License 2.0