Extract Files seam, WebDAV, and Visit from CheckDNS.

Publish go-nc-files v1 with local/WebDAV Root, DefaultPathStore, and neutral Working Folder language; depends on go-nc-exapp v0.1.0. Co-authored-by: Cursor <cursoragent@cursor.com>
2026-08-26 19:16:53 +02:00
commit 9068d8ba8e
14 changed files with 1308 additions and 0 deletions
@@ -0,0 +1,57 @@
+# go-nc-files
+
+Shared Go library for Nextcloud ExApp Services: a User Files seam (local disk and WebDAV), Saved Default path storage, and Visit-scoped Working Folder resolution.
+
+Import: `gitea.neitzel.de/konrad/go-nc-files`
+
+Depends on [go-nc-exapp](https://gitea.neitzel.de/konrad/go-nc-exapp) for AppAPI credentials on WebDAV.
+
+## v1 scope
+
+**Included**
+
+- **Files seam** — `Root` and `Folder` interfaces with `OpenFolder`, `EnsureFolder`, `List`, `Read`, `Write`, `Exists`
+- **Local** — filesystem-backed User Files Root for tests and local `go run`
+- **WebDAVRoot** — Nextcloud Files at `/remote.php/dav/files/{user}/` using `gonexapp.Credentials`
+- **CleanRel** — rejects `..`, URLs, and numeric file IDs
+- **RequireBasename** — shared basename rules for child file names
+- **DefaultPathStore** — `GetDefault` / `SetDefault` for Saved Default paths; `FileStore` (JSON) and `Memory` implementations
+- **Visit** — `Open` resolves Working Folder from Saved Default (app-icon) or visit-only path (Files view); fail-closed on missing/forbidden visit paths
+- Sentinel errors: `ErrNotExist`, `ErrForbidden`, `ErrNotDir`
+
+**Excluded from v1**
+
+- ExApp lifecycle HTTP routes and HaRP bootstrap (see **go-nc-exapp**)
+- AppAPI preference OCS wiring (ExApp adapts `gonexapp.AppAPIPreferences` to `DefaultPathStore`)
+- Catalog, DNS, or product-specific file semantics
+- Recursive tree walks and Nextcloud numeric file IDs
+
+## Usage
+
+```go
+import (
+    goncfiles "gitea.neitzel.de/konrad/go-nc-files"
+    gonexapp "gitea.neitzel.de/konrad/go-nc-exapp"
+)
+
+// Local mode
+visit, err := goncfiles.OpenLocal("/data/files", "/data/settings.json", "myapp", "")
+
+// WebDAV + ExApp preferences (adapter in your ExApp)
+cred := gonexapp.Credentials{ /* ... */ }
+root := goncfiles.WebDAVRoot{Cred: cred}
+prefs := gonexapp.NewAppAPIPreferences(cred, "myexapp", "savedDefault")
+store := myAppAPIPathStore{prefs} // implement DefaultPathStore
+visit, err := goncfiles.Open(root, store, "myapp", visitRelative)
+```
+
+Each ExApp chooses its Saved Default preference key and initial folder name; this library stays key-agnostic.
+
+## Domain language
+
+See [CONTEXT.md](./CONTEXT.md) for User Files Root, Working Folder, Saved Default, Visit, and Files seam terminology.
+
+## Related
+
+- **go-nc-exapp** — AppAPI credentials and OCS preferences
+- Workspace ADR 0013 — extraction from CheckDNS