move more into API

10 files changed, 65 insertions, 44 deletions

diff --git a/api/api.go b/api/api.go
new file mode 100644
index 0000000..d82c2c8
--- /dev/null
+++ b/api/api.go
@@ -0,0 +1,39 @@
+package api
+
+import (
+	"codeberg.org/snonux/gonf/api/option"
+	"codeberg.org/snonux/gonf/internal/resource"
+	"codeberg.org/snonux/gonf/internal/resource/dir"
+	"codeberg.org/snonux/gonf/internal/resource/file"
+	"codeberg.org/snonux/gonf/internal/resource/link"
+)
+
+// File creates a file resource.
+func File(path string, opts ...option.Option) resource.Resource {
+	return file.Have(path, opts...)
+}
+
+// NoFile creates a file resource that is ensured to be absent.
+func NoFile(path string, opts ...option.Option) resource.Resource {
+	return file.Absent(path, opts...)
+}
+
+// Dir creates a directory resource.
+func Dir(path string, opts ...option.Option) resource.Resource {
+	return dir.Have(path, opts...)
+}
+
+// NoDir creates a directory resource that is ensured to be absent.
+func NoDir(path string, opts ...option.Option) resource.Resource {
+	return dir.Absent(path, opts...)
+}
+
+// Link creates a link resource (symbolic or hard).
+func Link(path string, opts ...option.Option) resource.Resource {
+	return link.Have(path, opts...)
+}
+
+// NoLink creates a link resource that is ensured to be absent.
+func NoLink(path string, opts ...option.Option) resource.Resource {
+	return link.Absent(path, opts...)
+}
diff --git a/internal/resource/opt/opt.go b/api/option/option.go
index 23f076d..b5d2531 100644
--- a/internal/resource/opt/opt.go
+++ b/api/option/option.go
@@ -1,22 +1,6 @@
-// Package opt provides interface-based, resource-agnostic configuration
+// Package option provides interface-based, resource-agnostic configuration
 // options shared by the file, dir, and link resource packages.
-//
-// It is designed to be dot-imported at call sites so options read as bare
-// WithMode(...) / WithOwner(...) calls regardless of the resource type:
-//
-//	import (
-//		"codeberg.org/snonux/gonf/internal/resource/file"
-//		. "codeberg.org/snonux/gonf/internal/resource/opt"
-//	)
-//
-//	file.Have("file.txt", WithOwner("paul"), WithMode(0o755))
-//
-// Each option targets a small capability interface (Owner, Moded, ...). A
-// resource implements only the setters it supports. Applying an option to a
-// resource that lacks the matching interface (e.g. WithPrune on a file) is a
-// programming error in the resource declaration and aborts the program via
-// log.Fatalf.
-package opt
+package option
 
 import (
 	"log"
diff --git a/examples/examples.go b/examples/examples.go
index 346d74a..1a1df0b 100644
--- a/examples/examples.go
+++ b/examples/examples.go
@@ -3,44 +3,42 @@ package examples
 import (
 	"os"
 
+	. "codeberg.org/snonux/gonf/api"
+	. "codeberg.org/snonux/gonf/api/option"
 	"codeberg.org/snonux/gonf/internal/resource"
-	"codeberg.org/snonux/gonf/internal/resource/dir"
-	"codeberg.org/snonux/gonf/internal/resource/file"
-	"codeberg.org/snonux/gonf/internal/resource/link"
-	. "codeberg.org/snonux/gonf/internal/resource/opt"
 )
 
 func Run() error {
 	// 1. Regular file with content
-	file.Have("/tmp/gonf_hello.txt", WithContent("Hello World!"))
+	File("/tmp/gonf_hello.txt", WithContent("Hello World!"))
 
 	// 2. Regular file from a source template
-	file.Have("/tmp/gonf_example.conf", WithSource("assets/testfiles/test.tmpl"))
+	File("/tmp/gonf_example.conf", WithSource("assets/testfiles/test.tmpl"))
 
 	// 3. Regular file with specific mode and owner
-	file.Have(
+	File(
 		"/tmp/gonf_secret.txt",
 		WithContent("top secret"),
 		WithMode(0o600),
 	)
 
 	// 4. A directory
-	dir.Have("/tmp/gonf_dir", WithMode(0o755))
+	Dir("/tmp/gonf_dir", WithMode(0o755))
 
 	// 5. A symlink
-	link.Have("/tmp/gonf_link", WithSymlink("/tmp/gonf_hello.txt"))
+	Link("/tmp/gonf_link", WithSymlink("/tmp/gonf_hello.txt"))
 
 	// 6. A hardlink
-	link.Have("/tmp/gonf_hardlink", WithHardlink("/tmp/gonf_hello.txt"))
+	Link("/tmp/gonf_hardlink", WithHardlink("/tmp/gonf_hello.txt"))
 
 	// 7. Ensuring something is absent (two equivalent styles; each resource
 	// path may only be declared once per run, so they use distinct paths)
-	file.Have("/tmp/gonf_old.txt", IsAbsent())
-	file.Absent("/tmp/gonf_old_alt.txt") // Alternative way
+	File("/tmp/gonf_old.txt", IsAbsent())
+	NoFile("/tmp/gonf_old_alt.txt") // Alternative way
 
 	// 8. A directory tree copied from source, reconciled, with a distinct
 	// file mode from the directory's own mode
-	dir.Have(
+	Dir(
 		"/tmp/gonf_dir_from_source",
 		WithSource("assets/testfiles"),
 		WithPrune(),
@@ -52,23 +50,23 @@ func Run() error {
 	// (rather than reusing #8's path) to give WithPrune's recursive removal
 	// something real to demonstrate.
 	_ = os.MkdirAll("/tmp/gonf_stale_dir/nested", 0o755)
-	dir.Have("/tmp/gonf_stale_dir", IsAbsent(), WithPrune())
+	Dir("/tmp/gonf_stale_dir", IsAbsent(), WithPrune())
 	_ = os.MkdirAll("/tmp/gonf_stale_dir_alt/nested", 0o755)
-	dir.Absent("/tmp/gonf_stale_dir_alt", WithPrune()) // Alternative way
+	NoDir("/tmp/gonf_stale_dir_alt", WithPrune()) // Alternative way
 
 	// 10. Non-recursively removing an empty directory
 	_ = os.Mkdir("/tmp/gonf_stale_empty_dir", 0o755)
-	dir.Have("/tmp/gonf_stale_empty_dir", IsAbsent())
+	Dir("/tmp/gonf_stale_empty_dir", IsAbsent())
 
 	// 11. Ensuring a symlink is absent
 	_ = os.Symlink("/tmp/gonf_hello.txt", "/tmp/gonf_stale_link")
-	link.Have("/tmp/gonf_stale_link", IsAbsent())
+	Link("/tmp/gonf_stale_link", IsAbsent())
 	_ = os.Symlink("/tmp/gonf_hello.txt", "/tmp/gonf_stale_link_alt")
-	link.Absent("/tmp/gonf_stale_link_alt") // Alternative way
+	NoLink("/tmp/gonf_stale_link_alt") // Alternative way
 
 	// 12. Ensuring a hardlink is absent
 	_ = os.Link("/tmp/gonf_hello.txt", "/tmp/gonf_stale_hardlink")
-	link.Have("/tmp/gonf_stale_hardlink", IsAbsent())
+	Link("/tmp/gonf_stale_hardlink", IsAbsent())
 
 	return resource.Apply()
 }
diff --git a/internal/resource/dir/dir.go b/internal/resource/dir/dir.go
index ba50caf..34b161d 100644
--- a/internal/resource/dir/dir.go
+++ b/internal/resource/dir/dir.go
@@ -8,7 +8,7 @@ import (
 	"strconv"
 
 	"codeberg.org/snonux/gonf/internal/resource"
-	"codeberg.org/snonux/gonf/internal/resource/opt"
+	opt "codeberg.org/snonux/gonf/api/option"
 )
 
 type Dir struct {
diff --git a/internal/resource/dir/dir_test.go b/internal/resource/dir/dir_test.go
index 8b90fac..6a5bb83 100644
--- a/internal/resource/dir/dir_test.go
+++ b/internal/resource/dir/dir_test.go
@@ -8,7 +8,7 @@ import (
 	resource "codeberg.org/snonux/gonf/internal/resource"
 	"codeberg.org/snonux/gonf/internal/resource/file"
 
-	. "codeberg.org/snonux/gonf/internal/resource/opt"
+	. "codeberg.org/snonux/gonf/api/option"
 )
 
 func TestHaveDirectoryCreate(t *testing.T) {
diff --git a/internal/resource/dir/source.go b/internal/resource/dir/source.go
index 2e5ed98..b94756d 100644
--- a/internal/resource/dir/source.go
+++ b/internal/resource/dir/source.go
@@ -9,7 +9,7 @@ import (
 
 	"codeberg.org/snonux/gonf/internal/resource/file"
 	"codeberg.org/snonux/gonf/internal/resource/link"
-	"codeberg.org/snonux/gonf/internal/resource/opt"
+	opt "codeberg.org/snonux/gonf/api/option"
 )
 
 // copySourceTree mirrors d.source into d.path, dispatching each entry by
diff --git a/internal/resource/file/file.go b/internal/resource/file/file.go
index 50ba6e3..402b348 100644
--- a/internal/resource/file/file.go
+++ b/internal/resource/file/file.go
@@ -11,7 +11,7 @@ import (
 	"text/template"
 
 	"codeberg.org/snonux/gonf/internal/resource"
-	"codeberg.org/snonux/gonf/internal/resource/opt"
+	opt "codeberg.org/snonux/gonf/api/option"
 )
 
 type File struct {
diff --git a/internal/resource/file/file_test.go b/internal/resource/file/file_test.go
index 0669b88..e84ab13 100644
--- a/internal/resource/file/file_test.go
+++ b/internal/resource/file/file_test.go
@@ -7,7 +7,7 @@ import (
 	"testing"
 
 	"codeberg.org/snonux/gonf/internal/resource"
-	. "codeberg.org/snonux/gonf/internal/resource/opt"
+	. "codeberg.org/snonux/gonf/api/option"
 )
 
 func TestGetChecksum(t *testing.T) {
diff --git a/internal/resource/link/link.go b/internal/resource/link/link.go
index 0e5582c..5a1824b 100644
--- a/internal/resource/link/link.go
+++ b/internal/resource/link/link.go
@@ -6,7 +6,7 @@ import (
 	"os"
 
 	"codeberg.org/snonux/gonf/internal/resource"
-	"codeberg.org/snonux/gonf/internal/resource/opt"
+	opt "codeberg.org/snonux/gonf/api/option"
 )
 
 type kind int
diff --git a/internal/resource/link/link_test.go b/internal/resource/link/link_test.go
index 20542bd..c8d9789 100644
--- a/internal/resource/link/link_test.go
+++ b/internal/resource/link/link_test.go
@@ -6,7 +6,7 @@ import (
 	"testing"
 
 	"codeberg.org/snonux/gonf/internal/resource"
-	. "codeberg.org/snonux/gonf/internal/resource/opt"
+	. "codeberg.org/snonux/gonf/api/option"
 )
 
 func TestHaveSymlinkCreateAndIdempotent(t *testing.T) {