@pitcher/cli-scripts 3.1.0 → 3.2.0

package/dist/src/commands/roleplay.js

@@ -0,0 +1,449 @@
+import { Command } from 'commander';
+import { clickhouseClientFor, clientFor, toCliError } from '../core/http.js';
+import { ok, fail } from '../core/envelope.js';
+import { createCliError, isCliError } from '../core/errors.js';
+import { emitEnvelope } from '../core/output.js';
+import { pageSizeFor } from '../core/analytics-shape.js';
+import { assignmentSessions, repStats, sessionScore, skillAverages, } from '../core/roleplay-stats.js';
+import { withAuthFlags } from './withAuth.js';
+export const ROLEPLAY_DIFFICULTIES = ['easy', 'medium', 'hard'];
+export const ROLEPLAY_SESSION_SORT = ['session_at', 'rep_name', 'score', 'duration_ms'];
+export const ROLEPLAY_GROUP_BY = ['rep', 'scenario'];
+const REP_STATUSES = ['passed', 'in_progress', 'not_started', 'overdue', 'needs_coaching'];
+/** rep-summary reads at most this many pages of this size (5000 sessions), newest first. */
+export const REP_SUMMARY_PAGE_SIZE = 1000;
+export const REP_SUMMARY_MAX_PAGES = 5;
+export const REP_SUMMARY_MAX_GROUPS = 50;
+/** next-core's coach/data returns at most this many sessions, newest first, and no total. */
+export const COACH_DATA_SESSION_CAP = 1000;
+export const TEAM_MAX_ASSIGNMENTS = 50;
+export const TEAM_MAX_REPS_PER_ASSIGNMENT = 100;
+const COACH_BASE = '/core/api/protected/roleplay/coach';
+const APPSDB_QUERY = '/core/api/protected/appsdb/query';
+function requireInstance(opts, verb) {
+    if (!opts.instanceId)
+        throw createCliError('VALIDATION', `--instance-id is required for roleplay ${verb}`);
+    return opts.instanceId;
+}
+/** clickhouse-api params; `scenario` matches the persona OR scenario name server-side (`persona`). */
+function filterParams(opts, instanceId) {
+    if (opts.difficulty && !ROLEPLAY_DIFFICULTIES.includes(opts.difficulty)) {
+        throw createCliError('VALIDATION', `--difficulty must be one of: ${ROLEPLAY_DIFFICULTIES.join(', ')}`);
+    }
+    const params = { instance_id: instanceId };
+    if (opts.startDate)
+        params.start_date = opts.startDate;
+    if (opts.endDate)
+        params.end_date = opts.endDate;
+    if (opts.rep)
+        params.rep = opts.rep;
+    if (opts.scenario)
+        params.persona = opts.scenario;
+    if (opts.difficulty)
+        params.difficulty = opts.difficulty;
+    return params;
+}
+/** Dates have NO default window here (unlike the content-analytics verbs): omitted = all time. */
+function windowOf(opts) {
+    return { start_date: opts.startDate ?? null, end_date: opts.endDate ?? null };
+}
+const finiteOrNull = (v) => (typeof v === 'number' && Number.isFinite(v) ? v : null);
+/** clickhouse-api's roleplay routes are instance/org-admin only: say so, and where a manager goes instead. */
+function adminOnlyError(e) {
+    const err = toCliError(e);
+    if (err.code !== 'AUTH')
+        return err;
+    return createCliError('AUTH', `${err.message} — roleplay analytics are for instance or org admins; a coaching manager can use roleplay team`);
+}
+// ── kpis ─────────────────────────────────────────────────────────────────────
+/** Totals for the window: sessions, scored/unscored, mean score over SCORED sessions only, active reps. */
+export async function runRoleplayKpis(opts, deps = {}) {
+    try {
+        const instanceId = requireInstance(opts, 'kpis');
+        const params = filterParams(opts, instanceId);
+        const client = clickhouseClientFor(opts, deps);
+        const res = await client.get('/analytics/roleplay/kpis', { params });
+        return ok({ ...res.data, window: windowOf(opts) });
+    }
+    catch (e) {
+        return fail(adminOnlyError(e));
+    }
+}
+// ── sessions ─────────────────────────────────────────────────────────────────
+const SESSION_FIELDS = [
+    'entry_id',
+    'session_at',
+    'rep_name',
+    'who',
+    'scenario_name',
+    'persona_name',
+    'difficulty',
+    'score',
+    'evaluated',
+    'rating',
+    'duration_ms',
+];
+/** The row allowlist: nothing else from the replica (provider, recording flags, rubric) leaves. */
+export function pickSessionRow(row) {
+    const out = {};
+    for (const f of SESSION_FIELDS)
+        out[f] = row[f] ?? null;
+    out.score = finiteOrNull(row.score);
+    return out;
+}
+export async function runRoleplaySessions(opts, deps = {}) {
+    try {
+        const instanceId = requireInstance(opts, 'sessions');
+        if (opts.sortBy && !ROLEPLAY_SESSION_SORT.includes(opts.sortBy)) {
+            throw createCliError('VALIDATION', `--sort-by must be one of: ${ROLEPLAY_SESSION_SORT.join(', ')}`);
+        }
+        const sortOrder = opts.sortOrder?.toLowerCase();
+        if (sortOrder && sortOrder !== 'asc' && sortOrder !== 'desc') {
+            throw createCliError('VALIDATION', '--sort-order must be asc or desc');
+        }
+        const page = Number.isInteger(opts.page) && opts.page > 0 ? opts.page : 1;
+        const pageSize = pageSizeFor(opts.limit);
+        const params = { ...filterParams(opts, instanceId), page, page_size: pageSize };
+        if (opts.sortBy)
+            params.sort_by = opts.sortBy;
+        if (sortOrder)
+            params.sort_order = sortOrder;
+        const client = clickhouseClientFor(opts, deps);
+        const res = await client.get('/analytics/roleplay/sessions', { params });
+        const body = (res.data ?? {});
+        const rows = (Array.isArray(body.data) ? body.data : []).slice(0, pageSize).map(pickSessionRow);
+        const total = typeof body.total === 'number' ? body.total : rows.length;
+        const shown = (page - 1) * pageSize + rows.length;
+        const hasMore = shown < total;
+        return ok({
+            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` }
+                : {}),
+            window: windowOf(opts),
+        });
+    }
+    catch (e) {
+        return fail(adminOnlyError(e));
+    }
+}
+const round1 = (n) => Math.round(n * 10) / 10;
+/**
+ * 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 async function runRoleplayRepSummary(opts, deps = {}) {
+    try {
+        const instanceId = requireInstance(opts, 'rep-summary');
+        const groupBy = opts.groupBy ?? 'rep';
+        if (!ROLEPLAY_GROUP_BY.includes(groupBy)) {
+            throw createCliError('VALIDATION', `--group-by must be one of: ${ROLEPLAY_GROUP_BY.join(', ')}`);
+        }
+        const base = filterParams(opts, instanceId);
+        const client = clickhouseClientFor(opts, deps);
+        const fetched = [];
+        let total = 0;
+        for (let page = 1; page <= REP_SUMMARY_MAX_PAGES; page += 1) {
+            const res = await client.get('/analytics/roleplay/sessions', {
+                params: { ...base, page, page_size: REP_SUMMARY_PAGE_SIZE, sort_by: 'session_at', sort_order: 'desc' },
+            });
+            const body = (res.data ?? {});
+            const batch = Array.isArray(body.data) ? body.data : [];
+            total = typeof body.total === 'number' ? body.total : fetched.length + batch.length;
+            fetched.push(...batch);
+            if (batch.length < REP_SUMMARY_PAGE_SIZE || fetched.length >= total)
+                break;
+        }
+        const groups = new Map();
+        for (const row of fetched) {
+            const key = String((groupBy === 'rep' ? row.who : row.scenario_id) ?? '');
+            const name = String((groupBy === 'rep' ? row.rep_name || row.who : row.scenario_name || row.persona_name) ?? '');
+            const g = groups.get(key) ?? { name, sessions: 0, scores: [], last: null };
+            g.sessions += 1;
+            const score = finiteOrNull(row.score);
+            if (score !== null)
+                g.scores.push(score);
+            const at = typeof row.session_at === 'string' ? row.session_at : null;
+            if (at && (!g.last || at > g.last))
+                g.last = at;
+            groups.set(key, g);
+        }
+        const all = Array.from(groups.entries())
+            .map(([key, g]) => ({
+            key,
+            name: g.name,
+            sessions: g.sessions,
+            scored_sessions: g.scores.length,
+            avg_score: g.scores.length ? round1(g.scores.reduce((a, b) => a + b, 0) / g.scores.length) : null,
+            last_session_at: g.last,
+        }))
+            .sort((a, b) => b.sessions - a.sessions || a.key.localeCompare(b.key));
+        const shown = all.slice(0, REP_SUMMARY_MAX_GROUPS);
+        const complete = fetched.length >= total;
+        const warnings = [];
+        if (!complete) {
+            warnings.push(`Covers the newest ${fetched.length.toLocaleString('en-US')} of ${total.toLocaleString('en-US')} sessions; narrow the dates for exact figures`);
+        }
+        return ok({
+            group_by: groupBy,
+            key_field: groupBy === 'rep' ? 'who (rep email)' : 'scenario_id',
+            groups: shown,
+            total_groups: all.length,
+            returned: shown.length,
+            sessions_read: fetched.length,
+            total_sessions: total,
+            complete,
+            ...(all.length > shown.length
+                ? { truncated: `Showing the ${shown.length} ${groupBy === 'rep' ? 'reps' : 'scenarios'} with most sessions of ${all.length}` }
+                : {}),
+            ...(warnings.length ? { warnings } : {}),
+            window: windowOf(opts),
+        });
+    }
+    catch (e) {
+        return fail(adminOnlyError(e));
+    }
+}
+async function getCoachBundle(client, instanceId) {
+    const headers = { 'x-instance-id': instanceId };
+    try {
+        const res = await client.get(`${COACH_BASE}/data`, { params: { instance_id: instanceId, scope: 'instance' }, headers });
+        return { bundle: (res.data ?? {}), requested: 'instance' };
+    }
+    catch (e) {
+        // Not an instance or org admin: fall back to the caller's own coaching assignments.
+        if (toCliError(e).code !== 'AUTH')
+            throw e;
+        const res = await client.get(`${COACH_BASE}/data`, { params: { instance_id: instanceId }, headers });
+        return { bundle: (res.data ?? {}), requested: 'coach' };
+    }
+}
+/**
+ * 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 async function runRoleplayTeam(opts, deps = {}) {
+    try {
+        const instanceId = requireInstance(opts, 'team');
+        if (opts.status && !REP_STATUSES.includes(opts.status)) {
+            throw createCliError('VALIDATION', `--status must be one of: ${REP_STATUSES.join(', ')}`);
+        }
+        const client = clientFor(opts, deps);
+        const { bundle, requested } = await getCoachBundle(client, instanceId);
+        // An older next-core ignores scope=instance and answers without `scope`: report what was applied.
+        const scope = bundle.scope === 'instance' && requested === 'instance' ? 'instance' : 'coach';
+        const sessions = (bundle.sessions ?? []).filter((s) => s.sessionType !== 'manager-video-practice');
+        const roleplayAssignments = (bundle.assignments ?? []).filter((a) => a.contentType !== 'practice');
+        const selected = opts.assignmentId ? roleplayAssignments.filter((a) => a.id === opts.assignmentId) : roleplayAssignments;
+        if (opts.assignmentId && selected.length === 0) {
+            throw createCliError('NOT_FOUND', `No roleplay assignment ${opts.assignmentId} in this ${scope === 'instance' ? 'instance' : 'coaching scope'}`);
+        }
+        const now = new Date();
+        const shownAssignments = selected.slice(0, TEAM_MAX_ASSIGNMENTS);
+        const assignments = shownAssignments.map((a) => {
+            const own = assignmentSessions(sessions, a);
+            const reps = (a.resolvedUserIds ?? []).map((id) => ({
+                ...repStats(id, own, a, now),
+                name: a.resolvedUserNames?.[id] ?? null,
+            }));
+            const statusCounts = Object.fromEntries(REP_STATUSES.map((st) => [st, reps.filter((r) => r.status === st).length]));
+            const filtered = opts.status ? reps.filter((r) => r.status === opts.status) : reps;
+            const shownReps = filtered.slice(0, TEAM_MAX_REPS_PER_ASSIGNMENT);
+            return {
+                id: a.id,
+                scenario_id: a.scenarioId,
+                scenario_name: a.scenarioName ?? null,
+                type: a.type,
+                passing_score: a.passingScore,
+                due_date: a.dueDate,
+                active: a.active !== false,
+                created_at: a.createdAt,
+                rep_count: reps.length,
+                status_counts: statusCounts,
+                skills: skillAverages(own),
+                reps: shownReps,
+                ...(filtered.length > shownReps.length
+                    ? { truncated: `Showing ${shownReps.length} of ${filtered.length} reps — filter with status` }
+                    : {}),
+            };
+        });
+        const capped = sessions.length >= COACH_DATA_SESSION_CAP;
+        const warnings = [];
+        if (capped) {
+            warnings.push(`The server returned its maximum of ${COACH_DATA_SESSION_CAP} sessions (newest first); older sessions are missing, so statuses and averages may be understated`);
+        }
+        return ok({
+            scope,
+            complete: !capped,
+            assignments,
+            total_assignments: selected.length,
+            returned: assignments.length,
+            ...(selected.length > assignments.length
+                ? { truncated: `Showing ${assignments.length} of ${selected.length} assignments — pass assignmentId` }
+                : {}),
+            ...(warnings.length ? { warnings } : {}),
+        });
+    }
+    catch (e) {
+        return fail(toCliError(e));
+    }
+}
+/**
+ * The allowlist. Never the transcript, messages, contact name, graded snapshot, voice session,
+ * recording or audio ids, or any video-evaluation field.
+ */
+export function pickSessionDetail(id, data) {
+    const evaluation = (data.evaluation ?? null);
+    const categories = Array.isArray(evaluation?.category_scores) ? evaluation.category_scores : [];
+    const score = sessionScore(data);
+    return {
+        id,
+        scenario_name: data.scenarioName ?? null,
+        difficulty: data.difficulty ?? null,
+        timestamp: data.timestamp ?? null,
+        duration_ms: finiteOrNull(data.durationMs),
+        overall_score: score,
+        scored: score !== null,
+        evaluation_status: data.evaluationStatus ?? null,
+        evaluation: evaluation
+            ? {
+                summary: evaluation.summary ?? null,
+                strengths: Array.isArray(evaluation.strengths) ? evaluation.strengths : [],
+                improvements: Array.isArray(evaluation.improvements) ? evaluation.improvements : [],
+                category_scores: categories.map((c) => ({
+                    skill_id: c.skillId ?? null,
+                    title: c.title ?? null,
+                    score: finiteOrNull(c.score),
+                    feedback: c.feedback ?? null,
+                })),
+            }
+            : null,
+    };
+}
+export async function runRoleplaySessionGet(opts, deps = {}) {
+    try {
+        const instanceId = requireInstance(opts, 'session');
+        if (!opts.entryId)
+            throw createCliError('VALIDATION', '--entry-id is required for roleplay session');
+        const client = clientFor(opts, deps);
+        const res = await client.get(`${COACH_BASE}/sessions/${encodeURIComponent(opts.entryId)}`, {
+            params: { instance_id: instanceId },
+            headers: { 'x-instance-id': instanceId },
+        });
+        const body = (res.data ?? {});
+        return ok(pickSessionDetail(String(body.id ?? opts.entryId), body.data ?? {}));
+    }
+    catch (e) {
+        if (isCliError(e))
+            return fail(e);
+        const err = toCliError(e);
+        if (err.code === 'AUTH') {
+            return fail(createCliError('AUTH', `${err.message} — a session opens to its rep, a coach of that rep, or an instance or org admin`));
+        }
+        return fail(err);
+    }
+}
+// ── scenarios ────────────────────────────────────────────────────────────────
+/** The trimmed catalog: never the persona prompt or the evaluation prompt. */
+export function pickScenario(s) {
+    const persona = (s.persona ?? null);
+    const assessment = (s.assessment ?? null);
+    return {
+        id: s.id ?? null,
+        kind: s.kind === 'multi' ? 'multi' : 'single',
+        name: (persona?.name ?? s.name ?? null),
+        persona_title: persona?.title ?? null,
+        description: s.description ?? null,
+        difficulty: s.difficulty ?? 'medium',
+        active: s.active !== false,
+        time_limit_minutes: s.time_limit_minutes ?? null,
+        categories: (assessment?.categories ?? []).map((c) => ({ title: c.title ?? null, weight: c.weight ?? null })),
+    };
+}
+export async function runRoleplayScenariosList(opts, deps = {}) {
+    try {
+        const instanceId = requireInstance(opts, 'scenarios');
+        const client = clientFor(opts, deps);
+        // Newest row only: duplicate cch-config rows exist, and the admin app reads the same one.
+        const res = await client.post(APPSDB_QUERY, {
+            type: 'cch-config',
+            where: { field: 'instance_id', operator: 'eq', value: instanceId },
+            orderBy: [{ field: 'updated_at', direction: 'desc' }],
+            limit: 1,
+        }, { headers: { 'x-instance-id': instanceId } });
+        const entry = (res.data ?? {}).entries?.[0];
+        const scenarios = Array.isArray(entry?.data?.scenarios) ? entry.data.scenarios : [];
+        return ok({ configured: !!entry, scenarios: scenarios.map(pickScenario), total_count: scenarios.length });
+    }
+    catch (e) {
+        return fail(toCliError(e));
+    }
+}
+// ── commander ────────────────────────────────────────────────────────────────
+const ADMIN_NOTE = 'instance or org admins only';
+function withFilterFlags(cmd) {
+    return cmd
+        .option('--instance-id <id>', 'Instance ID (required)')
+        .option('--start-date <iso>', 'Window start (ISO date; omitted = all time)')
+        .option('--end-date <iso>', 'Window end (ISO date; omitted = all time)')
+        .option('--rep <text>', 'Rep name or email contains')
+        .option('--scenario <text>', 'Scenario or persona name contains')
+        .option('--difficulty <level>', `Difficulty: ${ROLEPLAY_DIFFICULTIES.join(', ')}`);
+}
+export function createRoleplayCommand() {
+    const cmd = new Command('roleplay').description('read AI Roleplay sessions, scores and assignment completion');
+    withFilterFlags(withAuthFlags(cmd.command('kpis')))
+        .description(`roleplay totals: sessions, scored/unscored, mean score of scored sessions, active reps (${ADMIN_NOTE})`)
+        .action(async (options, command) => {
+        const globals = command.optsWithGlobals();
+        emitEnvelope(await runRoleplayKpis({ ...options, quiet: globals.quiet }), globals);
+    });
+    withFilterFlags(withAuthFlags(cmd.command('sessions')))
+        .option('--sort-by <field>', `Sort field: ${ROLEPLAY_SESSION_SORT.join(', ')}`)
+        .option('--sort-order <dir>', 'asc or desc (default desc)')
+        .option('--page <n>', 'Page number', (v) => parseInt(v, 10))
+        .option('--limit <n>', 'Rows per page (default 20, max 100)', (v) => parseInt(v, 10))
+        .description(`roleplay session list (${ADMIN_NOTE})`)
+        .action(async (options, command) => {
+        const globals = command.optsWithGlobals();
+        emitEnvelope(await runRoleplaySessions({ ...options, quiet: globals.quiet }), globals);
+    });
+    withFilterFlags(withAuthFlags(cmd.command('rep-summary')))
+        .option('--group-by <key>', `Group by: ${ROLEPLAY_GROUP_BY.join(', ')} (default rep)`)
+        .description(`per-rep or per-scenario session counts and mean scores (${ADMIN_NOTE})`)
+        .action(async (options, command) => {
+        const globals = command.optsWithGlobals();
+        emitEnvelope(await runRoleplayRepSummary({ ...options, quiet: globals.quiet }), globals);
+    });
+    withAuthFlags(cmd.command('team'))
+        .option('--instance-id <id>', 'Instance ID (required)')
+        .option('--assignment-id <id>', 'Only this assignment')
+        .option('--status <status>', `Only reps with this status: ${REP_STATUSES.join(', ')}`)
+        .description('assignment completion per rep: every assignment for admins, your coached ones for managers')
+        .action(async (options, command) => {
+        const globals = command.optsWithGlobals();
+        emitEnvelope(await runRoleplayTeam({ ...options, quiet: globals.quiet }), globals);
+    });
+    withAuthFlags(cmd.command('session'))
+        .option('--instance-id <id>', 'Instance ID (required)')
+        .option('--entry-id <id>', 'Session entry ID (required; entry_id from roleplay sessions)')
+        .description('one session: score, summary, strengths, improvements, per-skill scores (no transcript)')
+        .action(async (options, command) => {
+        const globals = command.optsWithGlobals();
+        emitEnvelope(await runRoleplaySessionGet({ ...options, quiet: globals.quiet }), globals);
+    });
+    withAuthFlags(cmd.command('scenarios'))
+        .option('--instance-id <id>', 'Instance ID (required)')
+        .description('the instance scenario catalog (names, difficulty, skills; no prompts)')
+        .action(async (options, command) => {
+        const globals = command.optsWithGlobals();
+        emitEnvelope(await runRoleplayScenariosList({ ...options, quiet: globals.quiet }), globals);
+    });
+    return cmd;
+}

package/dist/src/core/dsr-visits.d.ts

@@ -0,0 +1,50 @@
+/**
+ * One DSR viewer's event timeline (`/analytics/canvas-details/sessions`) → visits, and per visit the
+ * sections, files and pages viewed with their time (PIT-9589). The visit rule is the Sharing
+ * Analytics app's (`packages/apps/canvas-analytics/src/lib/reconstructSessions.ts`): a visit opens
+ * on an `Entered` of the canvas itself and is keyed by its `event_pair_id`; its engaged time is the
+ * sum of its focus segments (canvas Entered → Exited). Change them together.
+ *
+ * Item time: the sum of the item's `Exited` durations (`forhowlong`, seconds) in the visit. An
+ * `Entered` with no `Exited` (the unload beacon was dropped, PIT-5833) or an `Exited` reporting 0 is
+ * estimated from the gap to the next event of the visit, as the app's timeline does, and flagged
+ * `estimated`.
+ */
+export interface DsrSessionEvent {
+    timestamp: string;
+    action: string;
+    entity_id: string;
+    entity_type?: string;
+    entity_name?: string;
+    original_event_name: string;
+    duration?: number;
+    event_pair_id?: string;
+}
+export interface DsrVisitItem {
+    type: 'section' | 'file' | 'page';
+    id: string;
+    name: string;
+    page_number?: number;
+    views: number;
+    seconds: number;
+    estimated: boolean;
+}
+export interface DsrVisit {
+    visit: number;
+    started_at: string;
+    ended_at: string;
+    engaged_seconds: number;
+    items: DsrVisitItem[];
+}
+/** `reconstructSessions`' grouping: events from an anchor `Entered` until the next one, by pair key. */
+export declare function groupVisits(events: DsrSessionEvent[], anchorId: string): DsrSessionEvent[][];
+/** `computeEngagementDuration`: the wall-clock of each canvas focus segment, summed. */
+export declare function engagedSeconds(events: DsrSessionEvent[], anchorId: string): number;
+export declare function summarizeVisits(events: DsrSessionEvent[], canvasId: string): DsrVisit[];
+/** RFC 4180 cell; a leading = + - @ is prefixed with ' so a spreadsheet never runs it as a formula. */
+export declare function csvCell(v: unknown): string;
+export declare const VISITS_CSV_HEADER: string[];
+export declare function visitsToCsv(viewers: Array<{
+    viewer: string;
+    visits: DsrVisit[];
+}>): string;