feat: centralize Barkfile schema

README.md

@@ -0,0 +1,83 @@
+# Barkfile Parser
+
+`barkfile-parser` is the Go source of truth for the Barkfile schema. It parses and validates the current PawSQL `pawsql` document and watches a Barkfile for validated revisions so control-plane consumers can reconfigure without owning another parser.
+
+## Install
+
+```sh
+go get git.campbellwireless.net/barkstack/barkfile-parser@v0.1.0
+```
+
+The module requires Go 1.24 or later.
+
+## Parse and validate
+
+```go
+cfg, err := barkfile.Load("/etc/pawsql/Barkfile")
+if err != nil {
+    return err
+}
+```
+
+`Load` reads, parses, and validates a file. `Parse` parses bytes when a caller owns file I/O; call `Config.Validate` before applying a parsed configuration.
+
+The current schema defines one `pawsql` block with a listener, TLS certificate/key paths, and one or more `database` routes. A route has exactly one of:
+
+- `upstream <host:port>` for an external PostgreSQL server.
+- `postgres { ... }` for a managed PostgreSQL container. Its `image`, `volume`, and `password_env` directives are required. `idle_timeout` and `traffic_idle_timeout` accept Go duration strings.
+
+```text
+pawsql {
+    listen :5432
+
+    tls {
+        cert /etc/pawsql/tls/fullchain.pem
+        key /etc/pawsql/tls/privkey.pem
+    }
+
+    database application {
+        hostname app.db.example.com
+        postgres {
+            image postgres:18
+            volume application-data
+            password_env APPLICATION_POSTGRES_PASSWORD
+            idle_timeout 10m
+            traffic_idle_timeout 1h
+        }
+    }
+}
+```
+
+## Watch validated changes
+
+```go
+ctx, cancel := context.WithCancel(context.Background())
+defer cancel()
+
+changes, err := barkfile.Watch(ctx, "/etc/pawsql/Barkfile", barkfile.WatchOptions{})
+if err != nil {
+    return err
+}
+for change := range changes {
+    if change.Err != nil {
+        log.Printf("Barkfile update rejected: %v", change.Err)
+        continue
+    }
+    apply(change.Config)
+}
+```
+
+`Watch` emits the initial valid configuration, then each content change. It polls every 250ms by default; set `WatchOptions.PollInterval` to override it. Invalid or temporarily unreadable revisions are emitted as `Change.Err` and do not stop the watcher. A later valid revision is emitted normally.
+
+## Releases
+
+Gitea Actions runs tests on each `main` push. The release job reads Conventional Commit messages since the last `v*` tag and pushes a new semantic-version tag when needed:
+
+| Commit | Version change |
+| --- | --- |
+| `feat:` | minor |
+| `fix:` or `perf:` | patch |
+| `type!:` or `BREAKING CHANGE:` | major |
+| other types | no release |
+
+Go consumers update through standard module versions, for example `go get git.campbellwireless.net/barkstack/barkfile-parser@latest`.