feat: create initial implementation of lib

.github/dependabot.yaml

@@ -0,0 +1,11 @@
+version: 2
+updates:
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "daily"
+
+  - package-ecosystem: "gomod"
+    directory: "/"
+    schedule:
+      interval: "daily"

.github/workflows/ci.yaml

@@ -0,0 +1,78 @@
+name: ci
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - main
+
+permissions:
+  contents: read
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout Code
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+
+      - name: Setup Go
+        uses: actions/setup-go@d35c59abb061a4a6fb18e82ac0862c26744d6ab5 # v5
+        with:
+          go-version: '1.25'
+
+      - name: Run go vet
+        run: go vet ./...
+
+      - name: Check formatting
+        run: |
+          unformatted=$(gofmt -l .)
+          if [ -n "$unformatted" ]; then
+            echo "The following files are not formatted:"
+            echo "$unformatted"
+            exit 1
+          fi
+
+  test-unit:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout Code
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+
+      - name: Setup Go
+        uses: actions/setup-go@d35c59abb061a4a6fb18e82ac0862c26744d6ab5 # v5
+        with:
+          go-version: '1.25'
+
+      - name: Run unit tests
+        run: make test-unit
+
+  test-integration:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout Code
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+
+      - name: Setup Go
+        uses: actions/setup-go@d35c59abb061a4a6fb18e82ac0862c26744d6ab5 # v5
+        with:
+          go-version: '1.25'
+
+      - name: Run integration tests
+        run: make test-integration
+
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout Code
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+
+      - name: Setup Go
+        uses: actions/setup-go@d35c59abb061a4a6fb18e82ac0862c26744d6ab5 # v5
+        with:
+          go-version: '1.25'
+
+      - name: Build
+        run: make build

.github/workflows/release.yaml

@@ -0,0 +1,29 @@
+name: release
+
+on:
+  push:
+    branches:
+      - main
+
+permissions:
+  contents: write
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout Code
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+      - name: Bump Version
+        id: tag_version
+        uses: mathieudutour/github-tag-action@d28fa2ccfbd16e871a4bdf35e11b3ad1bd56c0c1 # v6.2
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          default_bump: minor
+          custom_release_rules: bug:patch:Fixes,chore:patch:Chores,docs:patch:Documentation,feat:minor:Features,refactor:minor:Refactors,test:patch:Tests,ci:patch:Development,dev:patch:Development
+      - name: Create Release
+        uses: ncipollo/release-action@b7eabc95ff50cbeeedec83973935c8f306dfcd0b # v1
+        with:
+          tag: ${{ steps.tag_version.outputs.new_tag }}
+          name: ${{ steps.tag_version.outputs.new_tag }}
+          body: ${{ steps.tag_version.outputs.changelog }}

.github/workflows/semantic-check.yaml

@@ -0,0 +1,26 @@
+name: semantic-check
+on:
+  pull_request_target:
+    types:
+      - opened
+      - edited
+      - synchronize
+
+permissions:
+  contents: read
+  pull-requests: read
+
+jobs:
+  main:
+    name: Semantic Commit Message Check
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout Code
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+      - uses: amannn/action-semantic-pull-request@e32d7e603df1aa1ba07e981f2a23455dee596825 # v5
+        name: Check PR for Semantic Commit Message
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        with:
+          requireScope: false
+          validateSingleCommit: true

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 CruxStack
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

Makefile

@@ -0,0 +1,59 @@
+.PHONY: all build test test-unit test-integration lint fmt vet clean tidy help
+
+GO ?= go
+GOFLAGS ?=
+PACKAGES := $(shell $(GO) list ./... | grep -v '/examples/' | grep -v '/docs/' | grep -v '/integration')
+INTEGRATION_PKG := ./integration/...
+
+all: fmt vet lint test-unit ## Run all checks and unit tests
+
+build: ## Build all packages
+	$(GO) build $(GOFLAGS) ./...
+
+test: test-unit ## Alias for test-unit
+
+test-unit: ## Run unit tests only
+	$(GO) test $(GOFLAGS) $(PACKAGES)
+
+test-unit-v: ## Run unit tests with verbose output
+	$(GO) test $(GOFLAGS) -v $(PACKAGES)
+
+test-integration: ## Run integration tests
+	$(GO) test $(GOFLAGS) -tags=integration $(INTEGRATION_PKG)
+
+test-integration-v: ## Run integration tests with verbose output
+	VERBOSE=1 $(GO) test $(GOFLAGS) -v -tags=integration $(INTEGRATION_PKG)
+
+test-all: test-unit test-integration ## Run all tests (unit + integration)
+
+test-v: ## Run unit tests with verbose output (alias for test-unit-v)
+	$(GO) test $(GOFLAGS) -v $(PACKAGES)
+
+test-race: ## Run tests with race detector
+	$(GO) test $(GOFLAGS) -race $(PACKAGES)
+
+test-cover: ## Run tests with coverage
+	$(GO) test $(GOFLAGS) -cover $(PACKAGES)
+
+test-cover-html: ## Run tests and generate HTML coverage report
+	$(GO) test $(GOFLAGS) -coverprofile=coverage.out $(PACKAGES)
+	$(GO) tool cover -html=coverage.out -o coverage.html
+
+lint: ## Run linter (requires golangci-lint)
+	@which golangci-lint > /dev/null || (echo "golangci-lint not installed, skipping" && exit 0)
+	golangci-lint run ./...
+
+fmt: ## Format code
+	$(GO) fmt ./...
+
+vet: ## Run go vet
+	$(GO) vet ./...
+
+tidy: ## Tidy go.mod
+	$(GO) mod tidy
+
+clean: ## Clean build artifacts
+	rm -f coverage.out coverage.html
+
+help: ## Show this help
+	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | sort | awk 'BEGIN {FS = ":.*?## "}; {printf "\033[36m%-15s\033[0m %s\n", $$1, $$2}'