ravensight-playtest 0.5.2 → 0.6.0

package/src/commands/run.js

@@ -3,19 +3,26 @@ import { randomUUID } from 'node:crypto';
 import { mkdir, readFile, stat } from 'node:fs/promises';
 import path from 'node:path';
 import { buildAggregate, writeAggregate } from '../run/aggregate.js';
+import { reportPrOutcomes } from '../run/labsOutcome.js';
+import { finishJob } from '../run/settle.js';
 import { optionsFrom, unknownOptionNotes } from '../run/args.js';
 import { controllerPlan, quoteMatchesPlan, runsMatchPlan } from '../run/controllers.js';
 import { getDeps } from '../run/deps.js';
 import { createDriver } from '../run/drivers/index.js';
 import EXIT from '../run/exit.js';
+import { stopRunningChecks } from '../run/checks.js';
+import { detectGodotBinary, measureProject } from '../run/drivers/godot-project.js';
+import { claimSignal } from '../run/liveWork.js';
 import { createHeartbeat } from '../run/heartbeat.js';
 import { createUsageLedger } from '../run/usage.js';
-import { createModelClient, ModelUnavailableError, ProxyError } from '../run/model.js';
+import { configureSpendHold, createModelClient, ModelUnavailableError, ProxyError } from '../run/model.js';
 import { jobDir, runDir as runDirFor, JOB_FILES, RUN_FILES } from '../run/paths.js';
 import { readBridgeConfig } from "../run/drivers/stdio.js";
 import { WEBDRIVER_NAMES, readDriverConfig } from '../run/drivers/webdriver.js';
 import { automationChecks } from './check.js';
 import { runPersona } from '../run/personaLoop.js';
+import { tracesWanted } from '../run/acceptance.js';
+import { cleanCommit } from '../run/replay.js';
 import { loadLocalBrief, localBriefProblems } from '../briefLocal.js';
 import { DEFAULT_PERSONAS as RUN_DEFAULT_PERSONAS, RUN_MODULES, SIGN_UP_ACTIONS, defaultPersonasFor, describeBreakdown, personaCount, unknownPersonaMessage, unknownPersonas } from '../runDefaults.js';
 import { bold } from '../ui/index.js';
@@ -103,12 +110,18 @@ async function run(flags, injected, deps, log) {
   if (keyModifier.error) { log(keyModifier.error); return EXIT.ENVIRONMENT; }
   const driverName = options.driver || (context.config && context.config.driver) || 'playwright_web';
   if (controllers?.length > 1 && !['playwright_web', 'godot_driver'].includes(driverName)) { log('Comparisons currently require a web or Godot build. Nothing was charged.'); return EXIT.ENVIRONMENT; }
-  const target = resolveTarget(options, context.config, driverName);
+  const target = resolveTarget(options, context.config, driverName, repoRoot);
   if (!target) {
     log('Point the run at a build: --build-url for a web build, --godot-project for Godot, or --driver-config for a native or text bridge.');
     return EXIT.ENVIRONMENT;
   }
 
+  const noGodot = await godotRefusal({ driverName, godotPath: options.godotPath, projectDir: target, injected });
+  if (noGodot) {
+    log(noGodot);
+    return EXIT.ENVIRONMENT;
+  }
+
   // `aggregate_report` is asked for explicitly: it is what buys the run the
   // `aggregate.*` steps are spendable from, and it is free (the price list has
   // no unit for it), so asking costs nothing and not asking costs the judged
@@ -247,6 +260,11 @@ async function run(flags, injected, deps, log) {
     }
   }
 
+  // A Godot run always writes its trace locally. It goes up only for a game with
+  // Labs on, where a replay or a fix's verify can read it back from another
+  // machine; an older server or a failed read leaves it on this one.
+  if (driverName === 'godot_driver') options.uploadTrace = await tracesWanted(api, gameId);
+
   const idempotencyKey = options.idempotencyKey || randomUUID();
   let registered;
   try {
@@ -308,6 +326,10 @@ async function run(flags, injected, deps, log) {
   }
   log(`job ${jobId}${registered.replayed ? ' (replayed)' : ''}: ${formatCents(registered.price && registered.price.price_cents)} charged. ${directory}`);
 
+  // Which commit a trace was recorded on, so `replay --baseline` can check it
+  // there. Null on a dirty tree: that code is not in any commit to go back to.
+  const commit = driverName === 'godot_driver' ? await cleanCommit(repoRoot) : null;
+
   return playJob({
     deps,
     api,
@@ -315,7 +337,7 @@ async function run(flags, injected, deps, log) {
     gameId,
     jobId,
     repoRoot,
-    runs: registered.runs || [],
+    runs: (registered.runs || []).map(entry => (commit ? { ...entry, trace_header: { commit } } : entry)),
     pack,
     personas,
     driverName,
@@ -339,6 +361,32 @@ async function run(flags, injected, deps, log) {
  * @param {(message: string) => void} log
  * @returns {number|null} an exit code, or null when the error is not one of these
  */
+/**
+ * The line that names a job's start balance before it is confirmed, or null for a
+ * job with none. The floor is the server's figure, and it is never charged.
+ *
+ * @param {{estimate_cents?: number, minimum_balance_cents?: number}} quote
+ * @returns {string|null}
+ */
+export function startBalanceLine(quote) {
+  if (!Number.isFinite(quote?.minimum_balance_cents)) return null;
+  return `A balance of ${formatCents(quote.minimum_balance_cents)} is needed to start. Only the price, ${formatCents(quote.estimate_cents)}, is charged.`;
+}
+
+/**
+ * The refusal when a balance is short of a job's start balance. A role that may not
+ * see the balance is told the floor, and no figure that could reveal it.
+ *
+ * @param {{estimate_cents: number, minimum_balance_cents: number, balance_cents?: number|null, shortfall_cents?: number|null, topup_url?: string}} quote
+ * @returns {string}
+ */
+export function startBalanceShort(quote) {
+  const shortfall = Number.isFinite(quote.shortfall_cents) ? quote.shortfall_cents
+    : Number.isFinite(quote.balance_cents) ? quote.minimum_balance_cents - quote.balance_cents : null;
+  const more = shortfall !== null && shortfall > 0 ? `, ${formatCents(shortfall)} more than this account has` : '';
+  return `This job needs a balance of ${formatCents(quote.minimum_balance_cents)} to start${more}. Only its price of ${formatCents(quote.estimate_cents)} is charged, and the rest stays in the balance. Top up at ${quote.topup_url || 'ravensight.io'} and run this again. Nothing was charged.`;
+}
+
 export function explainRegisterRefusal(error, log) {
   const code = error && error.code;
   const body = (error && error.body) || {};
@@ -346,8 +394,12 @@ export function explainRegisterRefusal(error, log) {
     log('The server refused this job because the game has no complete expectations brief. Run "ravensight-playtest brief" and try again.');
     return EXIT.ENVIRONMENT;
   }
+  if (code === 'insufficient_balance' && Number.isFinite(body.minimum_balance_cents)) {
+    log(startBalanceShort(body));
+    return EXIT.ENVIRONMENT;
+  }
   if (code === 'insufficient_balance') {
-    log(`That is more than the balance covers: ${formatCents(body.shortfall_cents)} short. Top up at ${body.topup_url || 'ravensight.io'} and run this again.`);
+    log(`That is more than the balance covers${Number.isFinite(body.shortfall_cents) ? `: ${formatCents(body.shortfall_cents)} short` : ''}. Top up at ${body.topup_url || 'ravensight.io'} and run this again.`);
     return EXIT.ENVIRONMENT;
   }
   if (code === 'price_changed') {
@@ -526,7 +578,8 @@ export async function playJob({
     }
   }
 
-  await aggregatePhase({
+  // A validate job has no aggregate: its comparison is computed by the server.
+  if (!options.skipAggregate) await aggregatePhase({
     deps,
     api,
     client,
@@ -558,20 +611,31 @@ export async function playJob({
   const anySucceeded = results.some(result => result.state === 'succeeded' && !result.reportRefused);
   const reportRefused = results.some(result => result.reportRefused);
 
+  let settledState = null;
   if (finish) {
-    const finished = await api.jobs.finish(gameId, jobId, {
-      state: budgetHit && !anySucceeded ? 'budget_exceeded' : undefined,
-      reason: canceled ? 'cancelled by the developer' : ''
+    const finished = await finishJob({
+      api, gameId, jobId, log,
+      body: {
+        state: budgetHit && !anySucceeded ? 'budget_exceeded' : undefined,
+        reason: canceled ? 'cancelled by the developer' : ''
+      }
     });
-    journal.finished = true;
-    await stateFile.save(repoRoot, journal);
-    log(`job ${jobId} ${finished.job ? finished.job.state : 'finished'}: refunded ${formatCents(finished.refunded_cents)}.`);
+    if (finished) {
+      journal.finished = true;
+      await stateFile.save(repoRoot, journal);
+      settledState = finished.job ? finished.job.state : null;
+      log(`job ${jobId} ${settledState || 'finished'}: refunded ${formatCents(finished.refunded_cents)}.`);
+    }
   }
   log(`Reports: ${directory}`);
 
   if (canceled) return EXIT.CANCELED;
   if (reportBudgetRefused || reportRefused) return EXIT.FAILED;
   if (playBudgetHit) return EXIT.BUDGET;
+  // The server's settlement is the verdict on the job. A job it settled as
+  // failed (every run refunded, nothing kept) exited 0 in 0.5.0, so a script
+  // could not tell it from a success.
+  if (settledState === 'failed' || settledState === 'stalled') return EXIT.FAILED;
   return anySucceeded || reportBudgetDelivered ? EXIT.OK : EXIT.FAILED;
 }
 
@@ -612,7 +676,9 @@ export async function playPersonaRun({
   // Headless is right for a browser and wrong for Godot: a headless Godot
   // routes no GUI input, so it is a smoke-test mode rather than a way to play.
   const headless = driverName === 'godot_driver' ? options.headless === true : options.headed !== true;
-  const driver = await makeDriver(driverName, driverOptions({ headless, driverName, target, directory, entry, jobId, keyModifier: options.keyModifier }));
+  // A validate run plays its own side's checkout and its pair's seed.
+  const runTarget = entry.target || target;
+  const driver = await makeDriver(driverName, driverOptions({ headless, driverName, target: runTarget, directory, entry, jobId, keyModifier: options.keyModifier, godotPath: options.godotPath, realtime: options.realtime }));
   // The ledger is created here rather than inside the loop so the heartbeat
   // can feed it the server's own figure for what this run has spent. Prices
   // are server side only, so that answer is the only real one.
@@ -659,12 +725,13 @@ export async function playPersonaRun({
       persona,
       driver,
       driverName,
-      target,
+      target: runTarget,
       runDirectory: directory,
       skill,
       // The brief this command fetched and checked is complete, not the
       // pack's copy, which a pack bundle does not always carry.
-      brief: brief || pack.brief || null,
+      // A feature scenario brings its own, built from the frozen specification.
+      brief: entry.brief || brief || pack.brief || null,
       localBrief: usableLocalBrief(localBrief),
       intentNotes: pack.intent_notes || [],
       schemas: pack.schemas || [],
@@ -762,7 +829,7 @@ export async function playPersonaRun({
   });
 
   const delivered = {};
-  await deliver({ deps, api, gameId, jobId, runId, directory, outcome, options, log, journal, repoRoot, delivery: delivered });
+  await deliver({ deps, api, gameId, jobId, runId, directory, outcome, options, log, journal, repoRoot, delivery: delivered, extraBody: { ...validationBody(entry, outcome), ...(Number.isInteger(entry.report_scenario) ? { feature_scenario: entry.report_scenario } : {}) } });
 
   if (delivered.reportInvalid) {
     // No synthetic telemetry for findings the server does not hold, and no
@@ -791,6 +858,30 @@ export async function playPersonaRun({
   return { runId, persona: persona.slug, state: outcome.state, quitReason: outcome.quitReason };
 }
 
+/**
+ * What a validate run measured, in the shape its `complete` carries. Nothing for
+ * any other run, or a run whose driver measured nothing. A death count that is
+ * not a whole number is not one the game meant as a count, so it reads unknown.
+ *
+ * @param {Object} entry
+ * @param {Object} outcome
+ * @returns {{validation: Object}|null}
+ */
+export function validationBody(entry, outcome) {
+  const metrics = outcome && outcome.playMetrics;
+  if (!entry || !entry.validation || !metrics) return null;
+  return {
+    validation: {
+      seed: entry.seed,
+      ticks: metrics.ticks,
+      game_seconds: metrics.game_seconds,
+      deaths: Number.isInteger(metrics.deaths) && metrics.deaths >= 0 ? metrics.deaths : null,
+      errors: metrics.errors,
+      replayable: metrics.replayable
+    }
+  };
+}
+
 /**
  * A run's duration as `complete` sends it: `{ wall_seconds, model_seconds }`,
  * each a number or null.
@@ -819,12 +910,13 @@ export function durationBody(duration) {
  * uploaded and completed in exactly this order, including the `uploading`
  * transition the server's table allows from `reporting` and nowhere else.
  */
-export async function deliver({ deps, api, gameId, jobId, runId, directory, outcome, options, log, journal, repoRoot, delivery = null }) {
+export async function deliver({ deps, api, gameId, jobId, runId, directory, outcome, options, log, journal, repoRoot, delivery = null, extraBody = null }) {
   const body = {
     state: outcome.state,
     reason: outcome.quitDetail || '',
     actions_taken: outcome.actionsTaken,
-    quit_reason: outcome.quitReason
+    quit_reason: outcome.quitReason,
+    ...(extraBody || {})
   };
   // The run card's duration. The server lane accepts `duration`; an older
   // server ignores a key it does not know.
@@ -867,6 +959,7 @@ export async function deliver({ deps, api, gameId, jobId, runId, directory, outc
         runId,
         includeVideo: Boolean(options.uploadVideo),
         includeTranscript: Boolean(options.uploadTranscript),
+        includeTrace: Boolean(options.uploadTrace),
         body
       });
     } catch (error) {
@@ -1176,13 +1269,20 @@ export function createInterruptHandler({ api, gameId, jobId, repoRoot, journal,
     state.signalled = true;
     state.signal = signal;
     onInterrupt(signal);
+    // A check can run for minutes, and nothing it could say now is wanted.
+    stopRunningChecks();
+    if (target === process) claimSignal();
     log(`\n${signal}: ${message || `finishing the turn in flight, then stopping. Nothing is lost; "ravensight-playtest resume ${jobId}" carries on.`}`);
-    // Hand the signal back to the default behaviour, so a second press kills
-    // the process rather than being swallowed by a handler that is now done.
+    log(`Signal again to stop at once: job ${jobId} then stays open until the server's hourly sweep settles it, and what did not happen comes back then.`);
+    // Hand the signal back, so a second press kills the process rather than being
+    // swallowed by a handler that is now done. Godot and its temp copy are not left
+    // behind: ./liveWork.js hears that press and tidies up first.
     for (const name of signals) target.removeListener(name, onSignal);
   };
 
   for (const name of signals) target.on(name, onSignal);
+  // The pause for the hourly spend limit tells the developer Ctrl-C stops the job.
+  configureSpendHold({ shouldStop: () => state.signalled });
 
   return {
     get signalled() {
@@ -1213,10 +1313,39 @@ export function createInterruptHandler({ api, gameId, jobId, repoRoot, journal,
 
     release() {
       for (const name of signals) target.removeListener(name, onSignal);
+      configureSpendHold({ shouldStop: () => false });
     }
   };
 }
 
+/**
+ * Why a Godot job cannot start on this machine, or null. Asked before any price: a job
+ * charged and refunded over a missing binary is a worse answer than saying so for free.
+ *
+ * @param {{driverName: string, godotPath?: string, projectDir?: string, injected?: Object}} input
+ * @returns {Promise<string|null>}
+ */
+export async function godotRefusal({ driverName, godotPath, projectDir, injected = {} }) {
+  if (driverName !== 'godot_driver') return null;
+  // A test with its own driver has no use for a real binary.
+  const detect = injected.detectGodot || (injected.driverFactory ? null : detectGodotBinary);
+  if (!detect) return null;
+  try {
+    await detect({ explicitPath: godotPath || undefined, projectDir, env: process.env });
+    if (projectDir) {
+      // A Godot 3 project is config_version 4. Godot 4 would quietly convert the copy
+      // and the run would answer about something the developer does not have.
+      const settings = await readFile(path.join(projectDir, 'project.godot'), 'utf8').catch(() => '');
+      const version = /^config_version\s*=\s*(\d+)/m.exec(settings);
+      if (version && Number(version[1]) < 5) return 'This project is from before Godot 4 (config_version ' + version[1] + '), and only Godot 4.2 and newer are supported. Nothing was charged.';
+      await measureProject(projectDir, { excludes: ['.git', '.ravensight', 'node_modules', '.DS_Store'] });
+    }
+    return null;
+  } catch (error) {
+    return `${String(error && error.message)}. Nothing was charged.`;
+  }
+}
+
 /**
  * Resolve the context, the game and the credential, or answer with an exit
  * code. Shared with `profile`.
@@ -1250,12 +1379,16 @@ export async function resolveSetup(deps, options, log) {
     return { code: EXIT.ENVIRONMENT };
   }
 
+  const repoRoot = path.resolve(context.repoRoot || options.repo || process.cwd());
+  // In the background on purpose: what became of an earlier --open-pr is feedback,
+  // and nothing this command does waits for it or can be failed by it.
+  void reportPrOutcomes({ api: context.api, gameId, repoRoot, ...(deps.execGh ? { exec: deps.execGh } : {}) });
   return {
     context,
     api: context.api,
     gameId,
     apiUrl: context.apiUrl,
-    repoRoot: path.resolve(context.repoRoot || options.repo || process.cwd()),
+    repoRoot,
     cliVersion: deps.cliVersion || context.api.cliVersion || '0.0.0'
   };
 }
@@ -1269,12 +1402,18 @@ export async function resolveSetup(deps, options, log) {
  *
  * @returns {Object}
  */
-export function driverOptions({ headless, driverName, target, directory, entry, jobId, keyModifier }) {
+export function driverOptions({ headless, driverName, target, directory, entry, jobId, keyModifier, godotPath, realtime }) {
   // Only the browser driver sends key chords with a modifier.
   const modifier = driverName === 'playwright_web' ? resolveKeyModifier(keyModifier).modifier : null;
+  const godot = driverName === 'godot_driver'
+    // Lockstep unless the game has to run in real time: every persona run on
+    // Godot is seeded, on fixed ticks, and leaves a trace.jsonl to replay.
+    ? { pauseBetweenActions: realtime !== true, lockstep: realtime !== true, ...(Number.isInteger(entry.seed) ? { seed: entry.seed } : {}), ...(entry.trace_header ? { traceHeader: entry.trace_header } : {}), ...(godotPath ? { godotPath } : {}) }
+    : {};
   return {
     headless,
     ...(modifier ? { modifier } : {}),
+    ...godot,
     playtest: {
       token: entry.playtest_token || null,
       runId: entry.run_id,
@@ -1322,7 +1461,7 @@ export async function loadRunReports(repoRoot, jobId, personaRuns, journal = nul
     }
     const file = path.join(runDirFor(repoRoot, jobId, entry.run_id), RUN_FILES.reportJson);
     try {
-      const report = JSON.parse(await readFile(file, 'utf8'));
+      const report = withoutRunnerEvidence(JSON.parse(await readFile(file, 'utf8')), await readRunnerEvidence(path.dirname(file)));
       out.push({ runId: entry.run_id, persona: entry.persona, ...(entry.controller ? { controller: entry.controller } : {}), state: recorded?.state || entry.state || (report && report.partial === true ? 'budget_exceeded' : 'succeeded'), report });
     } catch {
       out.push({ runId: entry.run_id, persona: entry.persona, ...(entry.controller ? { controller: entry.controller } : {}), state: 'failed', report: null });
@@ -1331,6 +1470,38 @@ export async function loadRunReports(repoRoot, jobId, personaRuns, journal = nul
   return out;
 }
 
+async function readRunnerEvidence(directory) {
+  try {
+    const parsed = JSON.parse(await readFile(path.join(directory, RUN_FILES.runnerEvidence), 'utf8'));
+    return Array.isArray(parsed && parsed.attached) ? parsed.attached : [];
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * The report as the persona wrote it, for the aggregate: the screenshot the
+ * runner attached to a finding so the server keeps it is evidence for the
+ * server, not a sign that two findings sharing it are one issue.
+ *
+ * @param {Object} report
+ * @param {Array<{id: string, ref: string}>} attached
+ * @returns {Object}
+ */
+export function withoutRunnerEvidence(report, attached = []) {
+  if (!report || !Array.isArray(report.findings) || attached.length === 0) return report;
+  const byId = new Map(attached.map(entry => [entry.id, entry.ref]));
+  return {
+    ...report,
+    findings: report.findings.map(finding => {
+      if (!byId.has(finding.id) || !Array.isArray(finding.evidence)) return finding;
+      const ref = byId.get(finding.id);
+      const index = finding.evidence.findLastIndex(item => item && item.type === 'screenshot' && item.ref === ref);
+      return index === -1 ? finding : { ...finding, evidence: finding.evidence.filter((_, i) => i !== index) };
+    })
+  };
+}
+
 async function listUploadable(directory, options) {
   const names = [RUN_FILES.reportMd, RUN_FILES.reportJson, RUN_FILES.usageJson];
   if (options.uploadTranscript) names.push(RUN_FILES.transcript);
@@ -1542,11 +1713,16 @@ export function resolveMaxActions(options, persona, pack, run = null) {
   return candidates.length > 0 ? Math.min(...candidates) : DEFAULT_MAX_ACTIONS * factor;
 }
 
-export function resolveTarget(options, config, driverName) {
+export function resolveTarget(options, config, driverName, repoRoot = null) {
   if (WEBDRIVER_NAMES.includes(driverName) || driverName === 'cli_stdio') return options.driverConfig || (config?.build?.kind === 'driver_config' ? config.build.ref : null);
   const build = (config && config.build) || {};
   if (driverName === 'playwright_web') return options.buildUrl || (build.kind === 'url' ? build.ref : null) || null;
-  if (driverName === 'godot_driver') return options.godotProject || (build.kind === 'godot_project' ? build.ref : null) || null;
+  if (driverName === 'godot_driver') {
+    const project = options.godotProject || (build.kind === 'godot_project' ? build.ref : null) || null;
+    // `init` writes "." for a repository that is itself the Godot project;
+    // that means the repository, wherever the command was started from.
+    return project && repoRoot ? path.resolve(repoRoot, project) : project;
+  }
   return options.cli || null;
 }
 

package/src/commands/template.js

@@ -0,0 +1,70 @@
+import { readdir } from 'node:fs/promises';
+import path from 'node:path';
+
+import { capabilityLive } from '../run/acceptance.js';
+import { defaultConfig, saveConfig } from '../config.js';
+import { initRepository, TEMPLATE_3D_DIR, writeScaffold } from '../create/scaffold.js';
+import { getDeps } from '../run/deps.js';
+import EXIT from '../run/exit.js';
+
+/**
+ * `ravensight-playtest template godot-3d`: the 3D Alpha's starting point.
+ *
+ * It copies a small placeholder project from this package into a new directory, as
+ * its own git repository, linked to a game that already exists. No model is involved,
+ * no design is written and nothing is charged, which is the whole difference from
+ * `create`: nothing here makes a game from a brief.
+ *
+ * It answers only for a game with Labs on and Build a feature or Validate changes
+ * live on it, because those are the only things the template is for. There is no
+ * Alpha switch of its own.
+ */
+
+const TEMPLATES = Object.freeze({ 'godot-3d': TEMPLATE_3D_DIR });
+const OFF = 'The 3D template is part of Ravensight Labs (Alpha), and it needs Build a feature or Validate changes on for this game. Turn Labs on from the Labs page in the dashboard. Nothing was written.';
+
+/**
+ * @param {string} name
+ * @param {Object} flags
+ * @param {Object} [injected] test seam
+ * @returns {Promise<number>} an exit code
+ */
+export async function templateCommand(name, flags = {}, injected = {}) {
+  const deps = injected.deps || (await getDeps());
+  const log = injected.log || (deps.ui && deps.ui.info ? message => deps.ui.info(message) : message => console.log(message));
+  const templateDir = Object.hasOwn(TEMPLATES, name) ? (injected.templateDir || TEMPLATES[name]) : null;
+  if (!templateDir) {
+    log(`There is no template ${name}. This command writes ${Object.keys(TEMPLATES).join(', ')}; Create a game writes its own 2D project.`);
+    return EXIT.ENVIRONMENT;
+  }
+  const title = String(flags.name || 'New 3D project').slice(0, 80);
+  const dir = path.resolve(flags.dir || name);
+  const existing = await readdir(dir).catch(() => null);
+  if (existing && existing.length > 0) {
+    log(`${dir} is not empty, and a template only goes in an empty directory. Pass --dir with a new one. Nothing was written.`);
+    return EXIT.ENVIRONMENT;
+  }
+
+  const context = await deps.createContext({ apiUrl: flags.apiUrl, repoRoot: path.dirname(dir), requireAuth: true }).catch(error => {
+    log(`You are not signed in. Run "ravensight-playtest login" first. (${String(error && error.message)})`);
+    return null;
+  });
+  if (!context) return EXIT.AUTH;
+  const labs = await context.api.labs.get(flags.game).catch(() => null);
+  if (!capabilityLive(labs, 'feature') && !capabilityLive(labs, 'validate')) {
+    log(OFF);
+    return EXIT.ENVIRONMENT;
+  }
+
+  await initRepository(dir, { templateDir });
+  await saveConfig(defaultConfig(flags.game, { driver: 'godot_driver', godot_project: '.', build: { kind: 'godot_project', ref: '.' } }), { repoRoot: dir });
+  const { manifest, commit } = await writeScaffold({ dir, name: title, design: null, templateDir });
+  log(`3D Alpha: ${dir} holds the ${manifest.name} template ${manifest.version} on main (${String(commit).slice(0, 8)}). Nothing was charged. It is a proof of concept with placeholder primitives, and no key: README.md says where this game's key goes.`);
+  log('Then, from that directory:');
+  log('  npx ravensight-playtest feature "<brief>" --alpha-3d');
+  log('  npx ravensight-playtest validate <branch> --base main --alpha-3d');
+  if (flags.json) (deps.ui && deps.ui.json ? deps.ui.json : answer => console.log(JSON.stringify(answer)))({ dir, template: manifest.name, version: manifest.version, commit });
+  return EXIT.OK;
+}
+
+export default templateCommand;