feat(admin): add systemplane catalog surface

[fredcamaral]

Summary

• add public catalog APIs and read-only admin catalog routes
• reserve the -/catalog keyspace and support escaped slash-containing keys
• harden catalog/default cloning and document non-secret catalog usage

Verification

• DOCKER_CONFIG="$HOME/.docker-opencode" make ci

[coderabbitai]

Caution

Review failed

Failed to post review comments

Walkthrough

Adds a read-only catalog registry with public types and Client accessors, safe cloning/validation, reserved-key protections, admin HTTP catalog endpoints (MountCatalog), unit tests, and README updates for catalog metadata and multi-tenant mounting.

Changes

Catalog Registry System

Layer / File(s)	Summary
Catalog types and public API surface api_types.go, api_constants.go, api_constructors.go, api_client.go	New public types and constants (Catalog, CatalogKeySummary, CatalogKeyDetail, CatalogKeyMetadata, CatalogExample, CatalogVersion), RedactPolicy.String(), Client accessors Catalog(), CatalogKey(), CatalogService(), and option helpers WithCatalogService, WithCatalogMetadata.
Internal options, client fields, cloning and validation internal/client/options.go, internal/client/client.go, internal/client/value_clone.go, internal/client/redact.go	Client gains catalogService config; option helpers assign catalog metadata; cloning extended for arrays/structs with deep-copy helpers; clone-safety and catalog-safety validation (cycle detection and unexported mutable-field rejection); RedactPolicy.String() implemented.
Core catalog implementation and reserved key protection internal/client/register.go, internal/client/catalog.go, internal/client/client_test.go	Implements Client.Catalog, Client.CatalogKey, Client.CatalogService, catalog contract types, registry iteration/sorting/deduplication, kind inference, metadata cloning, and registration-time reserved-key rejection for admin catalog namespace/prefix.
Admin HTTP routing and catalog handlers admin/admin.go, admin/admin_responses.go	Adds MountCatalog() (read-only catalog list/detail), catalog handlers and URL/path builders; refactors Mount() for normalized prefixes, wildcard-capable routes, shared middleware and registered-path resolution; adds catalogDetailResponse and catalogWriteResponse.
Admin responses & endpoint tests admin/admin_test.go, api_catalog_test.go	Adds admin response DTOs and enhances fakeStore with call counters; mounts catalog routes in tests and adds TestAdmin_Catalog* suite covering list/detail, authorization, store isolation, multi-tenant access, path escaping, 404s, deny-by-default, custom prefixes, redaction semantics, and read-action authorization; adds a public catalog facade test.
Internal catalog unit tests internal/client/catalog_test.go	Unit tests (spy store) verify registered metadata before Start, ensure catalog reads post-Start don't touch store, confirm cloning of mutable defaults, reject unsafe unexported mutable struct fields and cyclic defaults, validate kind inference and tenant-scoping behavior.
Catalog documentation and examples README.md	Postgres quickstart now uses WithCatalogService and registers global/log.level with WithCatalogMetadata (kind, runtime class, schema, rules, examples); Admin HTTP routes docs expanded with multi-tenant ordering and a Catalog routes subsection describing admin.MountCatalog and reserved paths.
Manager event, seed and warm-load internal/manager/events.go, internal/manager/seed.go, internal/manager/schema_test.go	Adds Manager.notify/event decoding, applyEvent, synchronous dispatchCallbacks with panic recovery, seedDefaults to populate defaults with ON CONFLICT DO NOTHING, and warmLoad to populate tenant cache with decoded defaults; includes tests for marshal failures and resolve-failure cache safety.
Postgres config & notify dispatch internal/postgres/postgres_config.go, internal/postgres/postgres_notify.go, internal/postgres/postgres_unit_test.go	New Postgres New(cfg) with config normalization/validation, dispatchEvent, parseNotifyPayload, and truncateString moved to postgres_notify.go; adds unit tests for config, multi-tenant pre-I/O paths, closed/nil paths, and notify payload parsing/dispatch.
MongoDB reorg, events & tests internal/mongodb/mongodb_config.go, internal/mongodb/mongodb_events.go, internal/mongodb/mongodb_namespace.go, internal/mongodb/mongodb_unit_test.go	Split MongoDB constructor/config to mongodb_config.go with toEntry and New; added mongodb_events.go implementing FNV dedup, boundaryDedupHit, eventFromChange, dispatchEvent; added isNamespaceExists helper; includes unit tests for conversion, config validation, multi-tenant paths, event translation and dispatch.
Misc coverage & formatting .ignorecoverunit, Makefile, examples/manager/main.go, assorted tests	Adjust coverage ignore patterns and Makefile regex escaping; minor lint/comment formatting and added manager lifecycle wrapper test plus several public/testing facade tests.

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[lerian-studio]

🔍 PR Validation Summary

✅ PR Mergeable — no blocking failures

Check	Status	Blocking
Source Branch	✅ success	yes
PR Title	✅ success	yes
PR Description	✅ success	yes
PR Size	✅ success	no
Auto Labels	✅ success	no
PR Metadata	✅ success	no

---

_{🔍 View workflow run}

[lerian-studio]

🔒 Security Scan Results — lib-systemplane

✅ PR Mergeable — no blocking findings

Stage	Status	Blocking?
Filesystem Scan	✅ Clean	—
Docker Image Scan	➖ Skipped	—
Docker Hub Health Score	➖ Skipped	—
Pre-release Version Check	✅ Clean	—

Trivy

Filesystem Scan

✅ No vulnerabilities or secrets found.

---

Pre-release Version Check

✅ No unstable version pins found.

---

_{🔍 View full scan logs}

[lerian-studio]

📊 Unit Test Coverage Report: app

Metric	Value
Overall Coverage	80.5% ✅ PASS
Threshold	80%

Coverage by Package

Package	Coverage
github.com/LerianStudio/lib-systemplane/admin	88.4%
github.com/LerianStudio/lib-systemplane/internal/client	80.7%
github.com/LerianStudio/lib-systemplane/internal/debounce	73.1%
github.com/LerianStudio/lib-systemplane/internal/manager	87.4%
github.com/LerianStudio/lib-systemplane/internal/mongodb	97.5%
github.com/LerianStudio/lib-systemplane/internal/postgres	100.0%
github.com/LerianStudio/lib-systemplane	94.6%

---

Generated by Go PR Analysis workflow

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@admin/admin.go`:
- Around line 4-15: Update the exported doc comment for Mount and MountCatalog
to reflect the actual mounted patterns: include the wildcard "/*" variants (e.g.
GET/PUT/DELETE /<prefix>/:namespace/* to allow keys containing slashes via
escaped slashes), note that both exact ":key" and wildcard "/*" routes are
mounted to support escaped-slash keys, and add the catalog detail route (GET
/<prefix>/-/catalog/:namespace/:key and its wildcard form) so the comments match
the implemented Mount and MountCatalog behavior.

In `@internal/client/value_clone.go`:
- Around line 165-225: The validation only deduplicates pointers so
self-referential slices/maps can recurse forever; update
validateCloneSafeIndexed and validateCloneSafeMap to treat slice/map identity
like pointers: if v.IsNil() return nil, compute a visit mark using visit{typ:
v.Type(), ptr: v.Pointer()} (same visit type used in validateCloneSafePointer),
check seen[mark] and return if present, then add seen[mark] = struct{}{} before
iterating and validating elements/values via validateCloneSafeValue (preserve
existing path formatting). Ensure you only call v.Pointer() when the value is
not nil to avoid panics.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: a87bbf42-031f-4c3a-b0b9-1b8b727c653f

📥 Commits

Reviewing files that changed from the base of the PR and between bc50f8d and 1df8626.

📒 Files selected for processing (17)

• README.md
• admin/admin.go
• admin/admin_responses.go
• admin/admin_test.go
• api_catalog_test.go
• api_client.go
• api_constants.go
• api_constructors.go
• api_types.go
• internal/client/catalog.go
• internal/client/catalog_test.go
• internal/client/client.go
• internal/client/client_test.go
• internal/client/options.go
• internal/client/redact.go
• internal/client/register.go
• internal/client/value_clone.go

[fredcamaral]

Fixes Applied Successfully

Fixed 3 file(s) based on 2 CodeRabbit feedback item(s).

Files modified:

• admin/admin.go
• internal/client/value_clone.go
• internal/client/catalog_test.go

Commit: 2771991

Validation passed locally with DOCKER_CONFIG="$HOME/.docker-opencode" make ci.

The latest autofix changes are on the feat/systemplane-catalog-hardening branch.

[fredcamaral]

@CodeRabbit approve

[coderabbitai]

✅ Actions performed

Comments resolved and changes approved.