ravensight-playtest 0.5.2 → 0.7.0

package/src/commands/validateHosted.js

@@ -0,0 +1,292 @@
+import { createHash } from 'node:crypto';
+import path from 'node:path';
+
+import { capabilityLive } from '../run/acceptance.js';
+import { getDeps } from '../run/deps.js';
+import EXIT from '../run/exit.js';
+import { checkoutRef } from '../run/replay.js';
+import { jobLink } from '../dashboard.js';
+import { resolveSetup } from './run.js';
+import { detectGodotBinary, majorMinor } from '../godot.js';
+import { buildPack, HOSTED_GODOT, PACK_NAME } from '../simulation/godotPack.js';
+import { defaultBase } from './validate.js';
+import { DIMENSION_3D, dimensionGate } from '../run/dimension.js';
+
+/**
+ * `ravensight-playtest validate <branch> --hosted`: two uploaded Godot builds, the
+ * base and the head, played on one seed on hosted machines, and compared.
+ *
+ * Code stays here. Both commits are extracted to temp directories and exported to
+ * game packs on this machine; only the packs are uploaded. A commit that will not
+ * export is a free answer, because nothing is priced until both packs exist.
+ */
+
+export const DEFAULT_GAMES = 3;
+export const MAX_GAMES = 10;
+export const DEFAULT_STEPS = 300;
+export const MAX_STEPS = 10000;
+const POLL_MS = 15000;
+const WAIT_MS = 80 * 60 * 1000;
+const money = cents => `$${(cents / 100).toFixed(2)}`;
+const BUILD_POLL_MS = 5000;
+const BUILD_WAIT_MS = 15 * 60 * 1000;
+const PAIR_ATTEMPTS = 3;
+
+/** The whole request is decided here, so one commit pair on one seed is one request. */
+export function simulationFor({ seed, games, steps }) {
+  return { version: 1, seed, runs: games, max_steps: steps, workers: 1, strategies: [{ name: 'random', policy: 'random' }] };
+}
+
+// Why a comparison ended with no report, the dashboard's sentences. Money is the ledger's line.
+const COMPARISON_REASONS = {
+  base_failed: 'No game finished on the base build, so the head build did not run.',
+  head_failed: 'No game finished on the head build, so there is no comparison.',
+  platform_failure: 'A machine failed on our side, so there is no comparison.',
+  time_limit: 'A game reached the time limit, so there is no comparison.',
+  charge_refused: 'The balance could not cover both builds, so neither one ran.',
+  canceled: 'This comparison was canceled.',
+  not_comparable: 'The two builds could not be compared, so there is no comparison.'
+};
+
+/** The server's words, one line each. This command adds no reading of its own. */
+export function comparisonLines(pair) {
+  const name = side => `${side.ref || side.buildId}${side.sha ? ` (${side.sha.slice(0, 12)})` : ''}`;
+  const lines = [`Base ${name(pair.base)}`, `Head ${name(pair.head)}`, `Seed ${pair.seed}`];
+  const report = pair.report;
+  if (!report) {
+    lines.push(COMPARISON_REASONS[pair.reason] || (pair.reason ? 'No comparison was delivered.' : 'No comparison was delivered: not finished.'));
+  } else {
+    lines.push(`Verdict: ${report.verdict}`, report.note);
+    for (const game of report.games) {
+      lines.push(`Game ${game.run_index + 1}: ${game.outcome_differs ? `failed on the ${game.head_status === 'failed' ? 'head' : 'base'} only (base ${game.base_status}, head ${game.head_status})` : !game.compared ? `not compared (base ${game.base_status}, head ${game.head_status})` : game.matched ? 'same state at every recorded step' : `first differs at state ${game.first_divergence.state}${game.first_divergence.exact ? '' : ' or shortly before'}`}`);
+    }
+  }
+  const money_ = pair.money;
+  if (money_) lines.push(!money_.chargedCents ? 'Nothing was charged.' : money_.refundedCents ? `Charged ${money(money_.chargedCents)}, refunded ${money(money_.refundedCents)}, kept ${money(money_.keptCents)}.` : `Charged ${money(money_.chargedCents)}.`);
+  return lines;
+}
+
+/** A ready build of these exact bytes is reused, so a retry pays no second deposit. */
+async function ensureBuild({ api, gameId, built, sleep, fetchImpl, log, label, clock, created: createdIds }) {
+  const manifest = { sha256: built.sha256, bytes: built.bytes, entrypoint: PACK_NAME, args: [] };
+  const find = async () => (await api.hosted.builds(gameId)).builds.find(build => build.sha256 === built.sha256 && !['deleting', 'failed', 'rejected'].includes(build.state));
+  let build = await find();
+  // An upload that never finished is picked up again under the same request key.
+  if (!build || build.state === 'uploading') {
+    const capabilities = await api.hosted.capabilities(gameId);
+    if (!capabilities.reservationOffer) throw new Error('Hosted build uploads are not available.');
+    const created = await api.hosted.createBuild(gameId, {
+      ...manifest, reservation: { amountCents: capabilities.reservationOffer.amountCents, version: capabilities.reservationOffer.version }
+    }, `pack-${createHash('sha256').update(`${gameId}:${built.sha256}`).digest('hex').slice(0, 40)}`);
+    createdIds.push(created.build);
+    log(`Uploading ${label}: ${(built.bytes / 1e6).toFixed(1)} MB. Holding ${money(capabilities.reservationOffer.amountCents)} of the price as its deposit.`);
+    const put = await fetchImpl(created.upload.url, { method: created.upload.method || 'PUT', headers: created.upload.headers, body: built.zip });
+    if (!put.ok) throw new Error(`The upload of ${label} was refused (${put.status}).`);
+    await api.hosted.completeBuild(gameId, created.build.buildId);
+    build = await find() || created.build;
+  }
+  const deadline = clock() + BUILD_WAIT_MS;
+  while (build.state !== 'ready') {
+    if (['failed', 'rejected', 'deleting'].includes(build.state)) throw new Error(`The hosted check refused the ${label} build (${build.state}).`);
+    if (clock() >= deadline) throw new Error(`The ${label} build was not checked in time. Run this again to pick it up.`);
+    await sleep(BUILD_POLL_MS);
+    // By id, not by bytes: a refused build has to be seen as refused, not as still waiting.
+    build = (await api.hosted.builds(gameId)).builds.find(row => row.buildId === build.buildId) || { ...build, state: 'deleting' };
+  }
+  return build;
+}
+
+/**
+ * @param {string} [head] the branch to compare, default HEAD
+ * @param {Object} flags
+ * @param {Object} [injected] test seam
+ * @returns {Promise<number>} an exit code
+ */
+export async function validateHostedCommand(head, flags = {}, injected = {}) {
+  const deps = injected.deps || (await getDeps());
+  const log = injected.log || (deps.ui?.info ? message => deps.ui.info(message) : message => console.log(message));
+  const sleep = injected.sleep || (ms => new Promise(resolve => setTimeout(resolve, ms)));
+  const clock = injected.clock || Date.now;
+  if (flags.alpha3d) {
+    log('--hosted plays 2D Godot projects, so it cannot be used with --alpha-3d. Nothing was charged.');
+    return EXIT.ENVIRONMENT;
+  }
+  const setup = await (injected.resolveSetup || resolveSetup)(deps, { apiUrl: flags.apiUrl, repo: flags.repoRoot, game: flags.game, yes: flags.yes, godotPath: flags.godotPath }, log);
+  if (setup.code !== undefined) return setup.code;
+  const { context, api, gameId, repoRoot } = setup;
+
+  const games = Number(flags.games ?? DEFAULT_GAMES);
+  const steps = Number(flags.steps ?? DEFAULT_STEPS);
+  if (!Number.isInteger(games) || games < 1 || games > MAX_GAMES) { log(`--games must be a whole number from 1 to ${MAX_GAMES}. Nothing was charged.`); return EXIT.ENVIRONMENT; }
+  if (!Number.isInteger(steps) || steps < 1 || steps > MAX_STEPS) { log(`--steps must be a whole number from 1 to ${MAX_STEPS}. Nothing was charged.`); return EXIT.ENVIRONMENT; }
+
+  let labs = null;
+  try { labs = await api.labs.get(gameId); } catch { labs = null; }
+  if (!capabilityLive(labs, 'validate')) {
+    log('Validate changes is part of Ravensight Labs (beta), and it is not on for this game. Turn Labs on from the Labs page. Nothing was charged.');
+    return EXIT.ENVIRONMENT;
+  }
+
+  // Before any debit: the comparison's own switch, the funding rule and the price.
+  let offer, capabilities;
+  try {
+    capabilities = await api.hosted.capabilities(gameId);
+    offer = capabilities.hostedValidate;
+  } catch (error) {
+    log(`${String(error.message).slice(0, 500)} Nothing was charged.`);
+    return EXIT.ENVIRONMENT;
+  }
+  if (offer?.reason === 'hosted_comparison_capacity') {
+    log('Hosted comparison is not available: it needs room for two runs at once and this service is set up for one. Waiting will not change that. Use the local comparison without --hosted. Nothing was charged.');
+    return EXIT.ENVIRONMENT;
+  }
+  if (!offer?.available || !capabilities.reservationOffer) {
+    log('Hosted comparison is not on for this game. Use the local comparison without --hosted. Nothing was charged.');
+    return EXIT.ENVIRONMENT;
+  }
+  if (capabilities.funding && capabilities.funding.initialFundingMet === false) {
+    log(`Hosted runs need ${money(capabilities.funding.minimumFundingCents)} of verified top-ups first, and ${money(capabilities.funding.requiredTopUpCents)} more would meet it. Nothing was charged.`);
+    return EXIT.ENVIRONMENT;
+  }
+
+  // A price nobody can confirm is not a price anyone accepted.
+  const confirm = injected.confirm || deps.ui?.confirm;
+  if (!flags.yes && !confirm) {
+    log('This spends prepaid balance and there is no way to ask you here. Pass --yes to accept the price. Nothing was charged.');
+    return EXIT.ENVIRONMENT;
+  }
+
+  const project = path.resolve(repoRoot, flags.godotProject || context.config?.godot_project || '.');
+  const subdir = path.relative(repoRoot, project);
+  if (subdir.startsWith('..')) { log('The Godot project has to be inside this repository so its commits can be extracted. Nothing was charged.'); return EXIT.ENVIRONMENT; }
+
+  const checkout = injected.checkoutRef || checkoutRef;
+  const pack = injected.buildPack || buildPack;
+  const detect = injected.detectGodot || detectGodotBinary;
+  const baseRef = flags.base || await defaultBase(repoRoot);
+  const headRef = head || 'HEAD';
+  let godot;
+  try {
+    godot = await detect({ explicitPath: flags.godotPath, env: process.env, projectDir: project });
+  } catch (error) {
+    log(`${error.message} Nothing was charged.`);
+    return EXIT.ENVIRONMENT;
+  }
+  // A pack from another engine does not load on the one in the hosted image.
+  if (majorMinor(godot.version) !== (offer.engine || HOSTED_GODOT)) {
+    log(`Hosted comparison plays on Godot ${offer.engine || HOSTED_GODOT}, and this is Godot ${godot.version}. Use --godot-path with a ${offer.engine || HOSTED_GODOT} editor, or use the local comparison without --hosted. Nothing was charged.`);
+    return EXIT.ENVIRONMENT;
+  }
+
+  const sides = {};
+  try {
+    for (const [name, ref] of [['base', baseRef], ['head', headRef]]) {
+      const checked = await checkout({ repoRoot, ref, projectSubdir: subdir, godotPath: godot.path });
+      try {
+        // Measured on 2D only, so a 3D project is refused here, free, before any export or deposit.
+        const { dimension } = await (injected.dimensionGate || dimensionGate)({ projectDir: checked.projectDir, alpha3d: false, name: 'Validate changes' });
+        if (dimension === DIMENSION_3D) throw new Error(`${ref}: --hosted plays 2D Godot projects, and this main scene has a 3D root. Leave off --hosted to validate it on this machine with --alpha-3d.`);
+        log(`Exporting ${name} ${ref} (${checked.sha.slice(0, 12)}).`);
+        sides[name] = { ref, sha: checked.sha, built: await pack({ projectDir: checked.projectDir, godotPath: godot.path }) };
+      } finally { await checked.cleanup?.(); }
+    }
+  } catch (error) {
+    log(`${String(error.message).slice(0, 500)} Nothing was charged.`);
+    return EXIT.ENVIRONMENT;
+  }
+  if (sides.base.sha === sides.head.sha) { log('The base and the head are the same commit, so there is nothing to compare. Nothing was charged.'); return EXIT.ENVIRONMENT; }
+  if (sides.base.built.sha256 === sides.head.built.sha256) { log('The base and the head export to the same game pack, so they play the same. Nothing was charged.'); return EXIT.OK; }
+
+  const seed = flags.seed || `validate-${sides.base.sha.slice(0, 12)}-${sides.head.sha.slice(0, 12)}`;
+  const created = [];
+  let quote, pair;
+  // A deposit taken in this run comes back when its build is deleted; say which way it went.
+  const release = async () => {
+    if (!created.length) return;
+    const dropped = [], kept = [];
+    for (const build of created) {
+      try { await api.hosted.deleteBuild(gameId, build.buildId); dropped.push(build); } catch { kept.push(build); }
+    }
+    const each = capabilities.reservationOffer.amountCents;
+    if (dropped.length) log(`The ${money(each * dropped.length)} held for this run comes back once its upload is cleaned up, within minutes.`);
+    for (const build of kept) log(`${money(each)} stays held on build ${build.buildId} until it expires${build.expiresAt ? ` (${build.expiresAt})` : ''}, then comes back.`);
+  };
+  try {
+    const known = (await api.hosted.builds(gameId)).builds;
+    const fresh = [sides.base.built, sides.head.built].filter(built => !known.some(build => build.sha256 === built.sha256 && ['ready', 'awaiting_validation'].includes(build.state))).length;
+    const deposit = fresh * capabilities.reservationOffer.amountCents;
+    log(`This comparison is ${money(offer.totalPriceCents)}: ${money(offer.computePriceCents)} for two machines and ${money(offer.comparisonPriceCents)} for the comparison.`);
+    log(`${deposit ? `Uploading takes ${money(deposit)} now as deposits toward that` : 'Nothing is taken by uploading'}, and the rest is taken when it starts.`);
+    log(`If a build fails to run: its machine is ${offer.customerFailure === 'refund' ? 'refunded' : 'kept'}. If you cancel after a machine started: it is ${offer.cancelAfterStart === 'refund' ? 'refunded' : 'kept'}. A machine failing on our side is refunded.`);
+    if (offer.timeLimit) log(offer.timeLimit === 'refund' ? 'If a game reaches the time limit: its machine and the comparison are refunded.' : 'If a game reaches the time limit and left results: its machine is kept and the comparison is refunded. With no results, both are refunded.');
+    if (Number.isFinite(offer.minimumBalanceCents)) log(`A balance of ${money(offer.minimumBalanceCents)} is needed to start, counting any deposits. Only the price is charged.`);
+    if (!flags.yes && !await confirm(`Upload and start this comparison for ${money(offer.totalPriceCents)}?`, { yes: flags.yes })) { log('Stopped. Nothing was charged.'); return EXIT.OK; }
+    const fetchImpl = injected.fetch || fetch;
+    const base = await ensureBuild({ api, gameId, built: sides.base.built, sleep, fetchImpl, log, label: 'base', clock, created });
+    const headBuild = await ensureBuild({ api, gameId, built: sides.head.built, sleep, fetchImpl, log, label: 'head', clock, created });
+    quote = await api.hosted.quotePair(gameId, { baseBuildId: base.buildId, headBuildId: headBuild.buildId, simulation: simulationFor({ seed, games, steps }) });
+    if (quote.funding && quote.funding.eligible === false) {
+      log(`Add ${money(quote.funding.requiredTopUpCents)} of prepaid balance to start.${Number.isFinite(quote.funding.minimumBalanceCents) ? ` This comparison needs ${money(quote.funding.minimumBalanceCents)} available to start, though only its price is charged.` : ''}`);
+      await release();
+      return EXIT.ENVIRONMENT;
+    }
+    // The price the prompt named is the price, or the person is asked again.
+    if (quote.totalPriceCents !== offer.totalPriceCents && !flags.yes && !await confirm(`The price is now ${money(quote.totalPriceCents)}. Start it?`, { yes: flags.yes })) {
+      log('Stopped.');
+      await release();
+      return EXIT.OK;
+    }
+    // One pair of quotes is one key, so a retry reaches a pair the server already committed.
+    const pairKey = `pair-${createHash('sha256').update(`${gameId}:${quote.baseQuoteId}:${quote.headQuoteId}`).digest('hex').slice(0, 40)}`;
+    const body = {
+      baseQuoteId: quote.baseQuoteId, headQuoteId: quote.headQuoteId, totalPriceCents: quote.totalPriceCents, dueNowCents: quote.dueNowCents,
+      priceVersion: quote.priceVersion, policyVersion: quote.policyVersion,
+      refs: { base: { ref: sides.base.ref, sha: sides.base.sha }, head: { ref: sides.head.ref, sha: sides.head.sha } }
+    };
+    let unanswered = null;
+    for (let attempt = 0; attempt < PAIR_ATTEMPTS && !pair; attempt += 1) {
+      try {
+        pair = await api.hosted.createPair(gameId, body, pairKey);
+      } catch (error) {
+        // A 4xx is the server saying no, and only that proves nothing was committed, along
+        // with the one 503 that says a pair can never fit, which is decided before any write.
+        if ((error.status >= 400 && error.status < 500) || error.code === 'hosted_comparison_capacity') throw error;
+        unanswered = error;
+        if (attempt + 1 < PAIR_ATTEMPTS) await sleep(BUILD_POLL_MS);
+      }
+    }
+    if (!pair) {
+      log(`The server did not answer (${String(unanswered.message).slice(0, 200)}), so this comparison may have started. Your builds and deposits are left as they are. Check the jobs page before trying again.`);
+      return EXIT.ENVIRONMENT;
+    }
+  } catch (error) {
+    log(`${String(error.message).slice(0, 500)}`);
+    await release();
+    return EXIT.ENVIRONMENT;
+  }
+  log(`Comparison ${pair.pairId} started.`);
+  const link = jobLink(gameId, pair.base.jobId, setup.apiUrl);
+  if (link) log(`Follow it at ${link}`);
+  if (flags.wait === false) {
+    if (flags.json) console.log(JSON.stringify(pair));
+    return EXIT.OK;
+  }
+
+  const deadline = clock() + WAIT_MS;
+  while (pair.state !== 'settled' && !pair.underReview && clock() < deadline) {
+    await sleep(POLL_MS);
+    try { pair = await api.hosted.readPair(gameId, pair.pairId); } catch (error) { if (error.status === 404) throw error; }
+  }
+  if (flags.json) console.log(JSON.stringify(pair));
+  if (pair.state !== 'settled' && pair.underReview) {
+    log(`Comparison ${pair.pairId} is under review: a machine ended without a result, so a person decides what it cost. The money stays where it is until then, and the job page shows the outcome.`);
+    return EXIT.OK;
+  }
+  if (pair.state !== 'settled') {
+    log(`Comparison ${pair.pairId} is still running. The job page shows it when it finishes.`);
+    return EXIT.OK;
+  }
+  for (const line of comparisonLines(pair)) log(line);
+  if (flags.failOnRegression && pair.report?.verdict !== 'matched') return EXIT.FAILED;
+  return pair.report ? EXIT.OK : EXIT.FAILED;
+}

package/src/create/scaffold.js

@@ -0,0 +1,192 @@
+import { createHash } from 'node:crypto';
+import { execFile } from 'node:child_process';
+import { chmod, cp, mkdir, readdir, readFile, rm, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { promisify } from 'node:util';
+
+/**
+ * The scaffold `ravensight-playtest create` writes: a versioned Godot 4 2D template
+ * from this package, with this game's name, its design beside it and its development
+ * key on this machine only. Nothing is generated: the code is the template's and the
+ * art is placeholder primitives, because a studio's own assets arrive later.
+ *
+ * The SDK in the template is the public release, byte for byte, as a customer would
+ * download it. `template.json` pins its tag and digest, and `readTemplate` refuses a
+ * package where that no longer holds.
+ */
+
+const execFileAsync = promisify(execFile);
+
+export const TEMPLATE_DIR = fileURLToPath(new URL('../../templates/godot-2d/', import.meta.url));
+/** The 3D Alpha's template. `create` never uses it: it starts from `template godot-3d`. */
+export const TEMPLATE_3D_DIR = fileURLToPath(new URL('../../templates/godot-3d/', import.meta.url));
+export const KEY_FILE = 'ravensight_key.cfg';
+const NAME_TOKEN = /__GAME_NAME__/g;
+/** Files that name the game. Nothing else is rewritten. */
+const NAMED_FILES = Object.freeze(['project.godot', 'README.md']);
+
+/**
+ * The template's manifest, with its pinned SDK proved.
+ *
+ * @param {string} [dir]
+ * @returns {Promise<Object>}
+ */
+export async function readTemplate(dir = TEMPLATE_DIR) {
+  const manifest = JSON.parse(await readFile(path.join(dir, 'template.json'), 'utf8'));
+  const sdk = await readFile(path.join(dir, manifest.sdk.path));
+  const digest = createHash('sha256').update(sdk).digest('hex');
+  if (digest !== manifest.sdk.sha256) throw new Error(`The template's SDK does not match its pinned digest (${manifest.sdk.tag}).`);
+  return manifest;
+}
+
+/** A string safe inside a quoted Godot value, on one line. */
+export function godotString(value) {
+  return String(value).replace(/[\r\n]+/g, ' ').replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+}
+
+/**
+ * The key file: this game's own key, and the API it talks to. Mode 600 and ignored
+ * by git. The key is only ever written here, and never printed.
+ *
+ * @param {{dir: string, ingestKey: string, apiUrl: string}} input
+ */
+export async function writeKeyFile({ dir, ingestKey, apiUrl }) {
+  const file = path.join(dir, KEY_FILE);
+  await writeFile(file, `[ravensight]\ningest_key="${godotString(ingestKey)}"\napi_url="${godotString(apiUrl)}"\n`, { mode: 0o600 });
+  await chmod(file, 0o600);
+  return file;
+}
+
+/** The approved design, as the file a developer and the model both read. */
+export function designMarkdown(design, { declared = null } = {}) {
+  const out = [
+    `# ${design.title}`,
+    '',
+    design.pitch,
+    '',
+    '## Core loop',
+    '',
+    design.core_loop.summary,
+    '',
+    ...design.core_loop.player_steps.map((step, index) => `${index + 1}. ${step}`),
+    '',
+    `Done when: ${design.core_loop.done_when}`,
+    '',
+    'Call `GameState.complete_core_loop()` once for each pass of it.',
+    '',
+    '## Controls',
+    '',
+    ...design.controls.map(control => `- \`${control.action}\`: ${control.meaning}`),
+    '',
+    `How to start: ${design.how_to_start}`,
+    '',
+    `Success: ${design.success_criteria}`,
+    '',
+    '## Milestones',
+    ''
+  ];
+  design.milestones.forEach((milestone, index) => {
+    const past = declared !== null && index >= declared ? ' (past the declared count, so not bought)' : '';
+    out.push(`${index + 1}. **${milestone.title}**${past}: ${milestone.summary}`);
+  });
+  out.push('', '## Placeholders', '', ...(design.placeholders.length ? design.placeholders.map(item => `- ${item}`) : ['None named.']), '');
+  return out.join('\n');
+}
+
+async function countFiles(dir) {
+  let total = 0;
+  for (const entry of await readdir(dir, { withFileTypes: true })) {
+    if (entry.name === '.git' || entry.name === '.ravensight' || entry.name === '.godot') continue;
+    total += entry.isDirectory() ? await countFiles(path.join(dir, entry.name)) : 1;
+  }
+  return total;
+}
+
+function git(dir, args) {
+  return execFileAsync('git', ['-C', dir, ...args], { maxBuffer: 16 * 1024 * 1024 });
+}
+
+/**
+ * Make `dir` a repository whose ignore file exists before anything else does, so the
+ * key that is already there can never be staged.
+ *
+ * @param {string} dir
+ * @param {{templateDir?: string}} [options]
+ */
+export async function initRepository(dir, { templateDir = TEMPLATE_DIR } = {}) {
+  await mkdir(dir, { recursive: true });
+  await cp(path.join(templateDir, 'gitignore'), path.join(dir, '.gitignore'));
+  await git(dir, ['init', '-q', '-b', 'main']);
+}
+
+/** The author on a commit this command makes, when the machine has none set. */
+async function identityArgs(dir) {
+  const named = await git(dir, ['config', 'user.email']).then(answer => answer.stdout.trim()).catch(() => '');
+  return named ? [] : ['-c', 'user.name=Ravensight create', '-c', 'user.email=create@ravensight.invalid'];
+}
+
+/** Commit everything that is not ignored, here, on this branch. Never pushes. */
+export async function commitAll(dir, message) {
+  await git(dir, ['add', '-A']);
+  const { stdout } = await git(dir, ['status', '--porcelain']);
+  if (!stdout.trim()) return null;
+  await git(dir, [...await identityArgs(dir), 'commit', '-q', '-m', message]);
+  return (await git(dir, ['rev-parse', 'HEAD'])).stdout.trim();
+}
+
+/** Back to main with this branch's commit on it, only ever as a fast-forward. */
+export async function landOnMain(dir, branch) {
+  await git(dir, ['checkout', '-q', 'main']);
+  await git(dir, ['merge', '-q', '--ff-only', branch]);
+}
+
+export async function checkoutMain(dir) {
+  await git(dir, ['checkout', '-q', 'main']);
+}
+
+export async function currentBranch(dir) {
+  return (await git(dir, ['rev-parse', '--abbrev-ref', 'HEAD'])).stdout.trim();
+}
+
+export async function hasCommit(dir) {
+  return git(dir, ['rev-parse', '--verify', '-q', 'HEAD']).then(() => true).catch(() => false);
+}
+
+/**
+ * Copy the template in, name it, write the design beside it, and commit. Only ever
+ * on an empty repository: a scaffold never lands on top of somebody's work, and the
+ * caller's key file is left alone because it was written first and is ignored.
+ *
+ * @param {{dir: string, name: string, design?: Object|null, declared?: number, templateDir?: string}} input
+ * @returns {Promise<{manifest: Object, files: number, commit: string}>}
+ */
+export async function writeScaffold({ dir, name, design, declared, templateDir = TEMPLATE_DIR }) {
+  const manifest = await readTemplate(templateDir);
+  await cp(templateDir, dir, {
+    recursive: true,
+    force: true,
+    filter: source => {
+      const relative = path.relative(templateDir, source);
+      return relative !== 'gitignore' && relative !== 'template.json';
+    }
+  });
+  for (const file of NAMED_FILES) {
+    const full = path.join(dir, file);
+    const safe = file === 'project.godot' ? godotString(name) : String(name).replace(/[\r\n]+/g, ' ');
+    await writeFile(full, (await readFile(full, 'utf8')).replace(NAME_TOKEN, () => safe));
+  }
+  if (design) await writeFile(path.join(dir, 'DESIGN.md'), designMarkdown(design, { declared }));
+  // Which template this came from, for a later reader.
+  await writeFile(path.join(dir, '.ravensight-template.json'), `${JSON.stringify({ template: manifest.name, version: manifest.version, sdk: manifest.sdk.version }, null, 2)}\n`);
+  const commit = await commitAll(dir, `Scaffold ${String(name).replace(/[\r\n]+/g, ' ')} from the ${manifest.name} template ${manifest.version}`);
+  return { manifest, files: await countFiles(dir), commit };
+}
+
+/** Removes a directory this command created and nothing else has used. */
+export async function discard(dir) {
+  await rm(dir, { recursive: true, force: true });
+}
+
+
+export default { readTemplate, writeKeyFile, designMarkdown, initRepository, commitAll, landOnMain, checkoutMain, currentBranch, hasCommit, writeScaffold, godotString, TEMPLATE_DIR, TEMPLATE_3D_DIR, KEY_FILE };