Watchnoc Protocols

Universal Protocol Truth for Go, Node.js, and Python.

Central repository for Protocol Buffer definitions used across the Watchnoc ecosystem (Go, Node.js, Python).

🚀 Automation

This repository is fully automated via GitHub Actions (.github/workflows/proto-pipeline.yml):

• Auto-Generate: Any push touching logs/**/*.proto triggers regeneration for all three languages. Pushes that don't touch a .proto file (docs, CI tweaks, etc.) skip generation/validation/tagging entirely.
• Auto-Lint: buf lint enforces schema style on every push and PR.
• Auto-Validate: After generation, each language's output is smoke-tested (import it, round-trip a message, construct a gRPC stub/client) before anything is committed or tagged - see Validation, below. A generation that produces code nobody can actually import (this has happened - see gen/python's history) now fails the pipeline instead of shipping.
• Breaking-change detection: buf breaking compares the changed .proto files against the previous commit (or the PR's base branch). The result drives auto-tagging:
• Auto-Tag: On merge to main, a new tag is created automatically - major if buf breaking found a breaking change, minor otherwise. (Pushes with no .proto changes don't tag at all, instead of always bumping patch regardless of what changed.)

🛠️ Local Development

Prerequisites

• Buf
• Node.js (v18+)
• Go (v1.25+)
• Python (v3.9+)

Commands

# Install tool dependencies
npm install

# Regenerate all code (buf generate -> fix Python packaging -> compile Node TS)
npm run generate

# Lint proto files
npm run lint

# Format proto files
npm run format

# Validate each language's generated output actually works
bash scripts/validate-go.sh
node scripts/validate-node.mjs
python3 scripts/validate_python.py

Pre-commit hooks (recommended)

Catches lint/format/breaking-change/generation problems before they leave your machine, instead of only in CI:

pip install pre-commit
pre-commit install

This runs buf format, buf lint, buf breaking (against origin/main), and a full regenerate+validate pass on every commit that touches a .proto file. See .pre-commit-config.yaml.

📦 Consumption

Note: this repository is currently private. The registry commands below are the intended, long-term public consumption path once published; until then, use the git-based alternative shown under each language.

Go

go get github.com/watchnoc/proto

Private-repo alternative (requires a token with read access, e.g. via git config --global url."https://x-access-token:${GITHUB_TOKEN}@github.com/".insteadOf "https://github.com/"):

GOPRIVATE=github.com/watchnoc/* go get github.com/watchnoc/proto@latest

Node.js (NPM)

npm install @watchnoc/proto

Private-repo alternative (what the Go/Node/server-agent consumers in this org actually use today):

npm install git+https://github.com/watchnoc/proto.git

Python

pip install watchnoc-proto

Private-repo alternative:

pip install "git+https://github.com/watchnoc/proto.git"

(Append #subdirectory= only if you vendor a subset; the whole repo installs correctly as-is now that gen/python has proper __init__.py files - see Validation.)

✅ Validation

Three scripts (scripts/validate-go.sh, scripts/validate-node.mjs, scripts/validate_python.py) each do the same job for their language: import/build the freshly generated code and exercise it - encode/decode a message, construct a gRPC client/stub. They're run by CI after every generation and available locally for the same reason. If one of these ever fails, the generated output is broken and nothing downstream should consume it yet.

📂 Structure

• logs/v1/: Log ingestion definitions.
• gen/: Generated code (Go, Node, Python) - committed to the repo by CI, not hand-edited.
• scripts/: Post-generation fixups (fix_python_package.py) and per-language validation.
• buf.yaml / buf.gen.yaml: Buf configuration, linting rules, and code-generation plugins.
• .pre-commit-config.yaml: Local git-hook validation (optional but recommended).