Add namespace and collection inventories

listing.go

@@ -29,6 +29,27 @@ type NamespaceFilter struct {
 	Name string
 }
 
+// ResourceKind selects one identity type for [Engine.ListNamespaces].
+type ResourceKind string
+
+const (
+	// ResourcePrompt selects namespaces containing prompt IDs.
+	ResourcePrompt ResourceKind = "prompt"
+	// ResourceProfile selects namespaces containing profile IDs.
+	ResourceProfile ResourceKind = "profile"
+	// ResourceBackend selects namespaces containing backend IDs.
+	ResourceBackend ResourceKind = "backend"
+)
+
+// CollectionInfo describes one effective collections declaration.
+type CollectionInfo struct {
+	// Namespace is the exact collection key.
+	Namespace string
+	// ReleaseVersion is nil when absent or null and points to the exact value
+	// when present, including an explicitly empty string.
+	ReleaseVersion *string
+}
+
 // PromptIdentity identifies one prompt ID and its optional descriptive version
 // label in the effective configuration captured when an Engine is constructed.
 // A nil Version means no label was declared; a non-nil empty string is an
@@ -141,3 +162,60 @@ func internalListingFilters(filters []NamespaceFilter) []internalengine.ListingF
 	}
 	return internal
 }
+
+// ListNamespaces returns the sorted, distinct namespaces that contain the
+// selected resource kinds. With no kinds, it returns the union across prompts,
+// profiles, and backends. Repeated kinds have no effect; an unknown kind
+// returns an error matching ErrInvalidRequest. The inventory is global and is
+// not restricted by this engine view's scopes. Unqualified resource IDs do
+// not contribute a namespace.
+//
+// The returned slice is caller-owned. A nil or zero-value engine returns an
+// error matching ErrInvalidConfig. Cancellation or deadline expiration
+// returns the context error and no partial result.
+func (e *Engine) ListNamespaces(ctx context.Context, kinds ...ResourceKind) ([]string, error) {
+	if e == nil || e.internal == nil {
+		return nil, fmt.Errorf("%w: engine is nil", ErrInvalidConfig)
+	}
+	internalKinds := make([]string, len(kinds))
+	for index, kind := range kinds {
+		internalKinds[index] = string(kind)
+	}
+	namespaces, err := e.internal.ListNamespaces(ctx, internalKinds)
+	if err != nil {
+		return nil, mapPublicError(err)
+	}
+	return namespaces, nil
+}
+
+// ListCollections returns the sorted collection declarations from the
+// effective configuration captured when the engine was constructed. It
+// includes metadata-only and resource-only declarations and is independent of
+// namespace view scopes. It does not infer collections from resource IDs or
+// configuration source history.
+//
+// The returned slice and each ReleaseVersion pointer are caller-owned. Nil
+// means the label was absent or null; a non-nil empty string is preserved. A
+// nil or zero-value engine returns an error matching ErrInvalidConfig.
+// Cancellation or deadline expiration returns the context error and no partial
+// result.
+func (e *Engine) ListCollections(ctx context.Context) ([]CollectionInfo, error) {
+	if e == nil || e.internal == nil {
+		return nil, fmt.Errorf("%w: engine is nil", ErrInvalidConfig)
+	}
+	collections, err := e.internal.ListCollections(ctx)
+	if err != nil {
+		return nil, mapPublicError(err)
+	}
+	public := make([]CollectionInfo, len(collections))
+	for index, collection := range collections {
+		public[index] = CollectionInfo{
+			Namespace:      collection.Namespace,
+			ReleaseVersion: copyStringPtr(collection.ReleaseVersion),
+		}
+	}
+	if err := ctx.Err(); err != nil {
+		return nil, mapPublicError(err)
+	}
+	return public, nil
+}