@pitcher/cli-scripts 3.1.0 → 3.2.0

package/README.md

@@ -44,7 +44,7 @@ Pitcher's MCP tools come from two places:
 
 | Server | Tools | Add it with |
 |---|---|---|
-| **Hosted** (OAuth; Claude Code, Claude Desktop, claude.ai, ChatGPT) | everything: content, canvases, DSRs, analytics, L&D, users, … (121 tools, prompts, resources) | `claude mcp add --transport http pitcher https://mcp.pitcher.com/mcp` — Claude Desktop: Settings → Connectors → Add custom connector, same URL |
+| **Hosted** (OAuth; Claude Code, Claude Desktop, claude.ai, ChatGPT) | everything: content, canvases, DSRs, analytics, L&D, users, … (131 tools, prompts, resources) | `claude mcp add --transport http pitcher https://mcp.pitcher.com/mcp` — Claude Desktop: Settings → Connectors → Add custom connector, same URL |
 | **Local** `p mcp` (stdio) | only `pitcher_dev_sync`, `pitcher_dev_sync_revert`, `pitcher_publish_app` (they zip a folder on YOUR machine) | `claude mcp add pitcher-local -- p mcp` |
 
 Claude Code users add both. The local server runs on your `p login` session (no API key, no env block); the domain is fixed when it starts. Signed in to several orgs? Add one entry per org:
@@ -392,9 +392,46 @@ p analytics viewers --instance-id 01... --canvas-id 01CANVASID... --viewer-type
 
 # Per-viewer session event timeline for a DSR canvas (member key)
 p analytics sessions --instance-id 01... --canvas-id 01CANVASID... --user rep@example.com --api-key myapikey
+
+# Who opened one file, and time per page of it (instance editor or admin)
+p analytics file-users --instance-id 01... --file-id 01FILEID... --start-date 2026-10-01 --end-date 2026-10-31
+p analytics file-pages --instance-id 01... --file-id 01FILEID... --user-emails rep@example.com
+
+# Reps' canvas usage; with --canvas-id also seconds per page (section) (instance editor or admin)
+p analytics canvas-users --instance-id 01... --canvas-id 01CANVASID...
+
+# Per DSR viewer: each visit and the pages viewed with their time; --format csv for an export (member key)
+p analytics viewer-visits --instance-id 01... --canvas-id 01CANVASID... --limit 25 --format csv
+```
+
+`file-users`, `file-pages` and `canvas-users` need an instance editor, instance admin or org admin. `canvas-users`
+counts internal users only and presentation time only; it reads `GET /analytics/canvases/users` (PIT-9589).
+`viewer-visits` reads the 10 most recently active viewers by default (`--limit`, max 25; one timeline query each),
+or one with `--user`. `kpi` returns every value and growth figure as a number.
+
+MCP: all fourteen verbs are exposed as read-only `pitcher_analytics_*` tools, alongside a `pitcher://analytics/catalog` resource (which verb answers which question — returns, time model, key tier) and four query prompts — `top_content`, `content_engagement_summary`, `who_viewed_canvas`, `adoption_snapshot`.
+
+## To run the `roleplay` command:
+
+Read AI Roleplay results (PIT-9200; read-only). `kpis`, `sessions` and `rep-summary` read the roleplay analytics
+replica in clickhouse-api and need an **instance or org admin**; dates are optional and there is **no default
+window** (omitted = all time). `team` (assignment completion per rep, as the manager app shows it) gives an admin every
+roleplay assignment on the instance and a coaching manager the assignments they coach. `session` opens one session to
+its rep, a coach of that rep, or an admin, and never returns the transcript or recordings. `scenarios` lists the
+instance's scenarios without prompts. A session with no score is unscored, never 0, and Practice Studio takes never
+appear.
+
+```shell
+p roleplay kpis --instance-id 01... --start-date 2026-10-01
+p roleplay sessions --instance-id 01... --rep ann --sort-by score --sort-order desc --limit 50
+p roleplay rep-summary --instance-id 01... --group-by scenario
+p roleplay team --instance-id 01... --status needs_coaching
+p roleplay session --instance-id 01... --entry-id 01ENTRYID...
+p roleplay scenarios --instance-id 01...
 ```
 
-MCP: all ten verbs are exposed as read-only `pitcher_analytics_*` tools, alongside a `pitcher://analytics/catalog` resource (which verb answers which question — returns, time model, key tier) and four query prompts — `top_content`, `content_engagement_summary`, `who_viewed_canvas`, `adoption_snapshot`.
+MCP: `pitcher_roleplay_kpis`, `_sessions`, `_rep_summary`, `_team`, `_session_get`, `_scenarios_list`, all read-only,
+so they are also served to organizations in read-only mode.
 
 ## To run the `users` command:
 
@@ -502,7 +539,7 @@ p metadata-template scaffold --out ./schema.json
 p metadata-template upsert --instance-id 01... --sections-file ./schema.json --api-key myapikey
 ```
 
-`upsert` merges the incoming sections by section `label` — a section whose label matches an existing one is replaced, other sections are preserved. It **cannot remove** a section or field (that's a UI operation). `options` for `select`/`multi-select` fields are `{ label, value }` objects (bare strings are rejected). `upsert` requires an instance- or org-admin key; a non-admin member key is rejected (400 → `VALIDATION`).
+`upsert` merges the incoming sections by section `label` — a section whose label matches an existing one is **replaced whole** (fields left out of it are removed), other sections are preserved. It cannot remove a whole section (that's a UI operation). `options` for `select`/`multi-select` fields are `{ label, value }` objects (bare strings are rejected). `upsert` requires an instance- or org-admin key; a non-admin member key is rejected (400 → `VALIDATION`).
 
 ## To run the `dsr` command:
 

package/dist/index.js

@@ -14,6 +14,7 @@ import { createSharedLinksCommand } from './src/commands/sharedLinks.js';
 import { createTagsCommand } from './src/commands/tags.js';
 import { createOrgCommand } from './src/commands/org.js';
 import { createAnalyticsCommand } from './src/commands/analytics.js';
+import { createRoleplayCommand } from './src/commands/roleplay.js';
 import { createAnnouncementsCommand } from './src/commands/announcements.js';
 import { createDsrLandingCommand } from './src/commands/dsrLanding.js';
 import { createEmailTemplateCommand } from './src/commands/emailTemplate.js';
@@ -61,6 +62,7 @@ program.addCommand(createDsrCommand());
 program.addCommand(createLdCommand());
 program.addCommand(createOrgCommand());
 program.addCommand(createAnalyticsCommand());
+program.addCommand(createRoleplayCommand());
 program.addCommand(createMcpCommand());
 program.addCommand(createLoginCommand());
 program.addCommand(createLogoutCommand());

package/dist/src/commands/analytics.d.ts

@@ -9,6 +9,13 @@ export declare function runAnalyticsOrg(opts: CommonOpts, deps?: AnalyticsDeps):
 export declare function runAnalyticsInstance(opts: CommonOpts & {
     instanceId?: string;
 }, deps?: AnalyticsDeps): Promise<Envelope<unknown>>;
+/**
+ * KPI values as numbers everywhere (PIT-9589): clickhouse-api sends `growth` as a string
+ * (`toFixed()`), and ClickHouse quotes 64-bit integers, so one payload mixes `"88"` and `88`. Only
+ * the `data` subtree is walked, and only a string that is a plain decimal literal is converted;
+ * dates and labels stay strings. The server contract is left alone (the dashboard reads it).
+ */
+export declare function numifyKpiData(value: unknown): unknown;
 export interface AnalyticsKpiOpts extends CommonOpts {
     instanceId?: string;
     type?: string;
@@ -176,4 +183,74 @@ export interface AnalyticsSessionsOpts extends CommonOpts {
  * window, so dates are sent only when the caller supplies them.
  */
 export declare function runAnalyticsSessions(opts: AnalyticsSessionsOpts, deps?: AnalyticsDeps): Promise<Envelope<unknown>>;
+export interface AnalyticsFileUsersOpts extends CommonOpts {
+    instanceId?: string;
+    fileId?: string;
+    startDate?: string;
+    endDate?: string;
+    pageNumber?: number;
+    groupIds?: string;
+    userEmails?: string;
+    limit?: number;
+}
+/**
+ * Who opened ONE file: per user, opens, seconds, days active and the last day, from
+ * `GET /analytics/files/users` (editor/admin tier, the Files tab's user modal). Internal users
+ * only (the server leaves out external viewers). `pageNumber` (0-based) narrows to one page of the
+ * file. Dates default to the last 30 days (the server requires both). Sorted by opens, capped to
+ * `--limit`.
+ */
+export declare function runAnalyticsFileUsers(opts: AnalyticsFileUsersOpts, deps?: AnalyticsDeps): Promise<Envelope<unknown>>;
+export interface AnalyticsFilePagesOpts extends CommonOpts {
+    instanceId?: string;
+    fileId?: string;
+    startDate?: string;
+    endDate?: string;
+    groupIds?: string;
+    userEmails?: string;
+}
+/**
+ * Time per page of ONE file, from `GET /analytics/files/pages` (editor/admin tier): internal
+ * opens and seconds per page, plus external (DSR) views. Pass one `--user-emails` value for one
+ * user's time per page. Dates default to the last 30 days. Every page is returned (no cap).
+ */
+export declare function runAnalyticsFilePages(opts: AnalyticsFilePagesOpts, deps?: AnalyticsDeps): Promise<Envelope<unknown>>;
+export interface AnalyticsCanvasUsersOpts extends CommonOpts {
+    instanceId?: string;
+    canvasId?: string;
+    startDate?: string;
+    endDate?: string;
+    groupIds?: string;
+    userEmails?: string;
+    limit?: number;
+    page?: number;
+}
+/**
+ * Per-user canvas usage from `GET /analytics/canvases/users` (editor/admin tier, PIT-9589): one row
+ * per user and canvas with visits, seconds and the last visit; with `--canvas-id`, each user's
+ * seconds per page (section) too. Internal users only, presentation time only. Dates default to
+ * the last 30 days.
+ */
+export declare function runAnalyticsCanvasUsers(opts: AnalyticsCanvasUsersOpts, deps?: AnalyticsDeps): Promise<Envelope<unknown>>;
+export interface AnalyticsViewerVisitsOpts extends CommonOpts {
+    instanceId?: string;
+    canvasId?: string;
+    userEmail?: string;
+    viewerType?: string;
+    startDate?: string;
+    endDate?: string;
+    limit?: number;
+    format?: string;
+}
+/** Viewers read per call when no single viewer is named; each costs one timeline query. */
+export declare const VIEWER_VISITS_MAX_VIEWERS = 25;
+/**
+ * Per viewer of a DSR canvas: each visit, and in it which sections, files and pages were viewed for
+ * how long (PIT-9589). One viewer (`--user`, verbatim from `viewers`) or the most recently active
+ * viewers (`--limit`, default 10, max 25: one timeline query each). `--format csv` returns the same
+ * as CSV text, one row per viewer, visit and item, for export. Reads
+ * `/analytics/canvas-details/{viewers,sessions}` (any member, as `viewers`/`sessions`); the server
+ * applies its own default window when dates are omitted.
+ */
+export declare function runAnalyticsViewerVisits(opts: AnalyticsViewerVisitsOpts, deps?: AnalyticsDeps): Promise<Envelope<unknown>>;
 export declare function createAnalyticsCommand(): Command;

package/dist/src/commands/analytics.js

@@ -6,6 +6,7 @@ import { emitEnvelope } from '../core/output.js';
 import { withAuthFlags } from './withAuth.js';
 import { isKpiType, KPI_TYPES } from '../core/kpiTypes.js';
 import { shapeAnalytics, pageSizeFor, withDefaultWindow, todayIso } from '../core/analytics-shape.js';
+import { summarizeVisits, visitsToCsv } from '../core/dsr-visits.js';
 export async function runAnalyticsOrg(opts, deps = {}) {
     try {
         const client = clientFor(opts, deps);
@@ -28,6 +29,23 @@ export async function runAnalyticsInstance(opts, deps = {}) {
         return fail(toCliError(e));
     }
 }
+const NUMERIC_TEXT = /^-?\d+(\.\d+)?$/;
+/**
+ * KPI values as numbers everywhere (PIT-9589): clickhouse-api sends `growth` as a string
+ * (`toFixed()`), and ClickHouse quotes 64-bit integers, so one payload mixes `"88"` and `88`. Only
+ * the `data` subtree is walked, and only a string that is a plain decimal literal is converted;
+ * dates and labels stay strings. The server contract is left alone (the dashboard reads it).
+ */
+export function numifyKpiData(value) {
+    if (typeof value === 'string')
+        return NUMERIC_TEXT.test(value.trim()) ? Number(value) : value;
+    if (Array.isArray(value))
+        return value.map(numifyKpiData);
+    if (value && typeof value === 'object') {
+        return Object.fromEntries(Object.entries(value).map(([k, v]) => [k, numifyKpiData(v)]));
+    }
+    return value;
+}
 /**
  * KPI metrics from the clickhouse-api analytics service (PIT-7647). Unlike
  * org/instance rollups (Django), this hits `clickhouse.pitcher.com` with the
@@ -58,7 +76,8 @@ export async function runAnalyticsKpi(opts, deps = {}) {
         if (opts.userEmails)
             params.user_emails = opts.userEmails;
         const res = await client.get('/analytics/kpi', { params });
-        return ok(res.data);
+        const body = res.data;
+        return ok(body && typeof body === 'object' && 'data' in body ? { ...body, data: numifyKpiData(body.data) } : body);
     }
     catch (e) {
         return fail(toCliError(e));
@@ -365,6 +384,241 @@ export async function runAnalyticsSessions(opts, deps = {}) {
         return fail(toCliError(e));
     }
 }
+// ── PIT-9589: per-user file and canvas usage, DSR viewer page detail ─────────
+const toNum = (v) => (v == null || v === '' ? 0 : Number(v));
+/**
+ * Who opened ONE file: per user, opens, seconds, days active and the last day, from
+ * `GET /analytics/files/users` (editor/admin tier, the Files tab's user modal). Internal users
+ * only (the server leaves out external viewers). `pageNumber` (0-based) narrows to one page of the
+ * file. Dates default to the last 30 days (the server requires both). Sorted by opens, capped to
+ * `--limit`.
+ */
+export async function runAnalyticsFileUsers(opts, deps = {}) {
+    try {
+        if (!opts.instanceId)
+            throw createCliError('VALIDATION', '--instance-id is required for analytics file-users');
+        if (!opts.fileId)
+            throw createCliError('VALIDATION', '--file-id is required for analytics file-users');
+        if (opts.pageNumber !== undefined && !(Number.isInteger(opts.pageNumber) && opts.pageNumber >= 0)) {
+            throw createCliError('VALIDATION', '--page-number must be a 0-based page index');
+        }
+        const client = clickhouseClientFor(opts, deps);
+        const windowed = withDefaultWindow(opts, todayIso());
+        const params = {
+            instance_id: opts.instanceId,
+            file_id: opts.fileId,
+            start_date: windowed.startDate,
+            end_date: windowed.endDate,
+        };
+        if (opts.pageNumber !== undefined)
+            params.page_number = opts.pageNumber;
+        if (opts.groupIds)
+            params.group_ids = opts.groupIds;
+        if (opts.userEmails)
+            params.user_emails = opts.userEmails;
+        const res = await client.get('/analytics/files/users', { params });
+        const users = (res.data ?? {}).users ?? [];
+        const rows = users
+            .map((u) => {
+            const days = Array.isArray(u.accountUsage) ? u.accountUsage : [];
+            return {
+                email: u.who ?? null,
+                name: u.userName ?? null,
+                role: u.userRole ?? null,
+                opens: toNum(u.usageCount),
+                seconds: toNum(u.duration),
+                days_active: days.length,
+                last_opened_on: days[0]?.showDate ?? null,
+            };
+        })
+            .sort((a, b) => b.opens - a.opens || b.seconds - a.seconds);
+        return ok(shapeAnalytics(rows, (n) => ({ summary: { file_id: opts.fileId, start_date: windowed.startDate, end_date: windowed.endDate }, rows: n }), { limit: opts.limit }));
+    }
+    catch (e) {
+        return fail(toCliError(e));
+    }
+}
+/**
+ * Time per page of ONE file, from `GET /analytics/files/pages` (editor/admin tier): internal
+ * opens and seconds per page, plus external (DSR) views. Pass one `--user-emails` value for one
+ * user's time per page. Dates default to the last 30 days. Every page is returned (no cap).
+ */
+export async function runAnalyticsFilePages(opts, deps = {}) {
+    try {
+        if (!opts.instanceId)
+            throw createCliError('VALIDATION', '--instance-id is required for analytics file-pages');
+        if (!opts.fileId)
+            throw createCliError('VALIDATION', '--file-id is required for analytics file-pages');
+        const client = clickhouseClientFor(opts, deps);
+        const windowed = withDefaultWindow(opts, todayIso());
+        const params = {
+            instance_id: opts.instanceId,
+            file_id: opts.fileId,
+            start_date: windowed.startDate,
+            end_date: windowed.endDate,
+        };
+        if (opts.groupIds)
+            params.group_ids = opts.groupIds;
+        if (opts.userEmails)
+            params.user_emails = opts.userEmails;
+        const res = await client.get('/analytics/files/pages', { params });
+        const raw = Array.isArray(res.data) ? res.data : [];
+        const pages = raw.map((p) => ({
+            page_number: toNum(p.pageNumber) + 1,
+            internal_opens: toNum(p.openCount),
+            internal_seconds: toNum(p.totalDuration),
+            avg_seconds: p.averageDuration == null ? null : Math.round(toNum(p.averageDuration)),
+            external_views: toNum(p.viewedCount),
+        }));
+        return ok({
+            file_id: opts.fileId,
+            start_date: windowed.startDate,
+            end_date: windowed.endDate,
+            pages,
+            total_count: pages.length,
+        });
+    }
+    catch (e) {
+        return fail(toCliError(e));
+    }
+}
+/**
+ * Per-user canvas usage from `GET /analytics/canvases/users` (editor/admin tier, PIT-9589): one row
+ * per user and canvas with visits, seconds and the last visit; with `--canvas-id`, each user's
+ * seconds per page (section) too. Internal users only, presentation time only. Dates default to
+ * the last 30 days.
+ */
+export async function runAnalyticsCanvasUsers(opts, deps = {}) {
+    try {
+        if (!opts.instanceId)
+            throw createCliError('VALIDATION', '--instance-id is required for analytics canvas-users');
+        const client = clickhouseClientFor(opts, deps);
+        const windowed = withDefaultWindow(opts, todayIso());
+        const page = Number.isInteger(opts.page) && opts.page > 0 ? opts.page : 1;
+        const pageSize = pageSizeFor(opts.limit);
+        const params = {
+            instance_id: opts.instanceId,
+            start_date: windowed.startDate,
+            end_date: windowed.endDate,
+            page,
+            page_size: pageSize,
+        };
+        if (opts.canvasId)
+            params.canvas_id = opts.canvasId;
+        if (opts.groupIds)
+            params.group_ids = opts.groupIds;
+        if (opts.userEmails)
+            params.user_emails = opts.userEmails;
+        const res = await client.get('/analytics/canvases/users', { params });
+        const data = (res.data ?? {}).data ?? {};
+        const rows = Array.isArray(data.rows) ? data.rows.slice(0, pageSize) : [];
+        const total = typeof data.total === 'number' ? data.total : rows.length;
+        const hasMore = (page - 1) * pageSize + rows.length < total;
+        return ok({
+            start_date: windowed.startDate,
+            end_date: windowed.endDate,
+            ...(opts.canvasId ? { canvas_id: opts.canvasId } : {}),
+            rows,
+            total_count: total,
+            returned: rows.length,
+            page,
+            has_more: hasMore,
+            ...(hasMore
+                ? {
+                    truncated: `Showing ${rows.length} of ${total.toLocaleString('en-US')} (page ${page}) — pass page=${page + 1} or narrow with filters`,
+                }
+                : {}),
+        });
+    }
+    catch (e) {
+        return fail(toCliError(e));
+    }
+}
+/** Viewers read per call when no single viewer is named; each costs one timeline query. */
+export const VIEWER_VISITS_MAX_VIEWERS = 25;
+const VIEWER_VISITS_DEFAULT_VIEWERS = 10;
+const VIEWER_VISITS_CONCURRENCY = 3;
+/**
+ * Per viewer of a DSR canvas: each visit, and in it which sections, files and pages were viewed for
+ * how long (PIT-9589). One viewer (`--user`, verbatim from `viewers`) or the most recently active
+ * viewers (`--limit`, default 10, max 25: one timeline query each). `--format csv` returns the same
+ * as CSV text, one row per viewer, visit and item, for export. Reads
+ * `/analytics/canvas-details/{viewers,sessions}` (any member, as `viewers`/`sessions`); the server
+ * applies its own default window when dates are omitted.
+ */
+export async function runAnalyticsViewerVisits(opts, deps = {}) {
+    try {
+        if (!opts.instanceId)
+            throw createCliError('VALIDATION', '--instance-id is required for analytics viewer-visits');
+        if (!opts.canvasId)
+            throw createCliError('VALIDATION', '--canvas-id is required for analytics viewer-visits');
+        const format = (opts.format ?? 'json').toLowerCase();
+        if (format !== 'json' && format !== 'csv')
+            throw createCliError('VALIDATION', '--format must be json or csv');
+        const instanceId = opts.instanceId;
+        const canvasId = opts.canvasId;
+        const client = clickhouseClientFor(opts, deps);
+        const dates = {};
+        if (opts.startDate)
+            dates.start_date = opts.startDate;
+        if (opts.endDate)
+            dates.end_date = opts.endDate;
+        let viewers;
+        let viewersTotal;
+        if (opts.userEmail) {
+            viewers = [opts.userEmail];
+            viewersTotal = 1;
+        }
+        else {
+            const want = Math.min(Math.max(Number.isFinite(opts.limit) ? opts.limit : VIEWER_VISITS_DEFAULT_VIEWERS, 1), VIEWER_VISITS_MAX_VIEWERS);
+            const params = {
+                instance_id: instanceId,
+                canvas_id: canvasId,
+                page_size: want,
+                sort_by: 'last_active',
+                sort_order: 'desc',
+                ...dates,
+            };
+            if (opts.viewerType)
+                params.viewer_type = opts.viewerType;
+            const res = await client.get('/analytics/canvas-details/viewers', { params });
+            const list = (res.data ?? {})
+                .viewers;
+            const items = (list?.items ?? []).slice(0, want);
+            viewers = items.map((v) => String(v.normalized_email ?? v.email ?? '')).filter(Boolean);
+            viewersTotal = typeof list?.total === 'number' ? list.total : viewers.length;
+        }
+        const results = new Array(viewers.length);
+        let next = 0;
+        const worker = async () => {
+            while (next < viewers.length) {
+                const i = next++;
+                const res = await client.get('/analytics/canvas-details/sessions', {
+                    params: { instance_id: instanceId, canvas_id: canvasId, user_email: viewers[i], ...dates },
+                });
+                const events = (res.data ?? {}).events ?? [];
+                results[i] = { viewer: viewers[i], visits: summarizeVisits(events, canvasId) };
+            }
+        };
+        await Promise.all(Array.from({ length: Math.min(VIEWER_VISITS_CONCURRENCY, viewers.length) }, worker));
+        const truncated = viewersTotal > viewers.length
+            ? `Covers the ${viewers.length} most recently active of ${viewersTotal.toLocaleString('en-US')} viewers — pass userEmail, or a higher limit (max ${VIEWER_VISITS_MAX_VIEWERS})`
+            : undefined;
+        const common = {
+            canvas_id: canvasId,
+            viewers_returned: results.length,
+            viewers_total: viewersTotal,
+            ...(truncated ? { truncated } : {}),
+        };
+        if (format === 'csv') {
+            return ok({ ...common, format: 'csv', filename: `dsr-viewer-visits-${canvasId}.csv`, csv: visitsToCsv(results) });
+        }
+        return ok({ ...common, viewers: results });
+    }
+    catch (e) {
+        return fail(toCliError(e));
+    }
+}
 export function createAnalyticsCommand() {
     const cmd = new Command('analytics').description('read rollup analytics totals (requires an org-admin API key)');
     withAuthFlags(cmd.command('org'))
@@ -495,5 +749,59 @@ export function createAnalyticsCommand() {
         const globals = command.optsWithGlobals();
         emitEnvelope(await runAnalyticsSessions({ ...options, userEmail: options.user, quiet: globals.quiet }), globals);
     });
+    withAuthFlags(cmd.command('file-users'))
+        .option('--instance-id <id>', 'Instance ID (required)')
+        .option('--file-id <id>', 'File ID (required)')
+        .option('--start-date <iso>', 'Window start (ISO date; defaults to 30 days ago)')
+        .option('--end-date <iso>', 'Window end (ISO date; defaults to today)')
+        .option('--page-number <n>', 'Only this page of the file (0-based)', (v) => parseInt(v, 10))
+        .option('--group-ids <csv>', 'Comma-separated distribution-group IDs')
+        .option('--user-emails <csv>', 'Comma-separated user emails to scope by')
+        .option('--limit <n>', 'Max rows to return (default 20, max 100)', (v) => parseInt(v, 10))
+        .description('who opened one file: opens, seconds and days active per user (editor/admin key)')
+        .action(async (options, command) => {
+        const globals = command.optsWithGlobals();
+        emitEnvelope(await runAnalyticsFileUsers({ ...options, quiet: globals.quiet }), globals);
+    });
+    withAuthFlags(cmd.command('file-pages'))
+        .option('--instance-id <id>', 'Instance ID (required)')
+        .option('--file-id <id>', 'File ID (required)')
+        .option('--start-date <iso>', 'Window start (ISO date; defaults to 30 days ago)')
+        .option('--end-date <iso>', 'Window end (ISO date; defaults to today)')
+        .option('--group-ids <csv>', 'Comma-separated distribution-group IDs')
+        .option('--user-emails <csv>', 'Comma-separated user emails to scope by (one email: that user)')
+        .description('time per page of one file (editor/admin key)')
+        .action(async (options, command) => {
+        const globals = command.optsWithGlobals();
+        emitEnvelope(await runAnalyticsFilePages({ ...options, quiet: globals.quiet }), globals);
+    });
+    withAuthFlags(cmd.command('canvas-users'))
+        .option('--instance-id <id>', 'Instance ID (required)')
+        .option('--canvas-id <id>', "One canvas: adds each user's seconds per page (section)")
+        .option('--start-date <iso>', 'Window start (ISO date; defaults to 30 days ago)')
+        .option('--end-date <iso>', 'Window end (ISO date; defaults to today)')
+        .option('--group-ids <csv>', 'Comma-separated distribution-group IDs')
+        .option('--user-emails <csv>', 'Comma-separated user emails to scope by')
+        .option('--page <n>', 'Page number', (v) => parseInt(v, 10))
+        .option('--limit <n>', 'Rows per page (default 20, max 100)', (v) => parseInt(v, 10))
+        .description('per-user canvas usage: visits and seconds per user and canvas (editor/admin key)')
+        .action(async (options, command) => {
+        const globals = command.optsWithGlobals();
+        emitEnvelope(await runAnalyticsCanvasUsers({ ...options, quiet: globals.quiet }), globals);
+    });
+    withAuthFlags(cmd.command('viewer-visits'))
+        .option('--instance-id <id>', 'Instance ID (required)')
+        .option('--canvas-id <id>', 'DSR canvas ID (required)')
+        .option('--user <email>', 'One viewer, verbatim from analytics viewers (default: the most recent viewers)')
+        .option('--viewer-type <type>', "Viewer type when listing: all, internal, external (default 'all')")
+        .option('--start-date <iso>', 'Window start (ISO date; server default applies if omitted)')
+        .option('--end-date <iso>', 'Window end (ISO date; server default applies if omitted)')
+        .option('--limit <n>', 'Viewers to read when no --user (default 10, max 25)', (v) => parseInt(v, 10))
+        .option('--format <fmt>', 'json (default) or csv')
+        .description('per DSR viewer: each visit and the sections, files and pages viewed with their time')
+        .action(async (options, command) => {
+        const globals = command.optsWithGlobals();
+        emitEnvelope(await runAnalyticsViewerVisits({ ...options, userEmail: options.user, quiet: globals.quiet }), globals);
+    });
     return cmd;
 }

package/dist/src/commands/metadataTemplate.js

@@ -69,8 +69,9 @@ export async function runMetadataTemplateUpsert(opts, deps = {}) {
 const UPSERT_HELP = `
 Upserts the instance's metadata-field schema. POST is an upsert keyed by
 instance that MERGES the incoming sections by section 'label' — a section whose
-label matches an existing one is replaced, other sections are preserved. It
-CANNOT remove a section or field (a full-replace / UI operation).
+label matches an existing one is replaced whole (fields left out of it are
+removed), other sections are preserved. It cannot remove a whole section (a
+full-replace / UI operation).
   --instance-id    the instance whose schema to upsert (required)
   --sections       inline JSON array of sections, OR
   --sections-file  path to a JSON file with the sections array (exactly one)

package/dist/src/commands/roleplay.d.ts

@@ -0,0 +1,85 @@
+import { Command } from 'commander';
+import type { AxiosInstance } from 'axios';
+import { type CommonOpts } from '../core/http.js';
+import { type Envelope } from '../core/envelope.js';
+/**
+ * AI Roleplay reads (PIT-9200, Phase 1: read-only). Two sources:
+ * - clickhouse-api `/analytics/roleplay/{kpis,sessions}` (the `roleplay_statements` replica,
+ *   instance or org admins only): `kpis`, `sessions`, `rep-summary`;
+ * - next-core `/core/api/protected/roleplay/coach/*` and appsDB (`cch-*` rows in Postgres):
+ *   `team`, `session`, `scenarios`.
+ * A session with no score is unscored, never 0. Practice Studio takes (`manager-video-practice`)
+ * never appear: the coach routes exclude them by default and `team` drops practice assignments.
+ */
+export interface RoleplayDeps {
+    client?: AxiosInstance;
+}
+export declare const ROLEPLAY_DIFFICULTIES: readonly ["easy", "medium", "hard"];
+export declare const ROLEPLAY_SESSION_SORT: readonly ["session_at", "rep_name", "score", "duration_ms"];
+export declare const ROLEPLAY_GROUP_BY: readonly ["rep", "scenario"];
+/** rep-summary reads at most this many pages of this size (5000 sessions), newest first. */
+export declare const REP_SUMMARY_PAGE_SIZE = 1000;
+export declare const REP_SUMMARY_MAX_PAGES = 5;
+export declare const REP_SUMMARY_MAX_GROUPS = 50;
+/** next-core's coach/data returns at most this many sessions, newest first, and no total. */
+export declare const COACH_DATA_SESSION_CAP = 1000;
+export declare const TEAM_MAX_ASSIGNMENTS = 50;
+export declare const TEAM_MAX_REPS_PER_ASSIGNMENT = 100;
+export interface RoleplayFilterOpts extends CommonOpts {
+    instanceId?: string;
+    startDate?: string;
+    endDate?: string;
+    rep?: string;
+    scenario?: string;
+    difficulty?: string;
+}
+/** Totals for the window: sessions, scored/unscored, mean score over SCORED sessions only, active reps. */
+export declare function runRoleplayKpis(opts: RoleplayFilterOpts, deps?: RoleplayDeps): Promise<Envelope<unknown>>;
+declare const SESSION_FIELDS: readonly ["entry_id", "session_at", "rep_name", "who", "scenario_name", "persona_name", "difficulty", "score", "evaluated", "rating", "duration_ms"];
+export type RoleplaySessionRow = Record<(typeof SESSION_FIELDS)[number], unknown>;
+/** The row allowlist: nothing else from the replica (provider, recording flags, rubric) leaves. */
+export declare function pickSessionRow(row: Record<string, unknown>): RoleplaySessionRow;
+export interface RoleplaySessionsOpts extends RoleplayFilterOpts {
+    sortBy?: string;
+    sortOrder?: string;
+    limit?: number;
+    page?: number;
+}
+export declare function runRoleplaySessions(opts: RoleplaySessionsOpts, deps?: RoleplayDeps): Promise<Envelope<unknown>>;
+export interface RoleplayRepSummaryOpts extends RoleplayFilterOpts {
+    groupBy?: string;
+}
+/**
+ * Per-rep (keyed on the rep email `who`) or per-scenario (keyed on `scenario_id`) aggregates over
+ * the sessions list, read in pages of 1000 (newest first) up to 5000. `complete: false` when the
+ * window holds more than that; then the figures cover the newest 5000 only.
+ */
+export declare function runRoleplayRepSummary(opts: RoleplayRepSummaryOpts, deps?: RoleplayDeps): Promise<Envelope<unknown>>;
+export interface RoleplayTeamOpts extends CommonOpts {
+    instanceId?: string;
+    assignmentId?: string;
+    status?: string;
+}
+/**
+ * Assignment completion per rep, ported from the manager app: an admin gets every roleplay
+ * assignment on the instance (`scope=instance`), anyone else the assignments they coach.
+ * Statuses follow `deriveStatus`; raw sessions, evaluations and comments never leave.
+ */
+export declare function runRoleplayTeam(opts: RoleplayTeamOpts, deps?: RoleplayDeps): Promise<Envelope<unknown>>;
+export interface RoleplaySessionGetOpts extends CommonOpts {
+    instanceId?: string;
+    entryId?: string;
+}
+/**
+ * The allowlist. Never the transcript, messages, contact name, graded snapshot, voice session,
+ * recording or audio ids, or any video-evaluation field.
+ */
+export declare function pickSessionDetail(id: string, data: Record<string, unknown>): Record<string, unknown>;
+export declare function runRoleplaySessionGet(opts: RoleplaySessionGetOpts, deps?: RoleplayDeps): Promise<Envelope<unknown>>;
+/** The trimmed catalog: never the persona prompt or the evaluation prompt. */
+export declare function pickScenario(s: Record<string, unknown>): Record<string, unknown>;
+export declare function runRoleplayScenariosList(opts: CommonOpts & {
+    instanceId?: string;
+}, deps?: RoleplayDeps): Promise<Envelope<unknown>>;
+export declare function createRoleplayCommand(): Command;
+export {};