ravensight-playtest 0.1.0

package/src/states.js

@@ -0,0 +1,104 @@
+/**
+ * The job and run state machines, the module list and the driver list, copied
+ * from the server's `src/models/PlaytestJob.js` and `src/models/PlaytestRun.js`.
+ *
+ * The server is the authority and refuses a state it does not know, so these
+ * lists exist so the CLI can refuse locally (and so the runner can tell a
+ * terminal run from a resumable one without a round trip). If the two ever
+ * disagree, the server wins and this file is the one to fix.
+ *
+ * The transition table is data on both sides: the server does not enforce it
+ * either, it conditionally writes the state the caller read. It is here so a
+ * runner can avoid asking for a transition it knows is nonsense.
+ */
+
+export const MODULES = Object.freeze([
+  'game_profile',
+  'persona_playtest',
+  'aggregate_report',
+  'logic_twin',
+  'balance_sim',
+  'level_inspect'
+]);
+
+export const DRIVERS = Object.freeze([
+  'playwright_web',
+  'godot_driver',
+  'cli_stdio',
+  'unity_driver',
+  'unreal_driver'
+]);
+
+export const JOB_STATES = Object.freeze([
+  'registered',
+  'running',
+  'aggregating',
+  'uploading',
+  'succeeded',
+  'failed',
+  'canceled',
+  'budget_exceeded',
+  'interrupted',
+  'stalled'
+]);
+
+/**
+ * A job only ever reaches one of these through `/finish`, `/cancel` or
+ * `DELETE`: `PATCH /jobs/:jobId` refuses them with 409, because the terminal
+ * state and the refund are one decision and only the server's settlement writes
+ * either.
+ */
+export const JOB_TERMINAL_STATES = Object.freeze([
+  'succeeded',
+  'failed',
+  'canceled',
+  'budget_exceeded',
+  'stalled'
+]);
+
+export const RUN_STATES = Object.freeze([
+  'queued',
+  'launching',
+  'playing',
+  'reporting',
+  'uploading',
+  'succeeded',
+  'failed',
+  'canceled',
+  'budget_exceeded',
+  'skipped',
+  'interrupted'
+]);
+
+export const RUN_TERMINAL_STATES = Object.freeze([
+  'succeeded',
+  'failed',
+  'canceled',
+  'budget_exceeded',
+  'skipped'
+]);
+
+/**
+ * `interrupted` is deliberately not terminal: it is what the server's
+ * housekeeping sweep marks a run whose heartbeat stopped, and the whole point
+ * of the state is that `resume` can take it back to `launching`.
+ */
+export const RUN_TRANSITIONS = Object.freeze({
+  queued: ['launching', 'canceled', 'skipped', 'failed', 'interrupted'],
+  launching: ['playing', 'failed', 'canceled', 'interrupted'],
+  playing: ['reporting', 'failed', 'canceled', 'budget_exceeded', 'interrupted'],
+  reporting: ['uploading', 'failed', 'interrupted'],
+  uploading: ['succeeded', 'failed', 'interrupted'],
+  interrupted: ['launching', 'playing', 'reporting', 'uploading', 'failed', 'canceled'],
+  succeeded: [],
+  failed: [],
+  canceled: [],
+  budget_exceeded: [],
+  skipped: []
+});
+
+export const isRunTerminal = state => RUN_TERMINAL_STATES.includes(state);
+export const isJobTerminal = state => JOB_TERMINAL_STATES.includes(state);
+
+/** Whether the server's transition table allows this move. */
+export const canTransitionRun = (from, to) => (RUN_TRANSITIONS[from] || []).includes(to);

package/src/ui/index.js

@@ -0,0 +1,195 @@
+import { createInterface } from 'node:readline/promises';
+import { stableStringify } from '../fsutil.js';
+
+/**
+ * Terminal output, in one place.
+ *
+ * Two rules the rest of the CLI relies on. Nothing here writes to stdout in
+ * quiet mode except `ui.json`, so `--json` output is parseable by a CI step
+ * that pipes it. And nothing here uses an em dash or an en dash, because this
+ * is every string a customer reads.
+ */
+
+let quiet = false;
+let stream = process.stdout;
+let errStream = process.stderr;
+
+export const SYMBOLS = Object.freeze({ ok: 'ok', warn: 'warn', fail: 'fail', info: '..' });
+
+export function setQuiet(value) {
+  quiet = Boolean(value);
+}
+
+export function isQuiet() {
+  return quiet || process.env.RAVENSIGHT_JSON === '1';
+}
+
+/** Test seam: capture output without spawning a process. */
+export function setStreams({ out, err } = {}) {
+  stream = out || process.stdout;
+  errStream = err || process.stderr;
+}
+
+function write(text) {
+  if (isQuiet()) return;
+  stream.write(`${text}\n`);
+}
+
+export function info(text) {
+  write(text);
+}
+
+export function ok(text) {
+  write(`${SYMBOLS.ok}   ${text}`);
+}
+
+export function warn(text) {
+  write(`${SYMBOLS.warn} ${text}`);
+}
+
+/** Errors go to stderr and are printed even in quiet mode: a silent failure is a bug. */
+export function error(text) {
+  errStream.write(`${SYMBOLS.fail} ${text}\n`);
+}
+
+export function blank() {
+  write('');
+}
+
+/** Machine readable output. The one thing quiet mode does not suppress. */
+export function json(value) {
+  stream.write(`${JSON.stringify(value, null, 2)}\n`);
+}
+
+/** Stable JSON, for anything that gets hashed or compared between runs. */
+export const stable = stableStringify;
+
+/**
+ * An aligned table with no borders, which is what fits in a terminal that may
+ * be 80 columns wide.
+ * @param {Array<Object>} rows
+ * @param {Array<{key: string, label: string, align?: 'left'|'right'}>} columns
+ */
+export function table(rows, columns) {
+  if (isQuiet()) return;
+  const cells = rows.map(row => columns.map(column => {
+    const value = row[column.key];
+    return value === undefined || value === null ? '' : String(value);
+  }));
+  const widths = columns.map((column, index) => Math.max(
+    column.label.length,
+    ...cells.map(row => row[index].length),
+    0
+  ));
+  const pad = (text, width, align) => (align === 'right' ? text.padStart(width) : text.padEnd(width));
+
+  write(columns.map((column, i) => pad(column.label, widths[i], column.align)).join('  '));
+  write(widths.map(width => '-'.repeat(width)).join('  '));
+  for (const row of cells) {
+    write(row.map((text, i) => pad(text, widths[i], columns[i].align)).join('  '));
+  }
+}
+
+/**
+ * A spinner that degrades honestly. On a TTY it rewrites one line; anywhere
+ * else (a CI log, a pipe) it prints one line per update, because carriage
+ * returns in a log file are noise and a progress animation nobody sees is
+ * worse than a timestamped line someone can read later.
+ * @param {string} label
+ */
+export function spinner(label) {
+  const frames = ['.', '..', '...'];
+  const interactive = Boolean(stream.isTTY) && !isQuiet();
+  let text = label;
+  let frame = 0;
+  let timer = null;
+
+  const paint = () => {
+    frame = (frame + 1) % frames.length;
+    stream.write(`\r${text} ${frames[frame]}   `);
+  };
+
+  if (interactive) {
+    timer = setInterval(paint, 300);
+    if (typeof timer.unref === 'function') timer.unref();
+    paint();
+  } else {
+    write(text);
+  }
+
+  return {
+    update(next) {
+      text = next;
+      if (!interactive) write(next);
+    },
+    stop(final) {
+      if (timer) clearInterval(timer);
+      if (interactive) stream.write('\r'.padEnd(text.length + 8, ' '));
+      if (interactive) stream.write('\r');
+      if (final) write(final);
+    }
+  };
+}
+
+/**
+ * Ask a yes or no question.
+ *
+ * `--yes` skips it, and so does a non interactive stdin: a prompt nobody can
+ * answer would hang a CI job forever, so the absence of a TTY is treated as a
+ * refusal rather than as an assumed yes. That is the safe direction for a
+ * question that is usually "shall I spend your money".
+ *
+ * @param {string} question
+ * @param {{yes?: boolean, input?: object, output?: object}} [options]
+ * @returns {Promise<boolean>}
+ */
+export async function confirm(question, options = {}) {
+  if (options.yes) return true;
+  const input = options.input || process.stdin;
+  if (!input.isTTY && !options.input) return false;
+
+  const rl = createInterface({ input, output: options.output || stream });
+  try {
+    const answer = await rl.question(`${question} [y/N] `);
+    return /^y(es)?$/i.test(answer.trim());
+  } finally {
+    rl.close();
+  }
+}
+
+/** Cents as dollars, the one place that formatting exists. */
+export function money(cents) {
+  if (cents === null || cents === undefined) return 'unknown';
+  return `$${(cents / 100).toFixed(2)}`;
+}
+
+/** Bytes as a short human string. */
+export function bytes(value) {
+  const units = ['B', 'KB', 'MB', 'GB'];
+  let n = Number(value) || 0;
+  let unit = 0;
+  while (n >= 1024 && unit < units.length - 1) {
+    n /= 1024;
+    unit += 1;
+  }
+  return `${unit === 0 ? n : n.toFixed(1)} ${units[unit]}`;
+}
+
+export const ui = {
+  SYMBOLS,
+  setQuiet,
+  isQuiet,
+  setStreams,
+  info,
+  ok,
+  warn,
+  error,
+  blank,
+  json,
+  stable,
+  table,
+  spinner,
+  confirm,
+  money,
+  bytes
+};

package/src/upload/allowlist.js

@@ -0,0 +1,116 @@
+/**
+ * The upload path allowlist, compiled into the CLI.
+ *
+ * This is a copy of the server's `src/playtest/limits.js` ALLOWED_PATHS,
+ * deliberately. The server is the authority and refuses anything it does not
+ * recognize, so this copy exists only so the CLI can say "that file is not
+ * uploadable" locally instead of sending a request that comes back 400. The
+ * two must agree; if they ever disagree, the server wins and this file is the
+ * one to fix.
+ *
+ * Source code is not on the list, at any path. A playtest uploads reports,
+ * screenshots and, opted in, a video and a transcript. Nothing else.
+ */
+
+/**
+ * Exported so `allowlist.pinned.test.js` can compare this list entry by entry
+ * with the server's own, which is what makes the paragraph above a checked
+ * claim rather than an aspiration.
+ */
+export const ALLOWED_PATHS = [
+  { pattern: /^report\.md$/, contentType: 'text/markdown' },
+  { pattern: /^report\.json$/, contentType: 'application/json' },
+  { pattern: /^aggregate-report\.md$/, contentType: 'text/markdown' },
+  { pattern: /^aggregate-report\.json$/, contentType: 'application/json' },
+  { pattern: /^capability-report\.json$/, contentType: 'application/json' },
+  { pattern: /^usage\.json$/, contentType: 'application/json' },
+  { pattern: /^job\.json$/, contentType: 'application/json' },
+  { pattern: /^screenshots\/.+\.png$/, contentType: 'image/png' },
+  { pattern: /^screenshots\/.+\.jpe?g$/, contentType: 'image/jpeg' },
+  { pattern: /^screenshots\/.+\.webp$/, contentType: 'image/webp' },
+  { pattern: /^changeset.*\.json$/, contentType: 'application/json' },
+  { pattern: /^job-review\.json$/, contentType: 'application/json' },
+  { pattern: /^expectations-brief\.json$/, contentType: 'application/json' },
+  { pattern: /^next-action-plan\.json$/, contentType: 'application/json' },
+  { pattern: /^session\.webm$/, contentType: 'video/webm', optIn: 'video' },
+  { pattern: /^session\.mp4$/, contentType: 'video/mp4', optIn: 'video' },
+  { pattern: /^transcript\.jsonl$/, contentType: 'application/x-ndjson', optIn: 'transcript' }
+];
+
+export const TRANSCRIPT_PATH = 'transcript.jsonl';
+export const VIDEO_PATHS = Object.freeze(['session.webm', 'session.mp4']);
+
+/**
+ * The three paths whose objects carry the `retention=90d` S3 tag, from W8's
+ * `RETENTION_TAGGED_PATHS`. The CLI never computes the tag value itself: the
+ * presign response hands back the exact string that was signed. This list is
+ * only used to explain, in `--dry-upload` output, which files expire.
+ */
+export const RETENTION_TAGGED_PATHS = Object.freeze([...VIDEO_PATHS, TRANSCRIPT_PATH]);
+
+/**
+ * The only three artifacts that belong to a job rather than to one of its runs,
+ * and so get keys with no `runs/<runId>` segment.
+ *
+ * The server's allowlist is one list for both levels, so it would happily
+ * presign `report.json` at the job root. Nothing writes one there, but the job
+ * directory also holds `state.json` and `upload-queue.jsonl`, and a future
+ * artifact dropped beside them would start being uploaded under a job key by
+ * accident. Naming the three keeps the job level upload deliberate.
+ */
+export const JOB_UPLOAD_PATHS = Object.freeze([
+  'capability-report.json',
+  'aggregate-report.md',
+  'aggregate-report.json'
+]);
+
+export const MAX_FILES_PER_RUN = 500;
+export const MAX_RUN_BYTES = 500 * 1024 * 1024;
+export const MAX_VIDEO_BYTES = 200 * 1024 * 1024;
+
+/**
+ * The content type for a run relative path, or null when the path is not
+ * uploadable at all.
+ *
+ * `optIn` entries answer null unless the matching flag is set, which is what
+ * makes video and transcript opt in rather than "uploaded unless you noticed".
+ *
+ * @param {string} relPath - forward slashes, relative to the run directory
+ * @param {{video?: boolean, transcript?: boolean}} [opts]
+ * @returns {string|null}
+ */
+export function contentTypeFor(relPath, opts = {}) {
+  for (const entry of ALLOWED_PATHS) {
+    if (!entry.pattern.test(relPath)) continue;
+    if (entry.optIn && !opts[entry.optIn]) return null;
+    return entry.contentType;
+  }
+  return null;
+}
+
+/**
+ * Whether a path is on the list at all, ignoring the opt in flags. Used to tell
+ * "you did not ask for the video" apart from "that file has no business here",
+ * which are different messages.
+ * @param {string} relPath
+ * @returns {boolean}
+ */
+export function isAllowedPath(relPath) {
+  return ALLOWED_PATHS.some(entry => entry.pattern.test(relPath));
+}
+
+/**
+ * Why a path is being skipped, in words a developer can act on.
+ * @param {string} relPath
+ * @param {{video?: boolean, transcript?: boolean}} opts
+ * @returns {string}
+ */
+export function skipReason(relPath, opts = {}) {
+  if (!isAllowedPath(relPath)) return 'not an uploadable path';
+  for (const entry of ALLOWED_PATHS) {
+    if (entry.pattern.test(relPath) && entry.optIn && !opts[entry.optIn]) {
+      return `${entry.optIn} upload not enabled`;
+    }
+  }
+  return 'skipped';
+}