ravensight-playtest 0.1.0

package/src/commands/upload.js

@@ -0,0 +1,137 @@
+import { readdir } from 'node:fs/promises';
+import { createContext } from '../api/index.js';
+import { resolveGameId } from '../config.js';
+import { withAuthHandling } from '../auth/session.js';
+import { paths } from '../paths.js';
+import { readState } from '../state/index.js';
+import { pending } from '../upload/queue.js';
+import { uploadRunDir } from '../upload/index.js';
+import { JOB_UPLOAD_PATHS } from '../upload/allowlist.js';
+import { ui } from '../ui/index.js';
+import { CliError, ExitCode } from '../errors.js';
+
+/**
+ * The run ids a job has directories for on disk. The runner names them after
+ * the server's own run ids, so these are what the presign route expects.
+ * @param {string} jobId
+ * @param {{repoRoot?: string}} options
+ * @returns {Promise<string[]>}
+ */
+export async function localRunIds(jobId, options = {}) {
+  const dir = `${paths.jobDir(jobId, options)}/runs`;
+  try {
+    const entries = await readdir(dir, { withFileTypes: true });
+    return entries.filter(entry => entry.isDirectory()).map(entry => entry.name).sort();
+  } catch (error) {
+    if (error.code === 'ENOENT') return [];
+    throw error;
+  }
+}
+
+/**
+ * `ravensight-playtest upload <jobId>`
+ *
+ * Drain whatever a crashed or offline run left behind: every run directory of a
+ * job, plus the job level artifacts (the capability report and the aggregate).
+ *
+ * Safe to run repeatedly. `uploadRunDir` skips anything the job's
+ * `upload-queue.jsonl` already records as uploaded at the same sha256, so this
+ * costs one presign request per directory with nothing new in it, and re-sends
+ * only a file that actually changed.
+ *
+ * This command does not call `complete` or `finish`: those are the runner's,
+ * because they carry the report and the terminal state. This is the bytes only.
+ *
+ * @param {string} jobId
+ * @param {Object} [flags]
+ * @param {Object} [deps]
+ * @returns {Promise<number>}
+ */
+export async function upload(jobId, flags = {}, deps = {}) {
+  if (!jobId) throw new CliError('Which job? ravensight-playtest upload <jobId>');
+
+  const context = deps.context || await createContext({
+    apiUrl: flags.apiUrl,
+    repoRoot: flags.repoRoot,
+    requireAuth: true
+  });
+  return withAuthHandling(context, () => drainJob(context, jobId, flags));
+}
+
+async function drainJob(context, jobId, flags) {
+  const repoRoot = context.repoRoot;
+  const state = await readState(jobId, { repoRoot });
+  const gameId = flags.game || (state && state.game_id) || resolveGameId(flags, context.config);
+
+  const uploadsConfig = (context.config && context.config.uploads) || {};
+  const includeVideo = flags.video === undefined ? Boolean(uploadsConfig.video) : Boolean(flags.video);
+  const includeTranscript = flags.transcript === undefined
+    ? Boolean(uploadsConfig.transcript)
+    : Boolean(flags.transcript);
+
+  const runIds = await localRunIds(jobId, { repoRoot });
+  const results = [];
+
+  for (const runId of runIds) {
+    const result = await uploadRunDir(paths.runDir(jobId, runId, { repoRoot }), {
+      api: context.api,
+      gameId,
+      jobId,
+      runId,
+      includeVideo,
+      includeTranscript,
+      dryRun: Boolean(flags.dryRun),
+      repoRoot,
+      onFile: flags.json ? undefined : file => ui.info(`  ${file.status}  ${runId}/${file.path} (${ui.bytes(file.size)})`)
+    });
+    results.push({ run_id: runId, ...result });
+  }
+
+  // The job level files sit in the job directory itself, one level above the
+  // run directories, and get keys without a `runs/<runId>` segment. Narrowed to
+  // the three artifacts that actually belong to a job, because that directory
+  // also holds state.json and upload-queue.jsonl and is where a future local
+  // file would land.
+  const jobLevel = await uploadRunDir(paths.jobDir(jobId, { repoRoot }), {
+    api: context.api,
+    gameId,
+    jobId,
+    runId: null,
+    includeVideo: false,
+    includeTranscript: false,
+    allowedPaths: JOB_UPLOAD_PATHS,
+    dryRun: Boolean(flags.dryRun),
+    repoRoot,
+    onFile: flags.json ? undefined : file => ui.info(`  ${file.status}  ${file.path} (${ui.bytes(file.size)})`)
+  });
+  results.push({ run_id: null, ...jobLevel });
+
+  const uploaded = results.reduce((sum, result) => sum + result.uploaded.length, 0);
+  const bytes = results.reduce((sum, result) => sum + result.bytes, 0);
+  const stillPending = await pending(jobId, { repoRoot });
+
+  if (flags.json) {
+    ui.json({ ok: stillPending.length === 0, job_id: jobId, results, pending: stillPending });
+    return ExitCode.OK;
+  }
+
+  ui.blank();
+  if (flags.dryRun) {
+    ui.info(`Would send ${uploaded} files, ${ui.bytes(bytes)}.`);
+  } else {
+    ui.ok(`Sent ${uploaded} files, ${ui.bytes(bytes)}.`);
+  }
+  const skipped = results.flatMap(result => result.skipped);
+  if (skipped.length > 0) {
+    ui.blank();
+    ui.info('Not sent:');
+    ui.table(skipped, [
+      { key: 'path', label: 'PATH' },
+      { key: 'reason', label: 'REASON' }
+    ]);
+  }
+  if (stillPending.length > 0) {
+    ui.warn(`${stillPending.length} files are still owed. Run upload again when you are online.`);
+  }
+  return ExitCode.OK;
+}

package/src/config.js

@@ -0,0 +1,100 @@
+import { paths } from './paths.js';
+import { readJson, writeJson } from './fsutil.js';
+import { CliError } from './errors.js';
+
+export const CONFIG_VERSION = 1;
+
+/**
+ * `<repo>/.ravensight/config.json`: the repo to game link, and the defaults a
+ * developer should not have to retype.
+ *
+ * JSON rather than the YAML spec 17 sketched, because it needs no dependency
+ * and the file is machine written far more often than it is hand edited.
+ *
+ * @typedef {Object} LocalConfig
+ * @property {number} config_version
+ * @property {string} game_id
+ * @property {string} [api_url] - recorded so a repo linked against one server
+ *   cannot silently be run against another
+ * @property {string} [driver] - playwright_web, godot_driver or cli_stdio
+ * @property {Object} [build] - `{ kind, ref }`
+ * @property {string[]} [personas]
+ * @property {Object} [uploads] - `{ video: boolean, transcript: boolean }`
+ * @property {number} [max_actions]
+ * @property {number} [concurrency]
+ */
+
+/** The shape a fresh `init` writes. */
+export function defaultConfig(gameId, extra = {}) {
+  return {
+    config_version: CONFIG_VERSION,
+    game_id: gameId,
+    driver: 'playwright_web',
+    build: { kind: '', ref: '' },
+    personas: [],
+    uploads: { video: false, transcript: false },
+    concurrency: 2,
+    ...extra
+  };
+}
+
+/**
+ * Read the repo's config, or null when this repo has never been linked.
+ * @param {{repoRoot?: string}} [options]
+ * @returns {Promise<LocalConfig|null>}
+ */
+export async function loadConfig(options = {}) {
+  const value = await readJson(paths.configFile(options), null);
+  if (value === null) return null;
+  if (typeof value !== 'object' || Array.isArray(value)) {
+    throw new CliError(`${paths.configFile(options)} is not a config object.`);
+  }
+  return value;
+}
+
+/**
+ * Read the config or refuse, with the message that says what to do about it.
+ * Every game scoped command starts here.
+ * @param {{repoRoot?: string}} [options]
+ * @returns {Promise<LocalConfig>}
+ */
+export async function requireConfig(options = {}) {
+  const config = await loadConfig(options);
+  if (!config || !config.game_id) {
+    throw new CliError(
+      'This directory is not linked to a Ravensight game.',
+      1,
+      { hint: 'Run ravensight-playtest init --game <gameId>.' }
+    );
+  }
+  return config;
+}
+
+/**
+ * Write the repo's config.
+ * @param {LocalConfig} config
+ * @param {{repoRoot?: string}} [options]
+ */
+export async function saveConfig(config, options = {}) {
+  await writeJson(paths.configFile(options), { config_version: CONFIG_VERSION, ...config });
+  return config;
+}
+
+/**
+ * The game id for a command: the `--game` flag when given, otherwise the
+ * config's. A flag that contradicts the config is honored, not refused, so a
+ * developer can run one job against another game without editing a file, but
+ * the config is never rewritten as a side effect of that.
+ * @param {{game?: string}} flags
+ * @param {LocalConfig|null} config
+ * @returns {string}
+ */
+export function resolveGameId(flags = {}, config = null) {
+  const fromFlag = flags.game || process.env.RAVENSIGHT_GAME_ID;
+  if (fromFlag) return fromFlag;
+  if (config && config.game_id) return config.game_id;
+  throw new CliError(
+    'No game id. Pass --game <gameId>, or run init first.',
+    1
+  );
+}

package/src/dashboard.js

@@ -0,0 +1,97 @@
+import { resolveApiUrl } from './paths.js';
+
+/**
+ * Where the dashboard is, given where the API is.
+ *
+ * There is no endpoint that says, so this is a derivation with an override.
+ * `api.ravensight.io` pairs with `app.ravensight.io`, which is what
+ * `.env.ravensight.prod.example` records as `DASHBOARD_URL`. A localhost API
+ * pairs with the Vite dev server's port. Anything else keeps the same host,
+ * which is the least surprising guess for a single host deployment.
+ *
+ * `RAVENSIGHT_DASHBOARD_URL` overrides all of it, and the device code flow does
+ * not rely on any of this: it uses the `verification_uri` the server sends.
+ *
+ * @param {string} [apiUrl]
+ * @returns {string}
+ */
+export function dashboardUrl(apiUrl = resolveApiUrl()) {
+  const override = process.env.RAVENSIGHT_DASHBOARD_URL;
+  if (override) return override.replace(/\/+$/, '');
+
+  let url;
+  try {
+    url = new URL(apiUrl);
+  } catch {
+    return apiUrl;
+  }
+
+  if (url.hostname === 'localhost' || url.hostname === '127.0.0.1') {
+    return 'http://localhost:5173';
+  }
+  if (url.hostname.startsWith('api.')) {
+    url.hostname = `app.${url.hostname.slice('api.'.length)}`;
+    url.port = '';
+  }
+  return url.toString().replace(/\/+$/, '');
+}
+
+/** The dashboard page for one game's playtest surface. */
+export function gameLink(gameId, apiUrl) {
+  return `${dashboardUrl(apiUrl)}/games/${encodeURIComponent(gameId)}/playtest`;
+}
+
+/** The dashboard page for one job. Matches `links.dashboard` from POST /jobs. */
+export function jobLink(gameId, jobId, apiUrl) {
+  return `${gameLink(gameId, apiUrl)}/jobs/${encodeURIComponent(jobId)}`;
+}
+
+/** The post job review form for one job. */
+export function reviewLink(gameId, jobId, apiUrl) {
+  return `${jobLink(gameId, jobId, apiUrl)}/review`;
+}
+
+/** The brief form. */
+export function briefLink(gameId, apiUrl) {
+  return `${gameLink(gameId, apiUrl)}/brief`;
+}
+
+/**
+ * "What leaves your machine": the page that lists, artifact by artifact, what a
+ * playtest uploads and what it never does. The CLI points at it rather than
+ * restating it, so there is one answer to that question and it is the one the
+ * server can keep true.
+ */
+export function trustLink(gameId, apiUrl) {
+  return `${gameLink(gameId, apiUrl)}/what-leaves-your-machine`;
+}
+
+/**
+ * Open a URL in the platform browser, answering whether the attempt was made.
+ *
+ * Best effort on purpose: a headless box has nothing to open, and a CLI that
+ * failed because `xdg-open` is missing would be failing at the wrong thing. The
+ * URL is always printed by the caller, so a false answer costs a copy and paste
+ * and nothing else.
+ *
+ * @param {string} url
+ * @param {{spawn?: Function}} [options]
+ * @returns {Promise<boolean>}
+ */
+export async function openInBrowser(url, options = {}) {
+  if (process.env.RAVENSIGHT_NO_BROWSER === '1') return false;
+  const spawn = options.spawn || (await import('node:child_process')).spawn;
+  const command = process.platform === 'darwin'
+    ? ['open', [url]]
+    : process.platform === 'win32'
+      ? ['cmd', ['/c', 'start', '', url]]
+      : ['xdg-open', [url]];
+  try {
+    const child = spawn(command[0], command[1], { stdio: 'ignore', detached: true });
+    if (child.unref) child.unref();
+    child.on('error', () => {});
+    return true;
+  } catch {
+    return false;
+  }
+}

package/src/detect.js

@@ -0,0 +1,77 @@
+import { execFile } from 'node:child_process';
+import { statfs } from 'node:fs/promises';
+import { freemem } from 'node:os';
+import { promisify } from 'node:util';
+
+const run = promisify(execFile);
+
+/**
+ * Run a command and answer its first line of output, or null when it is not
+ * there or does not work. Never throws: every caller of this file is a
+ * diagnostic, and a diagnostic that crashes is worse than one that says "not
+ * found".
+ * @param {string} command
+ * @param {string[]} args
+ * @param {{timeout?: number}} [options]
+ * @returns {Promise<string|null>}
+ */
+export async function probe(command, args, options = {}) {
+  try {
+    const { stdout, stderr } = await run(command, args, {
+      timeout: options.timeout || 15000,
+      windowsHide: true
+    });
+    const text = (stdout || stderr || '').trim();
+    return text.split('\n')[0] || '';
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * ffmpeg, used to re-encode a session recording before it is uploaded. Optional:
+ * without it the video is either skipped or uploaded as the driver produced it.
+ * @returns {Promise<{path: string|null, version: string|null}>}
+ */
+export async function detectFfmpeg() {
+  const explicit = process.env.RAVENSIGHT_FFMPEG;
+  if (explicit) {
+    const version = await probe(explicit, ['-version']);
+    if (version !== null) return { path: explicit, version };
+    return { path: null, version: null };
+  }
+  const version = await probe('ffmpeg', ['-version']);
+  return version === null ? { path: null, version: null } : { path: 'ffmpeg', version };
+}
+
+/**
+ * Free bytes on the volume holding a path. `statfs` is not on every platform
+ * this CLI claims to support, so a miss is null rather than an exception.
+ * @param {string} path
+ * @returns {Promise<number|null>}
+ */
+export async function freeBytes(path) {
+  try {
+    const info = await statfs(path);
+    return Number(info.bavail) * Number(info.bsize);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * A recommended persona concurrency for this machine, and the numbers behind it.
+ * One Chromium is roughly a gigabyte and a half at peak, so RAM is usually the
+ * binding constraint rather than cores. Never above 4: past that the machine is
+ * thrashing and the personas start timing out on each other.
+ * @returns {{cpus: number, freeMemGb: number, recommended: number}}
+ */
+export function recommendConcurrency(machine = {}) {
+  const cpus = machine.cpus || (process.availableParallelism ? process.availableParallelism() : 2);
+  const freeMemBytes = machine.freeMemBytes === undefined ? freemem() : machine.freeMemBytes;
+  const freeMemGb = freeMemBytes / 1e9;
+  const byCpu = Math.max(1, Math.floor(cpus / 2));
+  const byMem = Math.floor(freeMemGb / 1.5);
+  const recommended = Math.max(1, Math.min(4, byMem > 0 ? Math.min(byCpu, byMem) : 1));
+  return { cpus, freeMemGb: Number(freeMemGb.toFixed(1)), recommended };
+}

package/src/errors.js

@@ -0,0 +1,44 @@
+/**
+ * Process exit codes, from spec 17 section 1.2. CI reads these, so they are a
+ * contract: add a code, never renumber one.
+ */
+export const ExitCode = Object.freeze({
+  OK: 0,
+  FAILURE: 1,
+  BUDGET_EXCEEDED: 2,
+  ENVIRONMENT: 3,
+  AUTH: 4,
+  MODEL: 5,
+  CANCELED: 10
+});
+
+/**
+ * An error whose message is meant for the person running the CLI and whose
+ * exit code is meaningful to CI. `bin/ravensight-playtest.js` prints the
+ * message and exits with the code, with no stack trace: a stack trace for
+ * "you are not logged in" is noise, and the difference between that and a
+ * genuine crash is exactly what this class records.
+ */
+export class CliError extends Error {
+  /**
+   * @param {string} message
+   * @param {number} [exitCode]
+   * @param {{hint?: string, cause?: unknown}} [options]
+   */
+  constructor(message, exitCode = ExitCode.FAILURE, options = {}) {
+    super(message, options.cause === undefined ? undefined : { cause: options.cause });
+    this.name = 'CliError';
+    this.exitCode = exitCode;
+    this.hint = options.hint || null;
+  }
+}
+
+/** Not logged in, or the credential was refused. */
+export function authError(message, hint) {
+  return new CliError(message, ExitCode.AUTH, { hint });
+}
+
+/** The machine or the repo is not set up for what was asked. */
+export function environmentError(message, hint) {
+  return new CliError(message, ExitCode.ENVIRONMENT, { hint });
+}

package/src/fsutil.js

@@ -0,0 +1,77 @@
+import { createHash } from 'node:crypto';
+import { createReadStream } from 'node:fs';
+import { mkdir, readFile, rename, writeFile, chmod } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { pipeline } from 'node:stream/promises';
+
+/**
+ * Write a file so that a crash cannot leave a half written one behind: write a
+ * sibling temp file, fsync it through the stream close, then rename over the
+ * target. Rename is atomic within a filesystem, which is what makes the job
+ * journal safe to resume from after a kill.
+ *
+ * @param {string} file
+ * @param {string} contents
+ * @param {{mode?: number}} [options]
+ */
+export async function writeFileAtomic(file, contents, options = {}) {
+  await mkdir(dirname(file), { recursive: true });
+  const temp = join(dirname(file), `.${Math.random().toString(36).slice(2)}.tmp`);
+  await writeFile(temp, contents, options.mode === undefined ? undefined : { mode: options.mode });
+  if (options.mode !== undefined) await chmod(temp, options.mode);
+  await rename(temp, file);
+}
+
+/**
+ * Read and parse JSON, answering `fallback` when the file is absent. A file
+ * that exists but is not JSON is an error, not a fallback: silently treating a
+ * corrupt config as "no config" would throw away a developer's settings.
+ * @param {string} file
+ * @param {unknown} [fallback]
+ * @returns {Promise<unknown>}
+ */
+export async function readJson(file, fallback = null) {
+  let text;
+  try {
+    text = await readFile(file, 'utf8');
+  } catch (error) {
+    if (error.code === 'ENOENT') return fallback;
+    throw error;
+  }
+  try {
+    return JSON.parse(text);
+  } catch (error) {
+    throw new Error(`${file} is not valid JSON: ${error.message}`);
+  }
+}
+
+/** Write JSON atomically, with a trailing newline so the file is diffable. */
+export async function writeJson(file, value, options = {}) {
+  await writeFileAtomic(file, `${JSON.stringify(value, null, 2)}\n`, options);
+}
+
+/**
+ * The sha256 of a file, hex, streamed so a 200 MB video does not go through
+ * memory. Hex because that is what the presign route wants; it converts to the
+ * base64 S3 needs on its own side.
+ * @param {string} file
+ * @returns {Promise<string>}
+ */
+export async function sha256File(file) {
+  const hash = createHash('sha256');
+  await pipeline(createReadStream(file), hash);
+  return hash.digest('hex');
+}
+
+/** The sha256 of a string or buffer, hex. */
+export function sha256(value) {
+  return createHash('sha256').update(value).digest('hex');
+}
+
+/** JSON.stringify with sorted keys, so two equal objects hash identically. */
+export function stableStringify(value) {
+  if (value === null || typeof value !== 'object') return JSON.stringify(value) ?? 'null';
+  if (Array.isArray(value)) return `[${value.map(stableStringify).join(',')}]`;
+  const keys = Object.keys(value).sort();
+  return `{${keys.map(key => `${JSON.stringify(key)}:${stableStringify(value[key])}`).join(',')}}`;
+}

package/src/godot.js

@@ -0,0 +1,85 @@
+import { detectGodotBinary, isGodotProject, readProjectEngineVersion } from './run/drivers/godot-project.js';
+import { compareVersions } from './version.js';
+
+/**
+ * The Godot half of `check`.
+ *
+ * Godot detection lives in exactly one place, `src/run/drivers/godot-project.js`,
+ * which is the module the driver itself uses to find and launch a binary. So the
+ * binary `check` blesses is the same one a `godot_driver` run will spawn, which
+ * is the only property worth having here. The three helpers are re-exported so
+ * nothing outside the runner has to reach into `src/run/**`.
+ *
+ * All this file adds is the shape `check` prints, and one judgement the detector
+ * deliberately does not make: `detectGodotBinary` answers `matchesProject: false`
+ * both when the versions disagree and when one of them could not be read, which
+ * is right for "should I prefer this binary" and wrong for a doctor. `matches`
+ * here is three way, with `unknown` naming the missing side.
+ */
+
+export { detectGodotBinary, isGodotProject, readProjectEngineVersion };
+
+/** Just the major.minor of a version, which is what a project pins. */
+export function majorMinor(version) {
+  if (!version) return null;
+  const parts = String(version).split('.');
+  return parts.length >= 2 ? `${parts[0]}.${parts[1]}` : parts[0];
+}
+
+/**
+ * Everything `check` needs to say about Godot: whether this repo is a Godot
+ * project, what version it asks for, which binary was found, and whether the
+ * two agree on major and minor.
+ *
+ * Nothing here is ever a failure, and nothing here throws. Godot is needed only
+ * for a `godot_driver` run, so a miss is a warning even in a Godot repo: a
+ * developer may be running a web build today. `detectGodotBinary` throws when it
+ * finds nothing usable, because for the driver that is fatal; for `check` it is
+ * a warning row, so the throw is caught and its message kept as the reason.
+ *
+ * `matches` is a three way answer on purpose. `true` and `false` mean the two
+ * versions were both read and did or did not agree; `null` means one of them
+ * could not be read, which is NOT the same as agreement and must not be
+ * reported as if it were. `unknown` says which side is missing, so `check` can
+ * print "could not read the engine version" instead of quietly passing.
+ *
+ * @param {{repoRoot?: string, godotPath?: string}} [options]
+ * @param {Object} [deps] test seam: `godotProject` replaces the three helpers
+ * @returns {Promise<{isProject: boolean, projectVersion: string|null,
+ *   binary: {path: string|null, version: string|null, reason: string|null},
+ *   matches: boolean|null, unknown: 'project'|'binary'|'both'|null}>}
+ */
+export async function inspectGodot(options = {}, deps = {}) {
+  const repoRoot = options.repoRoot || process.cwd();
+  const mod = deps.godotProject || { detectGodotBinary, isGodotProject, readProjectEngineVersion };
+
+  const isProject = Boolean(await mod.isGodotProject(repoRoot));
+  const projectVersion = isProject ? (await mod.readProjectEngineVersion(repoRoot)) || null : null;
+
+  let binary = { path: null, version: null, reason: null };
+  try {
+    // `explicitPath` is the parameter name, not `godotPath`: passing the wrong
+    // one silently ignores --godot-path and detects something else.
+    const found = await mod.detectGodotBinary({
+      explicitPath: options.godotPath,
+      projectDir: repoRoot
+    });
+    if (found) binary = { path: found.path || null, version: found.version || null, reason: null };
+  } catch (error) {
+    binary = { path: null, version: null, reason: error.message };
+  }
+
+  let matches = null;
+  let unknown = null;
+  if (isProject) {
+    if (projectVersion && binary.version) {
+      matches = compareVersions(majorMinor(projectVersion), majorMinor(binary.version)) === 0;
+    } else if (!projectVersion && !binary.version) {
+      unknown = 'both';
+    } else {
+      unknown = projectVersion ? 'binary' : 'project';
+    }
+  }
+
+  return { isProject, projectVersion, binary, matches, unknown };
+}