ravensight-playtest 0.3.0 → 0.3.2

package/src/commands/brief.js

@@ -7,6 +7,8 @@ import { readJson } from '../fsutil.js';
 import { briefLink, openInBrowser } from '../dashboard.js';
 import { ui } from '../ui/index.js';
 import { CliError, ExitCode } from '../errors.js';
+import { DEFAULT_PERSONAS, RUN_MODULES, describeBreakdown, personaCount } from '../runDefaults.js';
+import { displayLocalBrief, loadLocalBrief, localBriefFile, saveLocalBrief, splitLocalFields } from '../briefLocal.js';
 
 /** The goals the server's expectations-brief schema accepts, in its own order. */
 export const GOALS = Object.freeze([
@@ -19,7 +21,6 @@ export const GOALS = Object.freeze([
   'performance'
 ]);
 
-const DEFAULT_MODULES = ['game_profile', 'persona_playtest'];
 
 /**
  * The four things a quick brief needs, which are exactly the four the server
@@ -79,6 +80,13 @@ function showBrief(brief, rendered) {
   ui.info(rendered || '');
 }
 
+/** Print the fields kept on this machine, the password masked. */
+function showLocalBrief(local, repoRoot) {
+  ui.blank();
+  ui.info(`On this machine only (${localBriefFile({ repoRoot })}):`);
+  ui.info(JSON.stringify(local, null, 2));
+}
+
 /**
  * A question asker over a pair of streams.
  *
@@ -212,13 +220,21 @@ async function editBrief(context, flags, deps) {
   }
 
   if (flags.show) {
+    const local = displayLocalBrief(await loadLocalBrief({ repoRoot: flags.repoRoot }));
+    const hasLocal = Object.keys(local).length > 0;
     if (!current.brief) {
-      if (flags.json) ui.json({ brief: null });
-      else ui.info('No brief yet. Run brief with no flags to write one.');
+      if (flags.json) ui.json({ brief: null, local });
+      else {
+        ui.info('No brief yet. Run brief with no flags to write one.');
+        if (hasLocal) showLocalBrief(local, flags.repoRoot);
+      }
       return ExitCode.OK;
     }
-    if (flags.json) ui.json(current);
-    else showBrief(current.brief, current.rendered);
+    if (flags.json) ui.json({ ...current, local });
+    else {
+      showBrief(current.brief, current.rendered);
+      if (hasLocal) showLocalBrief(local, flags.repoRoot);
+    }
     return ExitCode.OK;
   }
 
@@ -226,12 +242,22 @@ async function editBrief(context, flags, deps) {
   const parentVersion = current.brief ? current.brief.version : null;
 
   let fields;
+  let localSaved = [];
   if (flags.from) {
     const loaded = await readJson(flags.from, null);
     if (!loaded || typeof loaded !== 'object') {
       throw new CliError(`${flags.from} does not contain a brief fields object.`);
     }
     fields = loaded.fields && typeof loaded.fields === 'object' ? loaded.fields : loaded;
+    // expected_noise and test_account stay on this machine: the server's
+    // brief schema refuses keys it does not list, and a password has no place
+    // in a record the studio shares.
+    const split = splitLocalFields(fields);
+    fields = split.server;
+    if (Object.keys(split.local).length > 0) {
+      await saveLocalBrief(split.local, { repoRoot: flags.repoRoot });
+      localSaved = Object.keys(split.local);
+    }
   } else {
     fields = await askQuickBrief(existingFields, deps);
   }
@@ -260,8 +286,13 @@ async function editBrief(context, flags, deps) {
     // A refused check does not undo a saved brief, and the brief is the point.
   }
 
-  const estimateModules = flags.modules || (context.config && context.config.modules) || DEFAULT_MODULES;
-  const estimatePersonas = flags.personas || (context.config && context.config.personas) || [];
+  // The run `run` would start: its modules and its personas (the flag, the
+  // repo config, else the default one). Before 0.3.2 this priced a game
+  // profile with no personas and quoted $4.00 for a job nobody was about to
+  // start.
+  const estimateModules = flags.modules || (context.config && context.config.modules) || [...RUN_MODULES];
+  const configuredPersonas = flags.personas || (context.config && Array.isArray(context.config.personas) && context.config.personas.length > 0 ? context.config.personas : null);
+  const estimatePersonas = estimateModules.includes('persona_playtest') ? (configuredPersonas || [...DEFAULT_PERSONAS]) : (configuredPersonas || []);
   let estimate = null;
   try {
     estimate = await api.brief.estimate(gameId, { modules: estimateModules, personas: estimatePersonas });
@@ -270,11 +301,14 @@ async function editBrief(context, flags, deps) {
   }
 
   if (flags.json) {
-    ui.json({ ...saved, estimate });
+    ui.json({ ...saved, estimate, local_saved: localSaved });
     return ExitCode.OK;
   }
 
   ui.ok(`Saved brief version ${saved.brief.version} (${saved.brief.status}).`);
+  if (localSaved.length > 0) {
+    ui.info(`Kept ${localSaved.join(' and ')} in ${localBriefFile({ repoRoot: flags.repoRoot })}, on this machine only: the server's brief does not store them.`);
+  }
   const after = saved.brief.completeness || completenessFor(saved.brief.fields);
   if (!after.complete) {
     ui.warn(`Still missing: ${after.missing.join(', ')}`);
@@ -283,7 +317,12 @@ async function editBrief(context, flags, deps) {
 
   if (estimate) {
     ui.blank();
-    ui.info(`A ${estimateModules.join(' plus ')} job would cost ${ui.money(estimate.estimate_cents)}.`);
+    const units = describeBreakdown(estimate.breakdown, ui.money);
+    const what = estimateModules.includes('persona_playtest')
+      ? `A run of ${personaCount(estimatePersonas.length)} (${estimatePersonas.join(', ')})${estimateModules.includes('game_profile') ? ' with a game profile' : ''}`
+      : `A ${estimateModules.join(' plus ')} job`;
+    ui.info(`${what} would cost ${ui.money(estimate.estimate_cents)}${units ? `: ${units}` : ''}.`);
+    if (!estimateModules.includes('game_profile')) ui.info('A game profile ("ravensight-playtest profile") is a separate job with its own price.');
     if (estimate.wall_warning) ui.warn(estimate.wall_warning);
     ui.table(estimate.breakdown, [
       { key: 'unit', label: 'UNIT' },

package/src/commands/check.js

@@ -11,8 +11,10 @@ import { CLI_VERSION, compareVersions } from '../version.js';
 import { ui } from '../ui/index.js';
 import { ExitCode } from '../errors.js';
 import { completenessFor } from './brief.js';
+import { RUN_MODULES, defaultPersonasFor, describeBreakdown, personaCount, unknownPersonaMessage, unknownPersonas } from '../runDefaults.js';
 import { WEBDRIVER_NAMES } from '../run/drivers/webdriver.js';
 import { inspectNativeBuild, probeAutomation, platformWords } from '../run/drivers/webdriver-probe.js';
+import { CHECK_PLAYTEST_IDENTITY, DEFAULT_VIEWPORT, WEB_OBSERVATION_MAX_CHARS, injectPlaytestIdentity, measureSnapshot, readSnapshot } from '../run/drivers/web.js';
 import path from 'node:path';
 
 export const NODE_MIN_MAJOR = 22;
@@ -64,21 +66,109 @@ export function browserSeverity(flags, config) {
   return config.driver === 'playwright_web' ? 'warn' : null;
 }
 
+/** How long `check` waits for a web build's first screen before it warns instead. */
+export const FIRST_SCREEN_TIMEOUT_MS = 20000;
+
+/** How long `check` waits for a first screen's network to go quiet, which a game with a socket never does. */
+export const FIRST_SCREEN_SETTLE_MS = 3000;
+
+/**
+ * A list with this many look-alike items or more on the first screen is
+ * worth a long run: the persona sees two and a count and has to search or
+ * scroll its way to the one it wants, or, when the items share a name and the
+ * page is under the cap, reads all of them on every step.
+ */
+export const LONG_LIST_ITEMS = 50;
+
+/** `18,400`. */
+const count = value => Number(value).toLocaleString('en-US');
+
+/**
+ * Load the first screen of a web build in an already launched browser and
+ * measure it the way a persona's observation would see it.
+ *
+ * @param {any} browser
+ * @param {string} url
+ * @param {{timeoutMs?: number}} [options]
+ * @returns {Promise<{ok: true, aria: boolean, fullChars: number, shownChars: number, longestRun: number}|{ok: false, detail: string}>}
+ */
+export async function measureFirstScreen(browser, url, { timeoutMs = FIRST_SCREEN_TIMEOUT_MS } = {}) {
+  let page = null;
+  try {
+    if (!browser || typeof browser.newPage !== 'function') throw new Error('this Playwright cannot open a page');
+    page = await browser.newPage({ viewport: DEFAULT_VIEWPORT });
+    // Marked as a playtest before any of the game's scripts run, so a build
+    // with the Ravensight web SDK never records this load as a real player.
+    // A Playwright that cannot mark the page does not load it at all.
+    if (typeof page.addInitScript !== 'function') throw new Error('this Playwright cannot mark the page as a check, so it was not loaded');
+    await page.addInitScript(injectPlaytestIdentity, { ...CHECK_PLAYTEST_IDENTITY });
+    await page.goto(url, { waitUntil: 'load', timeout: timeoutMs });
+    if (typeof page.waitForLoadState === 'function') {
+      try {
+        await page.waitForLoadState('networkidle', { timeout: FIRST_SCREEN_SETTLE_MS });
+      } catch {
+        // A page that keeps a connection open is measured as it stands.
+      }
+    }
+    const snap = await readSnapshot(page);
+    return { ok: true, ...measureSnapshot(snap, { viewport: DEFAULT_VIEWPORT }) };
+  } catch (error) {
+    return { ok: false, detail: String(error && error.message ? error.message : error).split('\n')[0] };
+  } finally {
+    if (page && typeof page.close === 'function') {
+      try {
+        await page.close();
+      } catch {
+        // The browser closes it with everything else.
+      }
+    }
+  }
+}
+
+/**
+ * Why a measured first screen is worth a long run, or an empty list when it
+ * is not: the whole compacted text over the observation cap, or a very long
+ * list of look-alike items.
+ *
+ * @param {{fullChars: number, longestRun: number}} measure
+ * @returns {string[]}
+ */
+export function heavyReasons(measure) {
+  const reasons = [];
+  if (measure.fullChars > WEB_OBSERVATION_MAX_CHARS) {
+    const ratio = measure.fullChars / WEB_OBSERVATION_MAX_CHARS;
+    reasons.push(`first screen is ${count(measure.fullChars)} characters, about ${ratio < 10 ? ratio.toFixed(1) : Math.round(ratio)}x the ${count(WEB_OBSERVATION_MAX_CHARS)} a persona reads per step`);
+  }
+  if (measure.longestRun >= LONG_LIST_ITEMS) {
+    reasons.push(measure.longestRunCollapsed === false
+      ? `first screen has a list of ${count(measure.longestRun)} look-alike items, which a persona sees in full on every step`
+      : `first screen has a list of ${count(measure.longestRun)} look-alike items, which a persona sees as two and a count`);
+  }
+  return reasons;
+}
+
 /**
  * Import Playwright, launch headless Chromium, close it. The same three steps
  * a web run starts with, so a pass here means the run will get a browser.
  *
+ * With a `url`, the browser also loads that first screen and measures it
+ * (see {@link measureFirstScreen}); a page that does not load is reported
+ * in `firstScreen`, never as a failed browser.
+ *
  * @param {(specifier: string) => Promise<any>} [importer] test seam
- * @returns {Promise<{ok: boolean, detail: string}>}
+ * @param {{url?: string|null, timeoutMs?: number}} [options]
+ * @returns {Promise<{ok: boolean, detail: string, firstScreen?: Object}>}
  */
-export async function probeBrowser(importer) {
+export async function probeBrowser(importer, { url = null, timeoutMs } = {}) {
   const load = importer || (specifier => import(specifier));
   let browser = null;
   try {
     const playwright = await load('playwright');
     browser = await playwright.chromium.launch({ headless: true });
     const version = typeof browser.version === 'function' ? browser.version() : '';
-    return { ok: true, detail: `chromium ${version}`.trim() + ' launched headless' };
+    const detail = `chromium ${version}`.trim() + ' launched headless';
+    if (!url) return { ok: true, detail };
+    return { ok: true, detail, firstScreen: await measureFirstScreen(browser, url, { timeoutMs }) };
   } catch (error) {
     return { ok: false, detail: String(error && error.message ? error.message : error).split('\n')[0] };
   } finally {
@@ -450,42 +540,17 @@ export async function runChecks(flags = {}, deps = {}) {
 
   /* -------------------------------------------------- balance and pack */
 
+  /** The standard estimate and its request, so a heavy first screen can quote the long price beside it. */
+  let priced = null;
   if (gameId && whoami && inScope) {
-    const modules = flags.modules || (config && config.modules) || ['game_profile', 'persona_playtest'];
-    const personas = flags.personas || (config && config.personas) || [];
-    try {
-      const estimate = await authed.jobs.estimate(gameId, { modules, personas });
-      if (estimate.balance_cents === null || estimate.balance_cents === undefined) {
-        rows.push(row(
-          'balance',
-          'warn',
-          `estimate ${ui.money(estimate.estimate_cents)}, balance hidden by your role`,
-          'ask an owner or admin to check the balance'
-        ));
-      } else {
-        rows.push(row(
-          'balance',
-          estimate.ok ? 'pass' : 'fail',
-          `estimate ${ui.money(estimate.estimate_cents)}, available ${ui.money(estimate.balance_cents)}`,
-          estimate.ok ? null : `top up at ${estimate.topup_url}`
-        ));
-      }
-      // Not a failure and not hidden by role: a job this size is still
-      // allowed, it may just outrun its wall clock, which is worth seeing
-      // here rather than only after `run` has already asked for a price.
-      if (estimate.wall_warning) {
-        rows.push(row('persona wall clock', 'warn', estimate.wall_warning));
-      }
-    } catch (error) {
-      rows.push(row(
-        'balance',
-        'warn',
-        error instanceof ApiError ? error.message : String(error && error.message)
-      ));
-    }
-
+    // What `run` would price: its modules, and with no personas named (by the
+    // flag or the repo config) the default persona set. Before 0.3.2 the
+    // persona module priced no persona at all.
+    const modules = flags.modules || (config && config.modules) || [...RUN_MODULES];
+    const named = flags.personas || (config && Array.isArray(config.personas) && config.personas.length > 0 ? config.personas : null);
+    let pack = null;
     try {
-      const pack = await packs.get({ api: authed, gameId, modules });
+      pack = await packs.get({ api: authed, gameId, modules });
       const manifest = (await authed.packs.manifest()).body;
       const verified = packs.verifyAgainstManifest(manifest, pack.bundle);
       rows.push(row(
@@ -504,6 +569,48 @@ export async function runChecks(flags = {}, deps = {}) {
         'the CLI cannot run without personas and schemas'
       ));
     }
+    const available = pack && pack.bundle && Array.isArray(pack.bundle.personas) ? pack.bundle.personas : null;
+    const personas = modules.includes('persona_playtest') ? (named || defaultPersonasFor(available)) : (named || []);
+    const unknown = available ? unknownPersonas(personas, available) : [];
+    if (unknown.length > 0) {
+      rows.push(row('personas', 'fail', unknownPersonaMessage(unknown, available), 'ravensight-playtest personas lists the valid slugs'));
+    }
+
+    if (unknown.length === 0) {
+      try {
+        const estimate = await authed.jobs.estimate(gameId, { modules, personas });
+        priced = { estimate, modules, personas };
+        const units = describeBreakdown(estimate.breakdown, ui.money);
+        const summary = `estimate ${ui.money(estimate.estimate_cents)}${modules.includes('persona_playtest') ? ` for ${personaCount(personas.length)} (${personas.join(', ')})` : ''}${units ? `: ${units}` : ''}`;
+        if (estimate.balance_cents === null || estimate.balance_cents === undefined) {
+          rows.push(row(
+            'balance',
+            'warn',
+            `${summary}; balance hidden by your role`,
+            'ask an owner or admin to check the balance'
+          ));
+        } else {
+          rows.push(row(
+            'balance',
+            estimate.ok ? 'pass' : 'fail',
+            `${summary}; available ${ui.money(estimate.balance_cents)}`,
+            estimate.ok ? null : `top up at ${estimate.topup_url}`
+          ));
+        }
+        // Not a failure and not hidden by role: a job this size is still
+        // allowed, it may just outrun its wall clock, which is worth seeing
+        // here rather than only after `run` has already asked for a price.
+        if (estimate.wall_warning) {
+          rows.push(row('persona wall clock', 'warn', estimate.wall_warning));
+        }
+      } catch (error) {
+        rows.push(row(
+          'balance',
+          'warn',
+          error instanceof ApiError ? error.message : String(error && error.message)
+        ));
+      }
+    }
   }
 
   /* --------------------------------------------------------- the machine */
@@ -533,13 +640,17 @@ export async function runChecks(flags = {}, deps = {}) {
 
   const browserNeed = browserSeverity(flags, await configForBrowser(flags));
   if (browserNeed) {
-    const probe = await probeBrowser(deps.importer);
+    const firstScreenUrl = plan.driverName === 'playwright_web' && /^https?:\/\//i.test(String(plan.target || '')) ? plan.target : null;
+    const probe = await probeBrowser(deps.importer, { url: firstScreenUrl, timeoutMs: deps.firstScreenTimeoutMs });
     rows.push(row(
       'browser',
       probe.ok ? 'pass' : browserNeed,
       probe.detail,
       probe.ok ? null : BROWSER_FIX
     ));
+    if (probe.firstScreen) {
+      rows.push(await firstScreenRow(probe.firstScreen, firstScreenUrl, { authed, gameId, priced }));
+    }
   }
 
   const godot = await (deps.inspectGodot || inspectGodot)(
@@ -587,6 +698,44 @@ export async function runChecks(flags = {}, deps = {}) {
   return { rows, ok: rows.every(entry => entry.status !== 'fail'), ...facts };
 }
 
+/**
+ * The `first screen` row: how heavy the build's first screen is for a
+ * persona, and a suggestion to use `--long` when it is heavy. Both prices are
+ * read from the server's free estimate; nothing here is charged. A first
+ * screen that did not load is a warning, never a failure: `run` has its own
+ * health check, and the server may simply not be started yet.
+ *
+ * @param {Object} measure from {@link measureFirstScreen}
+ * @param {string} url
+ * @param {{authed: Object|null, gameId: string|null, priced: Object|null}} context
+ * @returns {Promise<Object>} a row
+ */
+export async function firstScreenRow(measure, url, { authed, gameId, priced }) {
+  if (!measure.ok) {
+    return row('first screen', 'warn', `could not load ${url} to measure it: ${measure.detail}`, 'start the build, then run check again to see how heavy its first screen is');
+  }
+  const reasons = heavyReasons(measure);
+  if (reasons.length === 0) {
+    return row('first screen', 'pass', `${count(measure.fullChars)} characters, within the ${count(WEB_OBSERVATION_MAX_CHARS)} a persona reads per step`);
+  }
+  let prices = 'a long run costs twice a standard run; run shows the price before any charge';
+  if (priced && priced.modules.includes('persona_playtest') && authed && gameId) {
+    try {
+      // A read like the standard estimate above: it prices, it charges nothing.
+      const long = await authed.jobs.estimate(gameId, { modules: priced.modules, personas: priced.personas, runLength: 'long' });
+      prices = `long ${ui.money(long.estimate_cents)} against standard ${ui.money(priced.estimate.estimate_cents)}`;
+    } catch {
+      // The suggestion stands without the figure.
+    }
+  }
+  return row(
+    'first screen',
+    'warn',
+    `${reasons.join('; ')}. Consider --long: twice the actions, model budget and wall time per persona (${prices})`,
+    'ravensight-playtest run --long'
+  );
+}
+
 /**
  * `ravensight-playtest check`
  * @param {Object} [flags]

package/src/commands/fix.js

@@ -15,7 +15,8 @@ import { createRepoTools, PROFILE_TOOLS } from '../run/repoTools.js';
 import { assertNoSecrets } from '../run/secretScan.js';
 import * as stateFile from '../run/state.js';
 import { createUsageLedger, writeUsageFile } from '../run/usage.js';
-import { createInterruptHandler, deliver, driverOptions, exitCodeFor, explainRegisterRefusal, formatCents, resolveSetup, resolveTarget, skillFor } from './run.js';
+import { createInterruptHandler, deliver, driverOptions, exitCodeFor, explainRegisterRefusal, formatCents, resolveSetup, resolveTarget, skillFor, usableLocalBrief } from './run.js';
+import { loadLocalBrief } from '../briefLocal.js';
 
 /**
  * `ravensight-playtest fix <target>`: take one finding, change the code on a
@@ -784,6 +785,15 @@ export async function runVerify({
   });
   heartbeat.start();
 
+  // The verify replay plays like `run` does: with the brief's local fields,
+  // so it can sign in with the test account and knows the expected noise.
+  let localBrief = {};
+  try {
+    localBrief = usableLocalBrief(await loadLocalBrief({ repoRoot }));
+  } catch (error) {
+    log(`verify: ${String(error && error.message)} The replay goes ahead without expected_noise and test_account.`);
+  }
+
   let outcome;
   try {
     outcome = await runPersona({
@@ -801,6 +811,7 @@ export async function runVerify({
       skill: skillFor(pack, 'persona_playtest'),
       // The brief fetched above, as `run` does: the pack does not always carry one.
       brief: verifyBrief(brief || pack.brief || null, finding),
+      localBrief,
       intentNotes: pack.intent_notes || [],
       schemas: pack.schemas || [],
       maxActions,

package/src/commands/init.js

@@ -9,9 +9,14 @@ import { CliError, ExitCode } from '../errors.js';
 
 const GITIGNORE_LINE = '.ravensight/jobs/';
 
+/** The local brief holds a test account password, so it is never committed. */
+const LOCAL_BRIEF_LINE = '.ravensight/brief.local.json';
+
+const GITIGNORE_LINES = [GITIGNORE_LINE, LOCAL_BRIEF_LINE];
+
 /**
- * Add `.ravensight/jobs/` to the repo's .gitignore if it has one and does not
- * already ignore it.
+ * Add `.ravensight/jobs/` and `.ravensight/brief.local.json` to the repo's
+ * .gitignore if it has one and does not already ignore them.
  *
  * Job directories hold screenshots and a video, which nobody wants in their
  * history. Only appended when a .gitignore already exists: creating one in
@@ -29,8 +34,10 @@ export async function ensureGitignore(repoRoot) {
     if (error.code === 'ENOENT') return 'absent';
     throw error;
   }
-  if (text.split('\n').some(line => line.trim() === GITIGNORE_LINE)) return 'present';
-  await appendFile(file, `${text.endsWith('\n') ? '' : '\n'}${GITIGNORE_LINE}\n`);
+  const present = new Set(text.split('\n').map(line => line.trim()));
+  const missing = GITIGNORE_LINES.filter(line => !present.has(line));
+  if (missing.length === 0) return 'present';
+  await appendFile(file, `${text.endsWith('\n') || text === '' ? '' : '\n'}${missing.join('\n')}\n`);
   return 'added';
 }
 
@@ -137,8 +144,8 @@ async function linkRepo(context, flags, repoRoot, choose) {
   const name = (games.find(game => game.gameId === gameId) || {}).name || gameId;
   ui.ok(`Linked this repo to ${name} (${gameId}).`);
   ui.info(`Wrote ${paths.configFile({ repoRoot })}`);
-  if (gitignore === 'added') ui.info(`Added ${GITIGNORE_LINE} to .gitignore`);
-  if (gitignore === 'absent') ui.warn(`No .gitignore here. Add ${GITIGNORE_LINE} to whatever ignores build output.`);
+  if (gitignore === 'added') ui.info(`Added ${GITIGNORE_LINES.join(' and ')} to .gitignore`);
+  if (gitignore === 'absent') ui.warn(`No .gitignore here. Add ${GITIGNORE_LINES.join(' and ')} to whatever ignores build output.`);
   ui.blank();
   ui.info('Next: ravensight-playtest brief');
   return ExitCode.OK;

package/src/commands/personas.js

@@ -0,0 +1,50 @@
+import { createContext } from '../api/index.js';
+import { resolveGameId } from '../config.js';
+import { withAuthHandling } from '../auth/session.js';
+import { packs } from '../packs/index.js';
+import { ui } from '../ui/index.js';
+import { ExitCode } from '../errors.js';
+import { DEFAULT_PERSONAS, defaultPersonasFor } from '../runDefaults.js';
+
+/**
+ * `ravensight-playtest personas`
+ *
+ * The persona slugs `--personas` accepts, from the content pack this game
+ * gets, with each one's patience (its action budget) and play style. A free
+ * read: nothing is reserved.
+ *
+ * @param {Object} [flags]
+ * @param {Object} [deps] test seam: context, packs
+ * @returns {Promise<number>}
+ */
+export async function personas(flags = {}, deps = {}) {
+  const context = deps.context || await createContext({ apiUrl: flags.apiUrl, repoRoot: flags.repoRoot, requireAuth: true });
+  return withAuthHandling(context, async () => {
+    const gameId = resolveGameId(flags, context.config);
+    const answer = await (deps.packs || packs).get({ api: context.api, gameId, modules: ['persona_playtest'] });
+    const bundle = answer && answer.bundle ? answer.bundle : answer;
+    const list = (bundle && Array.isArray(bundle.personas) ? bundle.personas : []).map(persona => ({
+      slug: persona.slug,
+      name: persona.name || persona.slug,
+      patience_actions: Number(persona.patience_actions) || null,
+      playstyle: persona.playstyle || null,
+      skill_level: persona.skill_level || null
+    }));
+    const defaults = defaultPersonasFor(list);
+    if (flags.json) {
+      ui.json({ personas: list, default: defaults });
+      return ExitCode.OK;
+    }
+    ui.table(list.map(entry => ({ ...entry, slug: defaults.includes(entry.slug) ? `${entry.slug} (default)` : entry.slug, patience_actions: entry.patience_actions === null ? '' : String(entry.patience_actions) })), [
+      { key: 'slug', label: 'SLUG' },
+      { key: 'name', label: 'NAME' },
+      { key: 'patience_actions', label: 'ACTIONS', align: 'right' },
+      { key: 'playstyle', label: 'PLAYSTYLE' }
+    ]);
+    ui.blank();
+    ui.info(`A run with no --personas plays ${defaults.join(', ') || DEFAULT_PERSONAS.join(', ')}. Pick others with --personas <slug,slug>; each persona is one persona run.`);
+    return ExitCode.OK;
+  });
+}
+
+export default personas;