feat: add uuid utilities package

.editorconfig

@@ -0,0 +1,9 @@
+root = true
+
+[*]
+charset = utf-8
+indent_style = space
+indent_size = 2
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true

.github/actions/use-pnpm-dependencies/action.yml

@@ -0,0 +1,17 @@
+name: "Use pnpm Dependencies"
+
+description: "Checks if the pnpm dependencies have been cached with the hash of the pnpm-lock.yaml file."
+
+runs:
+  using: "composite"
+  steps:
+    - name: "🔧 Setup pnpm"
+      uses: pnpm/action-setup@v4
+    - name: "🔧 Setup Node"
+      uses: actions/setup-node@v4
+      with:
+        node-version: '22'
+        cache: 'pnpm'
+    - name: "📦 Install"
+      run: pnpm install
+      shell: bash

.github/pull_request_template.md

@@ -0,0 +1,23 @@
+<!--
+The title should summarise the purpose of this change.
+
+⚠️**NOTE:** The title must conform to the conventional commit message format outlined in CONTRIBUTING.md document, at the root of the project. This is to ensure the merge commit to the main branch is picked up by the CI and creates an entry in the CHANGELOG.md.
+-->
+
+# Description
+<!-- Describe your changes in detail -->
+
+# Type of change
+<!-- What type of change does this change introduce? Put an 'x' in all the boxes that apply. -->
+
+- [ ] 💥 Breaking change (fix or feature that would cause existing functionality to not work as expected)
+- [ ] 🏗️ Build configuration (CI configuration, scaffolding etc.)
+- [ ] 🐛 Bug fix (non-breaking change which fixes an issue)
+- [ ] 📝 Documentation update(s)
+- [ ] 📦 Dependency update(s)
+- [ ] 👩🏽‍💻 Improve developer experience
+- [ ] ⚡ Improve performance
+- [ ] ✨ New feature (non-breaking change which adds functionality)
+- [ ] ♻ Refactor
+- [ ] ⏪ Revert changes
+- [ ] 🧪 New tests or updates to existing tests

.github/workflows/lint_build_test.yml

@@ -0,0 +1,53 @@
+name: "Lint, Build & Test"
+
+on:
+  workflow_call:
+    inputs:
+      package_name:
+        description: "The pnpm package name."
+        required: true
+        type: string
+
+jobs:
+  lint:
+    name: "Lint"
+    runs-on: ubuntu-latest
+    steps:
+      - name: "🛎 Checkout"
+        uses: actions/checkout@v4
+        with:
+          submodules: recursive
+      - name: "🔧 Setup"
+        uses: ./.github/actions/use-pnpm-dependencies
+      - name: "👕 Lint"
+        run: pnpm -F ${{ inputs.package_name }} run lint
+
+  build:
+    name: "Build"
+    runs-on: ubuntu-latest
+    steps:
+      - name: "🛎 Checkout"
+        uses: actions/checkout@v4
+        with:
+          submodules: recursive
+      - name: "🔧 Setup Node"
+        uses: ./.github/actions/use-pnpm-dependencies
+      - name: "🏗️ Build"
+        run: |
+          pnpm -F ${{ inputs.package_name }} run build:dependencies
+          pnpm -F ${{ inputs.package_name }} run build
+
+  test:
+    name: "Test"
+    runs-on: ubuntu-latest
+    steps:
+      - name: "🛎 Checkout"
+        uses: actions/checkout@v4
+        with:
+          submodules: recursive
+      - name: "🔧 Setup Node"
+        uses: ./.github/actions/use-pnpm-dependencies
+      - name: "🧪 Test"
+        run: |
+          pnpm -F ${{ inputs.package_name }} run build:dependencies
+          pnpm -F ${{ inputs.package_name }} run test

.github/workflows/publish_release.yml

@@ -0,0 +1,59 @@
+name: "Release"
+
+on:
+  workflow_call:
+    inputs:
+      package_dir:
+        description: "The directory name of the package."
+        required: true
+        type: string
+      package_name:
+        description: "The pnpm package name."
+        required: true
+        type: string
+    secrets:
+      NPM_TOKEN:
+        required: true
+
+permissions:
+  contents: write # to be able to publish a github release
+  issues: write # to be able to comment on released issues
+  packages: write  # to be able to publish packages
+  pull-requests: write # to be able to comment on released pull requests
+
+jobs:
+  release:
+    name: "Release"
+    runs-on: ubuntu-latest
+    environment: production
+    steps:
+      - name: "🛎 Checkout"
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0 # use the entire git history for semantic-release to analyze history
+          submodules: recursive # ensure the git submodules are fetched
+      - name: "⤵️ Pull Latest Changes"
+        run: git pull origin ${{ github.ref_name }}
+      - name: "🔧 Setup"
+        uses: ./.github/actions/use-pnpm-dependencies
+      - name: "🏗️ Build"
+        run:  |
+          pnpm -F ${{ inputs.package_name }} run build:dependencies
+          pnpm -F ${{ inputs.package_name }} run build
+      - name: "📝 Create .npmrc"
+        run: |
+          echo "//registry.npmjs.org/:_authToken=${{ secrets.NPM_TOKEN }}" >> .npmrc
+          echo "@agoralabs-sh:registry=https://registry.npmjs.org" >> .npmrc
+          echo "access=public" >> .npmrc
+      - name: "🔖 Release"
+        env:
+          HUSKY: 0 # disable husky
+          # appears on the release commits
+          GIT_AUTHOR_NAME: Kieran O'Neill
+          GIT_AUTHOR_EMAIL: hello@kieranoneill.com
+          GIT_COMMITTER_NAME: Kieran O'Neill
+          GIT_COMMITTER_EMAIL: hello@kieranoneill.com
+          # used to push the release commit and create the tags
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: pnpm exec semantic-release -e semantic-release-monorepo
+        working-directory: ./packages/${{ inputs.package_dir }}

.github/workflows/pull_request_checks.yml

@@ -0,0 +1,56 @@
+name: "Pull Request Checks"
+
+on:
+  pull_request:
+
+jobs:
+  changed_files:
+    name: "Changed Files"
+    runs-on: ubuntu-latest
+    permissions:
+      pull-requests: read
+    outputs:
+      uuid: ${{ steps.filter.outputs.uuid }}
+    steps:
+      - name: "📥 Filter"
+        uses: dorny/paths-filter@v3
+        id: filter
+        with:
+          filters: |
+            uuid:
+              - 'packages/uuid/**'
+
+  validate_pr_title:
+    name: "Validate PR Title"
+    runs-on: ubuntu-latest
+    steps:
+      - name: "🛎 Checkout"
+        uses: actions/checkout@v4
+      - name: "🔧 Setup"
+        uses: ./.github/actions/use-pnpm-dependencies
+      - name: "📥 Get PR Title"
+        id: get_pr_title
+        uses: actions/github-script@v7
+        with:
+          result-encoding: string
+          script: |
+            const { data } = await github.rest.pulls.get({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              pull_number: context.payload.pull_request.number
+            });
+            return data.title;
+      - name: "✅ Validate"
+        run: echo "${{ steps.get_pr_title.outputs.result }}" | pnpm exec commitlint
+
+  ##
+  # package specific
+  ##
+
+  uuid:
+    name: "@agoralabs-sh/uuid"
+    needs: [changed_files, validate_pr_title]
+    if: ${{ needs.changed_files.outputs.uuid == 'true' }}
+    uses: ./.github/workflows/lint_build_test.yml
+    with:
+      package_name: "@agoralabs-sh/uuid"

.github/workflows/release.yml

@@ -0,0 +1,27 @@
+name: "Release"
+
+on:
+  push:
+    branches:
+      - beta
+      - main
+
+concurrency:
+  group: release-${{ github.ref_name }}
+  cancel-in-progress: true # ensure only one release workflow runs per branch (e.g., "release-beta" or "release-main")
+
+permissions:
+  contents: write # to be able to publish a github release
+  issues: write # to be able to comment on released issues
+  packages: write  # to be able to publish packages
+  pull-requests: write # to be able to comment on released pull requests
+
+jobs:
+  uuid:
+    name: "@agoralabs-sh/uuid"
+    uses: ./.github/workflows/publish_release.yml
+    with:
+      package_dir: "uuid"
+      package_name: "@agoralabs-sh/uuid"
+    secrets:
+      NPM_TOKEN: ${{ secrets.PUBLISH_PUBLIC_PACKAGES_TOKEN }}

.husky/.gitignore

@@ -0,0 +1 @@
+_

.husky/commit-msg

@@ -0,0 +1 @@
+pnpm exec commitlint --edit "$1"

.husky/pre-commit

@@ -0,0 +1 @@
+pnpm exec lint-staged --concurrent=false

.lintstagedrc.mjs

@@ -0,0 +1 @@
+// empty config to suppress errors

.prettierignore

@@ -0,0 +1 @@
+node_modules/

README.md

@@ -0,0 +1,97 @@
+<h1 align="center">
+  AVM Tools
+</h1>
+
+<p align="center">
+  A monorepo that contains types, utilities and general tools that help developers navigate the AVM ecosystem.
+</p>
+
+---
+
+### Table Of Contents
+
+* [1. Overview](#-1-overview)
+  - [1.1. Monorepo Project Structure](#11-monorepo-project-structure)
+* [2. Getting Started](#-2-getting-started)
+  - [2.1. Requirements](#21-requirements)
+  - [2.2. Installation](#22-installation)
+* [3. Appendix](#-3-appendix)
+  - [3.1. Packages](#31-packages)
+* [4. How To Contribute](#-4-how-to-contribute)
+
+## 🗂️ 1. Overview
+
+### 1.1. Monorepo Project Structure
+
+The repo follows the following structure:
+
+```text
+.
+├─ packages
+│   ├── <package>
+│   │   ├── .lintstagedrc.mjs
+│   │   ├── LICENSE
+│   │   ├── package.json       <-- contains package dependencies and is used to run package-level scripts
+│   │   ├── README.md
+│   │   ├── release.config.mjs <-- semantic release configuration
+│   │   └── ...
+│   └── ...                    <-- other packages
+├── package.json               <-- root package.json that contains top-level dependencies and tools
+└── ...
+```
+
+#### Root `package.json`
+
+The root `package.json` utilizes `pnpm`'s workspace feature. The root `package.json` should only reference packages that are used at the root level or are utilities/tools.
+
+#### `packages/` Directory
+
+The `packages/` directory contains, as the name suggests, the packages of the monorepo.
+
+#### `packages/<package>` Directory
+
+Each package **SHOULD** reflect the name of the package, i.e. the `packages/sigillum/` and **SHOULD** contain the following files and directories:
+
+* `.lintstagedrc.mjs` - Scripts to run on the pre-commit hook. This file is **REQUIRED**, however, if there are no scripts to run, use an empty file.
+* `LICENSE` - The license for the package.
+* `package.json` - The package's dependencies and is used to run package-level scripts.
+* `README.md` - Contains installation and usage instructions relevant to the package.
+* `release.config.mjs` - The local `semantic-release` configuration.
+
+## 🪄 2. Getting Started
+
+### 2.1. Requirements
+
+* Install [Node v22+](https://nodejs.org/en/)
+* Install [pnpm v10.3.0+](https://pnpm.io/installation)
+
+<sup>[Back to top ^][table-of-contents]</sup>
+
+### 2.2. Installation
+
+1. Install the dependencies using:
+
+```shell
+pnpm install
+```
+
+<sup>[Back to top ^][table-of-contents]</sup>
+
+## 📑 3. Appendix
+
+### 3.1. Packages
+
+| Name                                 | Visibility | Description                                                             | Package                                                                                                                   |
+|--------------------------------------|------------|-------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------|
+| [`uuid`](./packages/types/README.md) | `public`   | A UUID v4 utility package that allows generation and encoding/decoding. | [![NPM Version](https://img.shields.io/npm/v/%40agoralabs-sh%2Fuuid)](https://www.npmjs.com/package/%40agoralabs-sh/uuid) |
+
+<sup>[Back to top ^][table-of-contents]</sup>
+
+## 👏 4. How To Contribute
+
+Please read the [**Contributing Guide**](./CONTRIBUTING.md) to learn about the development process.
+
+<sup>[Back to top ^][table-of-contents]</sup>
+
+<!-- links -->
+[table-of-contents]: #table-of-contents

commitlint.config.ts

@@ -0,0 +1,7 @@
+import type { UserConfig } from '@commitlint/types';
+
+const config: UserConfig = {
+  extends: ['@commitlint/config-conventional'],
+};
+
+export default config;

package.json

@@ -0,0 +1,32 @@
+{
+  "name": "avm-tools",
+  "private": true,
+  "description": "A monorepo that contains types, utilities and general tools that help developers navigate the AVM ecosystem. ",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/agoralabs-sh/avm-tools"
+  },
+  "engines": {
+    "node": ">=22.x"
+  },
+  "packageManager": "pnpm@10.3.0",
+  "scripts": {
+    "prepare": "husky"
+  },
+  "devDependencies": {
+    "@anolilab/semantic-release-pnpm": "1.1.8",
+    "@commitlint/cli": "^19.6.0",
+    "@commitlint/config-conventional": "^19.6.0",
+    "@commitlint/types": "^19.5.0",
+    "@semantic-release/changelog": "^6.0.3",
+    "@semantic-release/commit-analyzer": "^13.0.0",
+    "@semantic-release/git": "^10.0.1",
+    "@semantic-release/github": "^11.0.1",
+    "@semantic-release/release-notes-generator": "^14.0.1",
+    "husky": "^9.1.7",
+    "lint-staged": "^15.2.10",
+    "prettier": "catalog:",
+    "semantic-release": "^24.2.0",
+    "semantic-release-monorepo": "^8.0.2"
+  }
+}