extension-data-viewer - SKILL.md Agent Skill

name: extension-data-viewer description: Admin-only paginated viewer for stable canister state. Use whenever the user asks for a viewer, dashboard, debug panel, or admin browse over backend data — users, items, orders, logs, or any stable Map/Set/Array/VarArray/List/Stack/Queue. Pre-installed in every Caffeine app via the caffeineai-data-viewer mops package; this skill explains what it does and how to keep using it correctly. version: 0.1.0 compatibility: mops: caffeineai-data-viewer: "~0.1.0"

caffeineai-subscription: [none]

Data Viewer

Admin-only data inspection extension for Caffeine AI.

Overview

Every Caffeine app ships with the caffeineai-data-viewer mops package and the moc --generate-view-queries flag enabled. Together with include MixinViews() in the actor, the compiler auto-exposes a controller-only __<var> query for every stable variable of a supported type:

Map.Map<K, V> — (?K, ?Nat) -> [(K, V)]
Set.Set<K> — (?K, ?Nat) -> [K]
[V], [var V], List.List<V>, Stack.Stack<V>, Queue.Queue<V> — (?Nat, ?Nat) -> [V]

A null cursor starts at the beginning; a null count returns everything from the cursor. Each generated query traps on any non-controller caller — they exist for admin dashboards and debug viewers, not user-facing endpoints.

Backend

The package and include are already wired into the template. You don't need to add or edit anything for the viewer to work — declare a stable variable of a supported type and the __<var> query appears automatically.

import Map "mo:core/Map";
import Principal "mo:core/Principal";
import MixinViews "mo:caffeineai-data-viewer/MixinViews";

actor {
  include MixinViews();

  let users = Map.empty<Principal, Text>();

  // Generated automatically: __users : (ko : ?Principal, count : ?Nat) -> [(Principal, Text)] query
};

Lintoko rule include-mixin-views (shipped with the package) errors if the actor body is missing include MixinViews();. Keep the include — removing it disables every auto-generated viewer.

Rules

NEVER use the generated __<var> queries as a substitute for user-facing endpoints — they trap for any non-controller caller. Public list/feed/search methods still need to be written normally with public query func listX(...).
NEVER declare an actor member whose name starts with __ — it either collides with an auto-generated query or hits a reserved prefix.
Pure (immutable) collections (pure/Map, pure/Set, pure/List, pure/Queue) are not supported. The viewer is mutable-only by design; pure collection field access is a deprecated pattern in Caffeine projects anyway.