ravensight-playtest 0.1.0

package/src/packs/index.js

@@ -0,0 +1,191 @@
+import { join } from 'node:path';
+import { paths } from '../paths.js';
+import { readJson, sha256, stableStringify, writeJson } from '../fsutil.js';
+import { CliError } from '../errors.js';
+import { ApiError } from '../api/errors.js';
+
+/**
+ * The content pack cache.
+ *
+ * Packs are data (markdown, JSON), never code, and they are fetched from the
+ * server rather than shipped in the npm package so a persona or a schema can
+ * be improved without a release. That makes three things necessary:
+ *
+ * - a conditional GET (`If-None-Match`), so the common case is a 304 and not a
+ *   megabyte on every run;
+ * - a sha256 over the cached body, verified on read, so a truncated write or a
+ *   half finished download cannot be mistaken for content;
+ * - an offline path, because spec 17 requires a run to work after one online
+ *   fetch, with the answer honestly labelled `stale`.
+ *
+ * The cache is keyed by API host (two servers can serve different packs under
+ * the same version) and by the request that produced it (game id and module
+ * list), so a bundle fetched for one game is never served for another.
+ */
+
+const CACHE_FORMAT = 1;
+
+function cacheFile({ apiUrl, gameId, modules }) {
+  const key = paths.cacheKey({ gameId: gameId || null, modules: modules || null });
+  return join(paths.packCacheDir(apiUrl), `bundle-${key}.json`);
+}
+
+/**
+ * @typedef {Object} PackResult
+ * @property {Object} bundle - the server's bundle body
+ * @property {string|null} etag
+ * @property {boolean} fromCache
+ * @property {string} fetchedAt - ISO, when the bundle was last actually fetched
+ * @property {boolean} stale - true when this process did not fetch it
+ */
+
+function resultFrom(entry, { fromCache, stale }) {
+  return {
+    bundle: entry.bundle,
+    etag: entry.etag || null,
+    fromCache,
+    fetchedAt: entry.fetched_at,
+    stale
+  };
+}
+
+/**
+ * Read the cache without touching the network. Answers null when there is no
+ * entry, and throws when there is one whose hash does not match its body: a
+ * corrupt cache has to be visible, because silently refetching would hide a
+ * disk that is losing writes.
+ *
+ * @param {{apiUrl: string, gameId?: string, modules?: string[]}} options
+ * @returns {Promise<PackResult|null>}
+ */
+export async function cached(options) {
+  const file = cacheFile(options);
+  const entry = await readJson(file, null);
+  if (!entry || typeof entry !== 'object' || entry.cache_format !== CACHE_FORMAT) return null;
+  const expected = entry.sha256;
+  const actual = sha256(stableStringify(entry.bundle));
+  if (expected !== actual) {
+    throw new CliError(
+      `The cached content pack at ${file} does not match its checksum.`,
+      1,
+      { hint: 'Delete that file and run the command again to refetch it.' }
+    );
+  }
+  return resultFrom(entry, { fromCache: true, stale: true });
+}
+
+async function writeCache(options, { bundle, etag }) {
+  const entry = {
+    cache_format: CACHE_FORMAT,
+    api_url: options.apiUrl,
+    game_id: options.gameId || null,
+    modules: options.modules || null,
+    etag: etag || null,
+    fetched_at: new Date().toISOString(),
+    sha256: sha256(stableStringify(bundle)),
+    bundle
+  };
+  await writeJson(cacheFile(options), entry);
+  return entry;
+}
+
+/**
+ * Fetch the bundle, ignoring any cached copy's ETag. Used by `check` and by an
+ * explicit pack refresh.
+ * @param {{api: Object, gameId?: string, modules?: string[]}} options
+ * @returns {Promise<PackResult>}
+ */
+export async function sync({ api, gameId, modules }) {
+  const answer = await api.packs.bundle({ gameId, modules });
+  const entry = await writeCache({ apiUrl: api.apiUrl, gameId, modules }, {
+    bundle: answer.body,
+    etag: answer.etag
+  });
+  return resultFrom(entry, { fromCache: false, stale: false });
+}
+
+/**
+ * The pack a run needs.
+ *
+ * Online with a cache: send `If-None-Match` and reuse the cached body on a 304,
+ * which is the normal case and costs one small request.
+ * Online without a cache: fetch and write one.
+ * Offline, or a fetch that fails for a reason a retry would not fix: fall back
+ * to the cache and label it `stale: true`. With no cache at all there is
+ * nothing to fall back to, so it throws rather than running with no personas.
+ *
+ * An authentication or authorization failure is never treated as "offline":
+ * falling back to a cache on a 401 would let a revoked token keep working.
+ *
+ * @param {{api: Object, gameId?: string, modules?: string[], offline?: boolean}} options
+ * @returns {Promise<PackResult>}
+ */
+export async function get({ api, gameId, modules, offline = false }) {
+  const key = { apiUrl: api.apiUrl, gameId, modules };
+  const existing = await cached(key);
+
+  if (offline) {
+    if (!existing) {
+      throw new CliError(
+        'No cached content pack, and offline was requested.',
+        1,
+        { hint: 'Run once while online, or drop the offline flag.' }
+      );
+    }
+    return existing;
+  }
+
+  try {
+    const answer = await api.packs.bundle({ gameId, modules, etag: existing ? existing.etag : null });
+    if (answer.status === 304 && existing) {
+      // Refresh `fetched_at` so "using cached content from N days ago" is
+      // about the last time the server confirmed it, not the last time the
+      // body changed.
+      const entry = await writeCache(key, { bundle: existing.bundle, etag: existing.etag });
+      return resultFrom(entry, { fromCache: true, stale: false });
+    }
+    const entry = await writeCache(key, { bundle: answer.body, etag: answer.etag });
+    return resultFrom(entry, { fromCache: false, stale: false });
+  } catch (error) {
+    // Any 5xx is the server being unavailable, and they are all the same thing
+    // from here: a 500 from a crashed handler is no more a reason to refuse to
+    // run than the 503 a load balancer sends. A 4xx is not: it is an answer
+    // about this request, and falling back to a cache on a 401 would let a
+    // revoked token keep working.
+    const fatal = error instanceof ApiError && !error.isNetwork && error.status < 500;
+    if (fatal || !existing) throw error;
+    return existing;
+  }
+}
+
+/**
+ * Verify a manifest's component ETags against a bundle we hold, which is what
+ * `check`'s "pack cache" row reports. Answers the components whose hash the
+ * bundle does not account for.
+ *
+ * The server's ETags are `sha256-<hex>` over each component, and the bundle
+ * carries the components themselves, so this is a real integrity check and not
+ * a version string comparison.
+ *
+ * @param {Object} manifest - the `GET /packs/manifest` body
+ * @param {Object} bundle - a bundle body
+ * @returns {{ok: boolean, checked: number, mismatched: string[]}}
+ */
+export function verifyAgainstManifest(manifest, bundle) {
+  const components = Array.isArray(manifest && manifest.components) ? manifest.components : [];
+  const have = new Map();
+  for (const persona of bundle.personas || []) have.set(`personas/${persona.slug}`, persona.etag);
+  for (const skill of bundle.skills || []) have.set(`skills/${skill.name}`, skill.etag);
+  for (const schema of bundle.schemas || []) have.set(`schemas/${schema.name}`, schema.etag);
+
+  const mismatched = [];
+  let checked = 0;
+  for (const component of components) {
+    if (!have.has(component.name)) continue;
+    checked += 1;
+    if (have.get(component.name) !== component.etag) mismatched.push(component.name);
+  }
+  return { ok: mismatched.length === 0, checked, mismatched };
+}
+
+export const packs = { get, sync, cached, verifyAgainstManifest, cacheFile };

package/src/paths.js

@@ -0,0 +1,129 @@
+import { homedir, tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { createHash } from 'node:crypto';
+
+export const DEFAULT_API_URL = 'https://api.ravensight.io';
+const USER_DIR_NAME = 'ravensight-playtest';
+
+/**
+ * Where the API is. `RAVENSIGHT_API_URL` overrides it, which is how a
+ * developer points at a local server and how the test suite points at an
+ * in-process one. A trailing slash is stripped so every path join is
+ * predictable.
+ * @returns {string}
+ */
+export function resolveApiUrl() {
+  const raw = process.env.RAVENSIGHT_API_URL || DEFAULT_API_URL;
+  return raw.replace(/\/+$/, '');
+}
+
+/**
+ * The host part of an API URL, used as the cache and keychain key. Two
+ * deployments must not share a token or a pack cache, and the host is the
+ * only part of the URL that identifies one.
+ * @param {string} [apiUrl]
+ * @returns {string}
+ */
+export function apiHost(apiUrl = resolveApiUrl()) {
+  try {
+    return new URL(apiUrl).host;
+  } catch {
+    return apiUrl;
+  }
+}
+
+function repoRoot(options = {}) {
+  return options.repoRoot || process.cwd();
+}
+
+/** Per user state, outside any repo: the credential fallback file and the caches. */
+function userDir() {
+  return process.env.RAVENSIGHT_HOME || join(homedir(), `.${USER_DIR_NAME}`);
+}
+
+/**
+ * The OS cache directory for this CLI, per API host. Pack content is keyed by
+ * host because two servers can ship different packs under the same version.
+ * @param {string} [apiUrl]
+ * @returns {string}
+ */
+function cacheDir(apiUrl = resolveApiUrl()) {
+  if (process.env.RAVENSIGHT_CACHE_DIR) {
+    return join(process.env.RAVENSIGHT_CACHE_DIR, apiHost(apiUrl));
+  }
+  const host = apiHost(apiUrl);
+  if (process.platform === 'darwin') {
+    return join(homedir(), 'Library', 'Caches', USER_DIR_NAME, host);
+  }
+  if (process.platform === 'win32') {
+    const base = process.env.LOCALAPPDATA || join(homedir(), 'AppData', 'Local');
+    return join(base, USER_DIR_NAME, 'Cache', host);
+  }
+  const base = process.env.XDG_CACHE_HOME || join(homedir(), '.cache');
+  return join(base, USER_DIR_NAME, host);
+}
+
+/**
+ * A filesystem safe fragment for a cache key that may contain anything: the
+ * modules list, a game id. Hashed rather than sanitized, so two keys that
+ * sanitize to the same name cannot collide.
+ * @param {unknown} value
+ * @returns {string}
+ */
+function cacheKey(value) {
+  return createHash('sha256').update(JSON.stringify(value === undefined ? null : value)).digest('hex').slice(0, 16);
+}
+
+export const paths = {
+  repoRoot,
+  userDir,
+  cacheDir,
+  cacheKey,
+  tmpDir: () => tmpdir(),
+
+  /** `<repo>/.ravensight`, everything this CLI writes into the developer's repo. */
+  ravensightDir: (options = {}) => join(repoRoot(options), '.ravensight'),
+
+  /** The repo to game link, written by `init`. */
+  configFile: (options = {}) => join(repoRoot(options), '.ravensight', 'config.json'),
+
+  jobsDir: (options = {}) => join(repoRoot(options), '.ravensight', 'jobs'),
+  jobDir: (jobId, options = {}) => join(repoRoot(options), '.ravensight', 'jobs', jobId),
+
+  /** The resumable journal for one job. */
+  stateFile: (jobId, options = {}) => join(repoRoot(options), '.ravensight', 'jobs', jobId, 'state.json'),
+
+  /** Pending and finished uploads for one job, append only. */
+  queueFile: (jobId, options = {}) => join(repoRoot(options), '.ravensight', 'jobs', jobId, 'upload-queue.jsonl'),
+
+  /** Where a run's artifacts are written, and what `uploadRunDir` is pointed at. */
+  runDir: (jobId, runId, options = {}) =>
+    join(repoRoot(options), '.ravensight', 'jobs', jobId, 'runs', runId),
+
+  /** The 0600 credential file, used only when no OS keychain is available. */
+  credentialsFile: () => join(userDir(), 'credentials.json'),
+
+  /** The pack cache directory for one API host. */
+  packCacheDir: (apiUrl) => join(cacheDir(apiUrl), 'packs')
+};
+
+/**
+ * The run relative names the upload allowlist recognizes. Written here rather
+ * than in nine command modules, so a writer and the uploader cannot disagree
+ * about where a report goes.
+ */
+export const RUN_FILES = Object.freeze({
+  reportMd: 'report.md',
+  reportJson: 'report.json',
+  usageJson: 'usage.json',
+  transcript: 'transcript.jsonl',
+  video: 'session.webm',
+  screenshotsDir: 'screenshots'
+});
+
+/** The job relative names, for artifacts that belong to a job and not a run. */
+export const JOB_FILES = Object.freeze({
+  capabilityReport: 'capability-report.json',
+  aggregateMd: 'aggregate-report.md',
+  aggregateJson: 'aggregate-report.json'
+});