{"id":46638249,"url":"https://github.com/tetherto/miningos-wrk-inventory","last_synced_at":"2026-03-08T02:13:20.548Z","repository":{"id":340874842,"uuid":"1129677024","full_name":"tetherto/miningos-wrk-inventory","owner":"tetherto","description":null,"archived":false,"fork":false,"pushed_at":"2026-02-26T22:58:46.000Z","size":85,"stargazers_count":0,"open_issues_count":0,"forks_count":3,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-02-27T04:59:58.634Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tetherto.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-01-07T12:29:58.000Z","updated_at":"2026-02-26T22:58:51.000Z","dependencies_parsed_at":null,"dependency_job_id":"3cc7cf53-1828-4c2d-b774-8e6e3fee647d","html_url":"https://github.com/tetherto/miningos-wrk-inventory","commit_stats":null,"previous_names":["tetherto/miningos-wrk-inventory"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/tetherto/miningos-wrk-inventory","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tetherto%2Fminingos-wrk-inventory","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tetherto%2Fminingos-wrk-inventory/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tetherto%2Fminingos-wrk-inventory/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tetherto%2Fminingos-wrk-inventory/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tetherto","download_url":"https://codeload.github.com/tetherto/miningos-wrk-inventory/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tetherto%2Fminingos-wrk-inventory/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30242406,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-08T00:58:18.660Z","status":"online","status_checked_at":"2026-03-08T02:00:06.215Z","response_time":56,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-03-08T02:13:18.345Z","updated_at":"2026-03-08T02:13:20.530Z","avatar_url":"https://github.com/tetherto.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# miningos-wrk-inventory\n\nHyperswarm RPC worker for managing mining equipment spare parts and container component inventory - handles registration, tracking, and querying of PSUs, hashboards, controllers, and cooling systems.\n\n## Table of Contents\n\n1. [Overview](#overview)\n2. [Prerequisites](#prerequisites)\n3. [Installation](#installation)\n4. [Configuration](#configuration)\n5. [Starting the Worker](#starting-the-worker)\n6. [Architecture](#architecture)\n7. [RPC Methods](#rpc-methods)\n8. [Development](#development)\n9. [Troubleshooting](#troubleshooting)\n10. [Contributing](#contributing)\n\n## Overview\n\nThe Inventory Worker extends the base `miningos-tpl-wrk-thing` template to provide inventory management for mining farm spare parts:\n- Registers devices and spare parts with unique identification\n- Tracks parent device relationships and part lineage\n- Enforces validation rules for data consistency\n- Generates unique part codes automatically\n- Maintains device information history\n- Supports multiple part types through specialized worker classes\n\nEach facility deploys inventory workers for different part categories to maintain organized spare part tracking across the mining operation.\n\n## Prerequisites\n\n- Node.js \u003e= 20.0\n- `hp-rpc-cli` tool for testing RPC methods (install via Hyperswarm tools)\n\n## Installation\n\n1. Clone the repository:\n```bash\ngit clone https://github.com/tetherto/miningos-wrk-inventory.git\ncd miningos-wrk-inventory\n```\n\n2. Install dependencies:\n```bash\nnpm install\n```\n\n3. Setup configuration files:\n```bash\nbash setup-config.sh\n```\n\n## Configuration\n\n### Common Configuration (config/common.json)\n\nConfigure worker logging and debug settings:\n\n```json\n{\n  \"dir_log\": \"logs\",\n  \"debug\": 0\n}\n```\n\n## Starting the Worker\n\nThe inventory worker supports multiple specialized types for different part categories.\n\n### Miner Parts\n\n#### PSU (Power Supply Unit) Worker\n```bash\nDEBUG=\"*\" node worker.js --wtype wrk-inventory-rack-miner_part-psu --env development --rack rack-1\n```\n\n#### Hashboard Worker\n```bash\nDEBUG=\"*\" node worker.js --wtype wrk-inventory-rack-miner_part-hashboard --env development --rack rack-1\n```\n\n#### Controller Worker\n```bash\nDEBUG=\"*\" node worker.js --wtype wrk-inventory-rack-miner_part-controller --env development --rack rack-1\n```\n\n### Container Parts\n\n#### Dry Cooler Worker\n```bash\nDEBUG=\"*\" node worker.js --wtype wrk-inventory-rack-container_part-drycooler --env development --rack rack-1\n```\n\n### Custom Configuration\n```bash\n# Change environment\nnode worker.js --wtype wrk-inventory-rack-miner_part-psu --env production --rack rack-0\n\n# Enable debug output\nDEBUG=\"*\" node worker.js --wtype wrk-inventory-rack-miner_part-psu --env development --rack rack-1\n```\n\n## Architecture\n\n### Core Components\n\n#### Worker Hierarchy\n```\nWrkRack (from miningos-tpl-wrk-thing)\n  └── WrkInventoryRack (workers/lib/worker-base.js)\n      ├── WrkMinerPartRack (workers/lib/miner_part-worker-base.js)\n      │   ├── WrkPsuMinerPartRack (workers/psu.miner_part.rack.inventory.wrk.js)\n      │   ├── WrkHashboardMinerPartRack (workers/hashboard.miner_part.rack.inventory.wrk.js)\n      │   └── WrkControllerMinerPartRack (workers/controller.miner_part.rack.inventory.wrk.js)\n      └── WrkContainerPartRack (workers/lib/container_part-worker-base.js)\n          └── WrkDrycoolerContainerPartRack (workers/drycooler.container_part.rack.inventory.wrk.js)\n```\n\n### Part Code Generation\n\nEach registered part receives a unique code in the format:\n```\n{PREFIX}-{MINER_MODEL}-{SUBTYPE}-{NUMBER}\n```\n\nExamples:\n- `PSU-WM-CB6_V5-01` (PSU for Whatsminer M56, CB6_V5 model)\n- `HB-AM-S19XP-03` (Hashboard for Antminer S19 XP)\n- `CTRL-AV-A1246-02` (Controller for Avalon A1246)\n\n### Validation Rules\n\nThe worker enforces strict validation:\n\n1. **Unique Identifiers**: `serialNum` and `macAddress` must be unique across all parts\n2. **Parent Device Consistency**: `parentDeviceId` and `parentDeviceCode` must both be present or both absent\n3. **Model-Type Matching**: `parentDeviceModel` must be contained within `parentDeviceType`\n   - Example: Model `\"wm\"` must be in type `\"miner-wm-m56\"`\n4. **Required Fields by Type**:\n   - PSUs: `serialNum` required\n   - Hashboards: `serialNum` recommended\n   - Controllers: `serialNum` recommended\n\n## RPC Methods\n\nAll RPC methods are exposed via Hyperswarm. Use `hp-rpc-cli` for testing.\n\n### registerThing\n\nRegister a new spare part in inventory.\n\n**Parameters:**\n- `info` (object): Device information\n  - `serialNum` (string): Serial number (required for PSUs)\n  - `macAddress` (string, optional): MAC address if applicable\n  - `parentDeviceModel` (string): Parent device model (`am`, `wm`, `av`)\n  - `parentDeviceType` (string): Full parent device type (e.g., `miner-wm-m56`)\n  - `parentDeviceId` (string, optional): UUID of parent device\n  - `parentDeviceCode` (string, optional): Short code of parent device\n  - `parentDeviceSN` (string, optional): Parent device serial number\n  - `subType` (string): Part sub-type/model (e.g., `CB6_V5`)\n  - `site` (string): Installation site name\n  - `location` (string): Specific location within site\n  - `status` (string, optional): Operational status\n- `opts` (object, optional): Additional options\n\n**Example:**\n```bash\nhp-rpc-cli -s inventory -m registerThing -d '{\n  \"info\": {\n    \"serialNum\": \"SN_123456\",\n    \"macAddress\": \"aa:bb:cc:dd:ee:ff\",\n    \"parentDeviceModel\": \"wm\",\n    \"parentDeviceType\": \"miner-wm-m56\",\n    \"parentDeviceId\": \"550e8400-e29b-41d4-a716-446655440000\",\n    \"parentDeviceCode\": \"WM-M56-001\",\n    \"parentDeviceSN\": \"WM_SN_789\",\n    \"subType\": \"CB6_V5\",\n    \"site\": \"Test\",\n    \"location\": \"Lab - Rack A1\",\n    \"status\": \"active\"\n  },\n  \"opts\": {}\n}'\n```\n\n**Response:**\n```json\n{\n  \"id\": \"e33abf5e-1a81-4ec4-9b2a-ac80c953b2c9\",\n  \"code\": \"PSU-WM-CB6_V5-01\",\n  \"info\": { ... },\n  \"createdAt\": \"2024-12-01T10:30:00.000Z\"\n}\n```\n\n### updateThing\n\nUpdate existing device information.\n\n**Parameters:**\n- `id` (string): Device UUID\n- `info` (object): Fields to update (same structure as registerThing)\n\n**Example:**\n```bash\nhp-rpc-cli -s inventory -m updateThing -d '{\n  \"id\": \"e33abf5e-1a81-4ec4-9b2a-ac80c953b2c9\",\n  \"info\": {\n    \"status\": \"in_repair\",\n    \"location\": \"Repair Shop - Bench 3\"\n  }\n}'\n```\n\n### forgetThings\n\nRemove devices from inventory.\n\n**Parameters:**\n- `ids` (array): Array of device UUIDs to remove\n\n**Example:**\n```bash\nhp-rpc-cli -s inventory -m forgetThings -d '{\n  \"ids\": [\"e33abf5e-1a81-4ec4-9b2a-ac80c953b2c9\"]\n}'\n```\n\n### listThings\n\nRetrieve all registered devices in this worker's inventory.\n\n**Parameters:**\n- (none)\n\n**Example:**\n```bash\nhp-rpc-cli -s inventory -m listThings -d '{}'\n```\n\n**Response:**\n```json\n[\n  {\n    \"id\": \"e33abf5e-1a81-4ec4-9b2a-ac80c953b2c9\",\n    \"code\": \"PSU-WM-CB6_V5-01\",\n    \"info\": {\n      \"serialNum\": \"SN_123456\",\n      \"parentDeviceModel\": \"wm\",\n      \"subType\": \"CB6_V5\",\n      \"site\": \"Test\",\n      \"status\": \"active\"\n    }\n  }\n]\n```\n\n## Development\n\n### Running Tests\n```bash\nnpm test              # Run linting (test = lint for this worker)\nnpm run lint          # Check code style (Standard.js)\nnpm run lint:fix      # Auto-fix linting issues\n```\n\n### Project Structure\n```\n.\n├── config/                    # Configuration files\n│   ├── common.json            # Worker configuration\n│   ├── base.thing.json        # Thing template\n│   └── facs/                  # Facility configs\n│       └── net.config.json    # Network settings\n├── workers/\n│   ├── psu.miner_part.rack.inventory.wrk.js\n│   ├── hashboard.miner_part.rack.inventory.wrk.js\n│   ├── controller.miner_part.rack.inventory.wrk.js\n│   ├── drycooler.container_part.rack.inventory.wrk.js\n│   └── lib/\n│       ├── worker-base.js             # Base inventory worker\n│       ├── miner_part-worker-base.js  # Miner part base\n│       ├── container_part-worker-base.js\n│       ├── constants.js               # Part type definitions\n│       ├── utils.js                   # Helpers\n│       └── stats.js                   # Metrics\n├── status/                    # Runtime status data\n├── store/                     # Persistent storage\n└── worker.js                  # Entry point\n```\n\n### Adding New Part Types\n\nTo add a new part type:\n\n1. Add constant to `workers/lib/constants.js`:\n```javascript\nMINER_PART_TYPES: {\n  NEW_PART: {\n    name: 'new_part',\n    prefix: 'NP'\n  }\n}\n```\n\n2. Create worker file `workers/new_part.miner_part.rack.inventory.wrk.js`:\n```javascript\nconst { MINER_PART_TYPES } = require('./lib/constants.js')\nconst WrkMinerPartRack = require('./lib/miner_part-worker-base.js')\n\nclass WrkNewPartMinerPartRack extends WrkMinerPartRack {\n  getThingType () {\n    return super.getThingType() + `-${MINER_PART_TYPES.NEW_PART.name}`\n  }\n\n  _validateRegisterThing (data) {\n    super._validateRegisterThing(data)\n    // Add custom validation\n  }\n}\n\nmodule.exports = WrkNewPartMinerPartRack\n```\n\n3. Start worker:\n```bash\nnode worker.js --wtype wrk-inventory-rack-miner_part-new_part --env development --rack rack-1\n```\n\n## Troubleshooting\n\n### Common Issues\n\n1. **Worker fails to start**\n   - Verify configuration files exist: `bash setup-config.sh`\n   - Check `config/common.json` has valid JSON syntax\n   - Ensure `config/facs/net.config.json` has proper network settings\n\n2. **Cannot register thing - ERR_THING_SERIALNUM_EXISTS**\n   - Serial number already exists in this worker's inventory\n   - Use `listThings` to find the duplicate\n   - Either update the existing thing or use a different serial number\n\n3. **Cannot register thing - ERR_THING_MACADDRESS_EXISTS**\n   - MAC address already exists in this worker's inventory\n   - MAC addresses are case-insensitive\n   - Check for duplicates with `listThings`\n\n4. **Cannot register thing - ERR_PARENT_DEVICE_INFO_INVALID**\n   - `parentDeviceId` and `parentDeviceCode` must both be present or both absent\n   - If setting one, you must set the other\n\n5. **Cannot register thing - ERR_PARENT_DEVICE_MODEL_TYPE_MISMATCH**\n   - The `parentDeviceModel` must be contained in `parentDeviceType`\n   - Example: Model `\"wm\"` should be in type `\"miner-wm-m56\"`\n   - Check your model and type values match\n\n6. **RPC connection issues**\n   - Verify Hyperswarm network configuration in `config/facs/net.config.json`\n   - Check DHT bootstrap nodes are accessible\n   - Ensure no firewall blocking UDP traffic\n   - Verify worker is running with `DEBUG=\"*\"` to see connection logs\n\n7. **hp-rpc-cli command not found**\n   - Install Hyperswarm RPC CLI tools\n   - Ensure the tool is in your PATH\n   - Try using the full path to the binary\n\n## Contributing\n\nContributions are welcome and appreciated!\n\n### How to Contribute\n\n1. **Fork** the repository\n2. **Create a new branch** for your feature or fix:\n   ```bash\n   git checkout -b feature/your-feature-name\n   ```\n3. **Make your changes** and ensure tests pass:\n   ```bash\n   npm test\n   ```\n4. **Push** to your fork:\n   ```bash\n   git push origin feature/your-feature-name\n   ```\n5. **Open a Pull Request** describing what you changed and why\n\n### Guidelines\n\n- Follow Standard.js code style (`npm run lint`)\n- Add validation for new fields or part types\n- Keep PRs focused—one feature or fix per pull request\n- Update documentation (README, CLAUDE.md) as needed\n- Ensure all tests pass before submitting\n- Test RPC methods with `hp-rpc-cli` before submitting\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftetherto%2Fminingos-wrk-inventory","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftetherto%2Fminingos-wrk-inventory","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftetherto%2Fminingos-wrk-inventory/lists"}