add magefiles

Author: miparnisari

README.md

@@ -8,15 +8,27 @@
 
 This project contains the definitions of [Protocol Buffers] used by Authzed.
 
-[Buf] is used to distribute these definitions and generate source code from them.
+We use [Buf] to distribute these definitions and generate source code from them. The definitions are published in [Buf Registry Authzed API repository].
 
-You can find more info on [HTTP API usage] in the [Authzed Docs].
+You can find more info on [HTTP API usage] and the [versioning and deprecation policy] in the [Authzed Docs].
 
-See [CONTRIBUTING.md] for instructions on how to contribute and perform common tasks like building the project and running tests.
+You can also use our [Postman collection] to explore the API.
+
+See [CONTRIBUTING.md] for instructions on how to contribute.
 
 [Protocol Buffers]: https://developers.google.com/protocol-buffers/
 [Buf]: https://github.com/bufbuild/buf
 [HTTP API usage]: https://authzed.com/docs/spicedb/getting-started/client-libraries#http-clients
 [Authzed Docs]: https://authzed.com/docs
+[versioning and deprecation policy]: https://authzed.com/blog/buf
+[Postman collection]: (https://www.postman.com/authzed/spicedb/collection/m26cqyc)
 [Buf Registry Authzed API repository]: https://buf.build/authzed/api/docs/main
-[CONTRIBUTING.md]: https://github.com/authzed/api/blob/main/CONTRIBUTING.md
+[CONTRIBUTING.md]: https://github.com/authzed/api/blob/main/CONTRIBUTING.md
+
+## Development
+
+You can run `mage` to see the available commands for development. We assume you have a Mac computer.
+
+## Warnings ⚠️
+
+- The `version` field found in various buf YAML configuration is actually schema of the YAML of the file and is not related to the version of the definitions.

magefiles/dev.go

@@ -0,0 +1,49 @@
+package main
+
+import (
+	"fmt"
+	"os/exec"
+
+	"github.com/magefile/mage/mg"
+)
+
+type Dev mg.Namespace
+
+// InstallDependencies installs development tools required for the project.
+func (Dev) InstallDependencies() error {
+	commands := [][]string{
+		{"brew", "install", "pre-commit"},
+		{"brew", "install", "bufbuild/buf/buf"},
+		{"pre-commit", "install"},
+	}
+
+	for _, cmd := range commands {
+		fmt.Printf("Running: %s\n", cmd)
+		c := exec.Command(cmd[0], cmd[1:]...)
+		if err := c.Run(); err != nil {
+			return fmt.Errorf("failed to run %v: %w", cmd, err)
+		}
+	}
+
+	return nil
+}
+
+// BufGenerate builds the image and then produces results according to `buf.gen.yaml`.
+func (Dev) BufGenerate() error {
+	fmt.Println("Running buf generate...")
+	c := exec.Command("buf", "generate")
+	if err := c.Run(); err != nil {
+		return fmt.Errorf("failed to run buf generate: %w", err)
+	}
+	return nil
+}
+
+// BufBuild compiles protobuf files into an internal image format, verifying that the definitions are syntactically and semantically correct (e.g., resolving types, imports, etc.).
+func (Dev) BufBuild() error {
+	fmt.Println("Running buf build...")
+	c := exec.Command("buf", "build")
+	if err := c.Run(); err != nil {
+		return fmt.Errorf("failed to run buf build: %w", err)
+	}
+	return nil
+}

magefiles/go.mod

@@ -0,0 +1,5 @@
+module github.com/authzed/api/magefiles
+
+go 1.24.0
+
+require github.com/magefile/mage v1.15.0

magefiles/go.sum

@@ -0,0 +1,2 @@
+github.com/magefile/mage v1.15.0 h1:BvGheCMAsG3bWUDbZ8AyXXpCNwU9u5CB6sM+HNb9HYg=
+github.com/magefile/mage v1.15.0/go.mod h1:z5UZb/iS3GoOSn0JgWuiw7dxlurVYTu+/jHXqQg881A=