docs: add README, per-resource examples, unit tests, CI, and pre-commit

- Add README.md with provider docs, resource/data-source reference, and
  development instructions
- Reorganize examples into per-resource-type subdirectories following
  Terraform provider conventions, add missing pypi/npm/puppet examples
- Add unit tests for helpers, HTTP client, model conversions, and
  provider registration
- Add Woodpecker CI pipelines for lint, test, and build
- Add pre-commit config with standard and Go-specific hooks

examples/data-sources/artifactapi_remote/main.tf

@@ -0,0 +1,27 @@
+terraform {
+  required_providers {
+    artifactapi = {
+      source  = "git.unkin.net/unkin/artifactapi"
+      version = "0.0.1"
+    }
+  }
+}
+
+provider "artifactapi" {
+  endpoint = "https://artifactapi.example.com"
+}
+
+# Read the configuration of an existing remote by name.
+# All fields (base_url, package_type, TTLs, patterns, etc.) are available
+# as computed attributes.
+data "artifactapi_remote" "dockerhub" {
+  name = "dockerhub"
+}
+
+output "dockerhub_base_url" {
+  value = data.artifactapi_remote.dockerhub.base_url
+}
+
+output "dockerhub_package_type" {
+  value = data.artifactapi_remote.dockerhub.package_type
+}

examples/data-sources/artifactapi_virtual/main.tf

@@ -0,0 +1,26 @@
+terraform {
+  required_providers {
+    artifactapi = {
+      source  = "git.unkin.net/unkin/artifactapi"
+      version = "0.0.1"
+    }
+  }
+}
+
+provider "artifactapi" {
+  endpoint = "https://artifactapi.example.com"
+}
+
+# Read the configuration of an existing virtual repository by name.
+# Returns the package type, description, and ordered member list.
+data "artifactapi_virtual" "helm" {
+  name = "helm"
+}
+
+output "helm_members" {
+  value = data.artifactapi_virtual.helm.members
+}
+
+output "helm_package_type" {
+  value = data.artifactapi_virtual.helm.package_type
+}

examples/main.tf

@@ -11,10 +11,13 @@ provider "artifactapi" {
   endpoint = "https://artifactapi.k8s.syd1.au.unkin.net"
 }
 
-# Generic — patterns act as allowlist, everything matching is immutable by default
+# ---------------------------------------------------------------------------
+# Generic remotes
+# ---------------------------------------------------------------------------
+
 resource "artifactapi_remote_generic" "github" {
-  name     = "github"
-  base_url = "https://github.com"
+  name        = "github"
+  base_url    = "https://github.com"
   description = "GitHub releases"
 
   immutable_ttl = 0
@@ -26,15 +29,14 @@ resource "artifactapi_remote_generic" "github" {
     "neovim/neovim-releases/.*/nvim-linux-x86_64.tar.gz$",
   ]
 
-  # Override: branch archives are mutable
   mutable_patterns = [
     ".*/archive/refs/heads/.*\\.tar\\.gz$",
   ]
 }
 
 resource "artifactapi_remote_generic" "hashicorp_releases" {
-  name     = "hashicorp-releases"
-  base_url = "https://releases.hashicorp.com"
+  name        = "hashicorp-releases"
+  base_url    = "https://releases.hashicorp.com"
   description = "HashiCorp product releases"
 
   immutable_ttl = 0
@@ -46,11 +48,13 @@ resource "artifactapi_remote_generic" "hashicorp_releases" {
   ]
 }
 
-# Docker — patterns restrict which images are proxied
-# Provider auto-classifies: tag manifests mutable, blobs immutable
+# ---------------------------------------------------------------------------
+# Docker
+# ---------------------------------------------------------------------------
+
 resource "artifactapi_remote_docker" "dockerhub" {
-  name     = "dockerhub"
-  base_url = "https://registry-1.docker.io"
+  name        = "dockerhub"
+  base_url    = "https://registry-1.docker.io"
   description = "Docker Hub registry"
 
   immutable_ttl    = 0
@@ -66,10 +70,13 @@ resource "artifactapi_remote_docker" "dockerhub" {
   ]
 }
 
-# Helm — no patterns needed, provider knows index.yaml is mutable
+# ---------------------------------------------------------------------------
+# Helm
+# ---------------------------------------------------------------------------
+
 resource "artifactapi_remote_helm" "jetstack" {
-  name     = "jetstack"
-  base_url = "https://charts.jetstack.io"
+  name        = "jetstack"
+  base_url    = "https://charts.jetstack.io"
   description = "Jetstack Helm charts (cert-manager)"
 
   immutable_ttl = 0
@@ -77,25 +84,62 @@ resource "artifactapi_remote_helm" "jetstack" {
 }
 
 resource "artifactapi_remote_helm" "hashicorp_helm" {
-  name     = "hashicorp-helm"
-  base_url = "https://helm.releases.hashicorp.com"
+  name        = "hashicorp-helm"
+  base_url    = "https://helm.releases.hashicorp.com"
   description = "HashiCorp Helm charts"
 
   immutable_ttl = 0
   mutable_ttl   = 3600
 }
 
-# RPM — no patterns needed, provider knows repodata/* is mutable
+# ---------------------------------------------------------------------------
+# Language package managers
+# ---------------------------------------------------------------------------
+
+resource "artifactapi_remote_pypi" "pypi" {
+  name        = "pypi"
+  base_url    = "https://pypi.org"
+  description = "Python Package Index"
+
+  immutable_ttl = 0
+  mutable_ttl   = 900
+}
+
+resource "artifactapi_remote_npm" "npmjs" {
+  name        = "npmjs"
+  base_url    = "https://registry.npmjs.org"
+  description = "npm public registry"
+
+  immutable_ttl = 0
+  mutable_ttl   = 900
+}
+
+# ---------------------------------------------------------------------------
+# OS package managers
+# ---------------------------------------------------------------------------
+
 resource "artifactapi_remote_rpm" "almalinux" {
-  name     = "almalinux"
-  base_url = "https://gsl-syd.mm.fcix.net/almalinux"
+  name        = "almalinux"
+  base_url    = "https://gsl-syd.mm.fcix.net/almalinux"
   description = "AlmaLinux RPM package repository"
 
   immutable_ttl = 0
   mutable_ttl   = 7200
 }
 
-# Terraform registry — needs releases_remote for URL rewriting
+resource "artifactapi_remote_alpine" "alpine" {
+  name        = "alpine"
+  base_url    = "https://dl-cdn.alpinelinux.org"
+  description = "Alpine Linux APK package repository"
+
+  immutable_ttl = 0
+  mutable_ttl   = 7200
+}
+
+# ---------------------------------------------------------------------------
+# Infrastructure tooling
+# ---------------------------------------------------------------------------
+
 resource "artifactapi_remote_terraform" "terraform_registry" {
   name            = "terraform-registry"
   base_url        = "https://registry.terraform.io"
@@ -106,31 +150,32 @@ resource "artifactapi_remote_terraform" "terraform_registry" {
   mutable_ttl   = 300
 }
 
-# Go module proxy — provider knows @v/list is mutable, .zip/.mod/.info immutable
 resource "artifactapi_remote_goproxy" "goproxy" {
-  name     = "goproxy"
-  base_url = "https://proxy.golang.org"
+  name        = "goproxy"
+  base_url    = "https://proxy.golang.org"
   description = "Go module proxy"
 
   immutable_ttl = 0
   mutable_ttl   = 300
 }
 
-# Alpine — provider knows APKINDEX.tar.gz is mutable
-resource "artifactapi_remote_alpine" "alpine" {
-  name     = "alpine"
-  base_url = "https://dl-cdn.alpinelinux.org"
-  description = "Alpine Linux APK package repository"
+resource "artifactapi_remote_puppet" "puppet_forge" {
+  name        = "puppet-forge"
+  base_url    = "https://forgeapi.puppet.com"
+  description = "Puppet Forge module repository"
 
   immutable_ttl = 0
-  mutable_ttl   = 7200
+  mutable_ttl   = 3600
 }
 
-# Virtual — merges multiple helm repos into one index
+# ---------------------------------------------------------------------------
+# Virtual repositories
+# ---------------------------------------------------------------------------
+
 resource "artifactapi_virtual" "helm" {
   name         = "helm"
   package_type = "helm"
-  description  = "All helm repos merged"
+  description  = "All Helm repos merged"
 
   members = [
     artifactapi_remote_helm.jetstack.name,
@@ -138,11 +183,22 @@ resource "artifactapi_virtual" "helm" {
   ]
 }
 
-# Data source — read a remote's config
+# ---------------------------------------------------------------------------
+# Data sources
+# ---------------------------------------------------------------------------
+
 data "artifactapi_remote" "dockerhub" {
   name = artifactapi_remote_docker.dockerhub.name
 }
 
+data "artifactapi_virtual" "helm" {
+  name = artifactapi_virtual.helm.name
+}
+
 output "dockerhub_base_url" {
   value = data.artifactapi_remote.dockerhub.base_url
 }
+
+output "helm_members" {
+  value = data.artifactapi_virtual.helm.members
+}

examples/resources/artifactapi_remote_alpine/main.tf

@@ -0,0 +1,23 @@
+terraform {
+  required_providers {
+    artifactapi = {
+      source  = "git.unkin.net/unkin/artifactapi"
+      version = "0.0.1"
+    }
+  }
+}
+
+provider "artifactapi" {
+  endpoint = "https://artifactapi.example.com"
+}
+
+# Alpine remote proxies an Alpine Linux APK repository.
+# The provider knows APKINDEX.tar.gz is mutable; .apk packages are immutable.
+resource "artifactapi_remote_alpine" "alpine" {
+  name        = "alpine"
+  base_url    = "https://dl-cdn.alpinelinux.org"
+  description = "Alpine Linux APK package repository"
+
+  immutable_ttl = 0
+  mutable_ttl   = 7200
+}

examples/resources/artifactapi_remote_docker/main.tf

@@ -0,0 +1,32 @@
+terraform {
+  required_providers {
+    artifactapi = {
+      source  = "git.unkin.net/unkin/artifactapi"
+      version = "0.0.1"
+    }
+  }
+}
+
+provider "artifactapi" {
+  endpoint = "https://artifactapi.example.com"
+}
+
+# Docker remote proxies a container registry.
+# The provider auto-classifies: tag manifests are mutable, blobs are immutable.
+resource "artifactapi_remote_docker" "dockerhub" {
+  name        = "dockerhub"
+  base_url    = "https://registry-1.docker.io"
+  description = "Docker Hub registry"
+
+  immutable_ttl    = 0
+  mutable_ttl      = 300
+  ban_tags_enabled = true
+  ban_tags         = ["latest"]
+
+  patterns = [
+    "^library/almalinux",
+    "^library/postgres",
+    "^library/redis",
+    "^bitnami/",
+  ]
+}

examples/resources/artifactapi_remote_generic/main.tf

@@ -0,0 +1,34 @@
+terraform {
+  required_providers {
+    artifactapi = {
+      source  = "git.unkin.net/unkin/artifactapi"
+      version = "0.0.1"
+    }
+  }
+}
+
+provider "artifactapi" {
+  endpoint = "https://artifactapi.example.com"
+}
+
+# A generic remote proxies arbitrary HTTP endpoints.
+# Patterns act as an allowlist; everything matching is immutable by default.
+resource "artifactapi_remote_generic" "github" {
+  name        = "github"
+  base_url    = "https://github.com"
+  description = "GitHub releases"
+
+  immutable_ttl = 0
+  mutable_ttl   = 7200
+
+  patterns = [
+    "ducaale/xh/.*/xh-.*-x86_64-unknown-linux-musl.tar.gz$",
+    "mikefarah/yq/.*/yq_linux_amd64$",
+    "neovim/neovim-releases/.*/nvim-linux-x86_64.tar.gz$",
+  ]
+
+  # Override: branch archives are mutable
+  mutable_patterns = [
+    ".*/archive/refs/heads/.*\\.tar\\.gz$",
+  ]
+}

examples/resources/artifactapi_remote_goproxy/main.tf

@@ -0,0 +1,23 @@
+terraform {
+  required_providers {
+    artifactapi = {
+      source  = "git.unkin.net/unkin/artifactapi"
+      version = "0.0.1"
+    }
+  }
+}
+
+provider "artifactapi" {
+  endpoint = "https://artifactapi.example.com"
+}
+
+# Go module proxy remote proxies a Go module proxy.
+# The provider knows @v/list is mutable; .zip, .mod, and .info files are immutable.
+resource "artifactapi_remote_goproxy" "goproxy" {
+  name        = "goproxy"
+  base_url    = "https://proxy.golang.org"
+  description = "Go module proxy"
+
+  immutable_ttl = 0
+  mutable_ttl   = 300
+}

examples/resources/artifactapi_remote_helm/main.tf

@@ -0,0 +1,23 @@
+terraform {
+  required_providers {
+    artifactapi = {
+      source  = "git.unkin.net/unkin/artifactapi"
+      version = "0.0.1"
+    }
+  }
+}
+
+provider "artifactapi" {
+  endpoint = "https://artifactapi.example.com"
+}
+
+# Helm remote proxies a Helm chart repository.
+# The provider knows index.yaml is mutable; chart tarballs are immutable.
+resource "artifactapi_remote_helm" "jetstack" {
+  name        = "jetstack"
+  base_url    = "https://charts.jetstack.io"
+  description = "Jetstack Helm charts (cert-manager)"
+
+  immutable_ttl = 0
+  mutable_ttl   = 3600
+}

examples/resources/artifactapi_remote_npm/main.tf

@@ -0,0 +1,23 @@
+terraform {
+  required_providers {
+    artifactapi = {
+      source  = "git.unkin.net/unkin/artifactapi"
+      version = "0.0.1"
+    }
+  }
+}
+
+provider "artifactapi" {
+  endpoint = "https://artifactapi.example.com"
+}
+
+# NPM remote proxies an npm registry.
+# The provider knows package metadata is mutable; tarballs are immutable.
+resource "artifactapi_remote_npm" "npmjs" {
+  name        = "npmjs"
+  base_url    = "https://registry.npmjs.org"
+  description = "npm public registry"
+
+  immutable_ttl = 0
+  mutable_ttl   = 900
+}

examples/resources/artifactapi_remote_puppet/main.tf

@@ -0,0 +1,23 @@
+terraform {
+  required_providers {
+    artifactapi = {
+      source  = "git.unkin.net/unkin/artifactapi"
+      version = "0.0.1"
+    }
+  }
+}
+
+provider "artifactapi" {
+  endpoint = "https://artifactapi.example.com"
+}
+
+# Puppet remote proxies a Puppet Forge repository.
+# The provider knows module metadata is mutable; release tarballs are immutable.
+resource "artifactapi_remote_puppet" "puppet_forge" {
+  name        = "puppet-forge"
+  base_url    = "https://forgeapi.puppet.com"
+  description = "Puppet Forge module repository"
+
+  immutable_ttl = 0
+  mutable_ttl   = 3600
+}

examples/resources/artifactapi_remote_pypi/main.tf

@@ -0,0 +1,23 @@
+terraform {
+  required_providers {
+    artifactapi = {
+      source  = "git.unkin.net/unkin/artifactapi"
+      version = "0.0.1"
+    }
+  }
+}
+
+provider "artifactapi" {
+  endpoint = "https://artifactapi.example.com"
+}
+
+# PyPI remote proxies a Python package index.
+# The provider knows /simple/ index pages are mutable; sdists and wheels are immutable.
+resource "artifactapi_remote_pypi" "pypi" {
+  name        = "pypi"
+  base_url    = "https://pypi.org"
+  description = "Python Package Index"
+
+  immutable_ttl = 0
+  mutable_ttl   = 900
+}

examples/resources/artifactapi_remote_rpm/main.tf

@@ -0,0 +1,23 @@
+terraform {
+  required_providers {
+    artifactapi = {
+      source  = "git.unkin.net/unkin/artifactapi"
+      version = "0.0.1"
+    }
+  }
+}
+
+provider "artifactapi" {
+  endpoint = "https://artifactapi.example.com"
+}
+
+# RPM remote proxies an RPM package repository.
+# The provider knows repodata/* is mutable; RPM packages are immutable.
+resource "artifactapi_remote_rpm" "almalinux" {
+  name        = "almalinux"
+  base_url    = "https://gsl-syd.mm.fcix.net/almalinux"
+  description = "AlmaLinux RPM package repository"
+
+  immutable_ttl = 0
+  mutable_ttl   = 7200
+}

examples/resources/artifactapi_remote_terraform/main.tf

@@ -0,0 +1,41 @@
+terraform {
+  required_providers {
+    artifactapi = {
+      source  = "git.unkin.net/unkin/artifactapi"
+      version = "0.0.1"
+    }
+  }
+}
+
+provider "artifactapi" {
+  endpoint = "https://artifactapi.example.com"
+}
+
+# A generic remote is needed for the releases CDN that the Terraform registry
+# redirects provider downloads to.
+resource "artifactapi_remote_generic" "hashicorp_releases" {
+  name        = "hashicorp-releases"
+  base_url    = "https://releases.hashicorp.com"
+  description = "HashiCorp product releases"
+
+  immutable_ttl = 0
+  mutable_ttl   = 7200
+
+  patterns = [
+    "terraform/.*terraform_.*_linux_amd64\\.zip$",
+    "vault/.*vault_.*_linux_amd64\\.zip$",
+  ]
+}
+
+# Terraform registry remote proxies the Terraform provider registry.
+# The releases_remote attribute points to a generic remote that serves
+# the actual provider/module archives after URL rewriting.
+resource "artifactapi_remote_terraform" "terraform_registry" {
+  name            = "terraform-registry"
+  base_url        = "https://registry.terraform.io"
+  description     = "Terraform provider registry"
+  releases_remote = artifactapi_remote_generic.hashicorp_releases.name
+
+  immutable_ttl = 0
+  mutable_ttl   = 300
+}

examples/resources/artifactapi_virtual/main.tf

@@ -0,0 +1,45 @@
+terraform {
+  required_providers {
+    artifactapi = {
+      source  = "git.unkin.net/unkin/artifactapi"
+      version = "0.0.1"
+    }
+  }
+}
+
+provider "artifactapi" {
+  endpoint = "https://artifactapi.example.com"
+}
+
+# Helm remotes to be merged into a virtual repository
+resource "artifactapi_remote_helm" "jetstack" {
+  name        = "jetstack"
+  base_url    = "https://charts.jetstack.io"
+  description = "Jetstack Helm charts (cert-manager)"
+
+  immutable_ttl = 0
+  mutable_ttl   = 3600
+}
+
+resource "artifactapi_remote_helm" "hashicorp_helm" {
+  name        = "hashicorp-helm"
+  base_url    = "https://helm.releases.hashicorp.com"
+  description = "HashiCorp Helm charts"
+
+  immutable_ttl = 0
+  mutable_ttl   = 3600
+}
+
+# Virtual repository merges multiple remotes of the same package type
+# into a single endpoint. Earlier members have higher priority for
+# duplicate entries.
+resource "artifactapi_virtual" "helm" {
+  name         = "helm"
+  package_type = "helm"
+  description  = "All Helm repos merged"
+
+  members = [
+    artifactapi_remote_helm.jetstack.name,
+    artifactapi_remote_helm.hashicorp_helm.name,
+  ]
+}