ravensight-playtest 0.5.2 → 0.7.0

package/src/assets/index.js

@@ -0,0 +1,260 @@
+import { mkdir, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+
+import { checkResultText, RUN_CHECK_TOOL } from '../run/checks.js';
+import { ASSET_CHECK_NAMES, createAssetChecks, scanUsage } from './integration.js';
+import { buildInventory, countsLine, DEFAULT_ASSETS_DIR, describeFile, isMediaPath, manifestText, warningKinds } from './inventory.js';
+
+/**
+ * Bring your own assets: the one seam the feature and create loops call.
+ *
+ *   const assets = await prepareAssets({ repoRoot, projectDir, folder, grid });
+ *   if (!assets.ok) refuse with assets.reason, before any charge
+ *
+ *   plan prompt:   ...assets.planLines
+ *   apply prompt:  ...assets.instructions
+ *   repo tools:    assets.guardRepo(createRepoTools(...))            plan and apply
+ *   after checks:  const bound = assets.bindChecks({ checks, changedFiles, ... })
+ *   apply tools:   bound.withChecks(withRunCheck(guardedRepo, checks))
+ *   gate:          const gate = await bound.gate(await runGateChecks(checks, log), log)
+ *                  a failure joins gate.failed; gate.assetsBlock blocks the upload
+ *   placeholders:  assets.placeholders(plan, spec)
+ *   report:        const summary = await assets.report({ runDir, changed, placeholders, log })
+ *                  summary.reportLines go in the uploaded report
+ *
+ * The studio's files stay where they are. The server stores none of them, there is
+ * no price of its own, and nothing is generated. The manifest reaches the model
+ * through the same proxy every read does; the report that uploads carries counts
+ * and kinds of warning only, and the file-by-file list stays in the run directory.
+ */
+
+/** The path the model reads the manifest at. It is answered from memory: no file is written there. */
+export const MANIFEST_PATH = '.ravensight/assets.json';
+
+/** Written beside a run. Neither is on the upload allowlist, so neither can leave. */
+export const LOCAL_REPORT_FILE = 'assets-report.md';
+export const LOCAL_MANIFEST_FILE = 'assets.json';
+
+const REFUSED_CONTENT = file => `Refused: ${file} is an art or audio file. Its content is never read or sent. Its measurements are in ${MANIFEST_PATH}.`;
+const REFUSED_WRITE = file => `Refused: ${file} is the studio's art or audio. You cannot make or change those: use what ${MANIFEST_PATH} lists, or a placeholder primitive named in placeholders.`;
+
+function refusal(id, text) {
+  return { result: { type: 'tool_result', tool_use_id: id, content: [{ type: 'text', text }], is_error: true } };
+}
+
+function inFolder(file, folder) {
+  // Case blind: on macOS and Windows `ART/hero.tres` is `art/hero.tres`.
+  const normal = path.posix.normalize(String(file).split(path.sep).join('/')).replace(/^\.\//, '').toLowerCase();
+  const declared = folder ? folder.toLowerCase() : folder;
+  return declared && (normal === declared || normal.startsWith(`${declared}/`));
+}
+
+/**
+ * Repository tools that know about assets. The manifest can be read, art and audio
+ * cannot be read or quoted, and nothing can be written over them or into the
+ * declared folder, except the `.import` settings beside a file.
+ *
+ * @param {Object} repo a `createRepoTools` surface
+ * @param {{manifest: string, folder: string, prefix?: string}} input `prefix` is the project's path inside the repository
+ * @returns {Object}
+ */
+export function guardRepoTools(repo, { manifest, folder, prefix = '' }) {
+  const declared = prefix ? path.posix.join(prefix, folder) : folder;
+  return {
+    tools: repo.tools,
+    get written() {
+      return repo.written;
+    },
+    async execute(toolUse) {
+      const input = toolUse.input || {};
+      const target = String(input.path || '');
+      if (toolUse.name === 'read_file') {
+        if (path.posix.normalize(target) === MANIFEST_PATH) return manifestAnswer(toolUse, manifest, input);
+        if (isMediaPath(target)) return refusal(toolUse.id, REFUSED_CONTENT(target));
+      }
+      if (toolUse.name === 'write_file' || toolUse.name === 'edit_file') {
+        if (isMediaPath(target) || (inFolder(target, declared) && !target.endsWith('.import'))) return refusal(toolUse.id, REFUSED_WRITE(target));
+      }
+      const answer = await repo.execute(toolUse);
+      if (toolUse.name === 'grep') return withoutMediaLines(answer);
+      return answer;
+    }
+  };
+}
+
+function manifestAnswer(toolUse, manifest, input) {
+  const lines = manifest.split('\n');
+  const start = Math.max(1, Number(input.start_line) || 1);
+  const limit = Number(input.limit) || lines.length;
+  const text = lines.slice(start - 1, start - 1 + limit).join('\n');
+  return { result: { type: 'tool_result', tool_use_id: toolUse.id, content: [{ type: 'text', text }] } };
+}
+
+/** A grep result quotes the line it found, and a line of a PNG is file content. */
+function withoutMediaLines(answer) {
+  const block = answer && answer.result && answer.result.content && answer.result.content[0];
+  if (!block || typeof block.text !== 'string') return answer;
+  const kept = block.text.split('\n').filter(line => {
+    const match = /^(.+?):\d+: /.exec(line);
+    return !(match && isMediaPath(match[1]));
+  });
+  block.text = kept.join('\n') || '(no matches)';
+  return answer;
+}
+
+/** The run_check tool, with the asset checks in its list. */
+function assetRunCheckTool(tool) {
+  return {
+    ...tool,
+    description: `${tool.description} asset_references says whether every art or audio path you named exists; asset_import imports the project in Godot and reads what it made for each of them; pixel_art_settings says whether pixel art you named has the nearest filter and clean import settings.`,
+    input_schema: {
+      ...tool.input_schema,
+      properties: { check: { type: 'string', enum: [...tool.input_schema.properties.check.enum, ...ASSET_CHECK_NAMES] } }
+    }
+  };
+}
+
+/**
+ * The tool surface from `withRunCheck`, with the asset checks answerable too.
+ *
+ * @param {Object} surface
+ * @param {{run: Function}} assetChecks
+ * @param {{maxRuns?: number}} [options]
+ */
+export function withAssetChecks(surface, assetChecks, { maxRuns = 6 } = {}) {
+  let runs = 0;
+  return {
+    tools: surface.tools.map(tool => (tool.name === RUN_CHECK_TOOL.name ? assetRunCheckTool(tool) : tool)),
+    get written() {
+      return surface.written;
+    },
+    async execute(toolUse) {
+      const name = toolUse.input && toolUse.input.check;
+      if (toolUse.name !== RUN_CHECK_TOOL.name || !ASSET_CHECK_NAMES.includes(name)) return surface.execute(toolUse);
+      const answer = (text, isError = false) => ({ result: { type: 'tool_result', tool_use_id: toolUse.id, content: [{ type: 'text', text }], ...(isError ? { is_error: true } : {}) } });
+      if (runs >= maxRuns) return answer(`refused: ${maxRuns} asset checks have run this turn set, which is the limit`, true);
+      runs += 1;
+      const result = await assetChecks.run(name);
+      return answer(checkResultText(result), result.status === 'failed');
+    }
+  };
+}
+
+function planLinesFor(inventory) {
+  return [
+    '',
+    `<assets>The studio's own art and audio are listed in ${MANIFEST_PATH} (${countsLine(inventory.counts)}). Read that file with read_file before you plan any art or audio. List in "placeholders" only what the specification needs and that file does not cover; your list is final and replaces the specification's expected placeholders.</assets>`
+  ];
+}
+
+function instructionsFor(dimension) {
+  const primitives = dimension === '3d' ? 'a MeshInstance3D with a BoxMesh, a SphereMesh or a CapsuleMesh, or a Label' : 'a ColorRect, a Polygon2D or a Label';
+  return [
+    `Art and audio belong to the studio. Read ${MANIFEST_PATH} with read_file: it lists every file you may use, with its res_path and what was measured about it. Use those files by their res_path, and never invent a path, because a file not listed there does not exist. Do not try to read the files themselves; you cannot.`,
+    'Believe the measurements over a file\'s name or any size the specification assumes: size nodes from the width and height listed, and use the listed cell size for a sheet. A row\'s warnings say what will go wrong with that file, so work around them or say so in one line.',
+    `If something the feature needs is missing, build it with a placeholder primitive such as ${primitives}, and name it plainly in your final message and in the plan's placeholders. Never draw, write or fetch art or audio, and never suggest a tool or service for them.`,
+    'For a file with pixel_art true, set texture_filter = CanvasItem.TEXTURE_FILTER_NEAREST on the node that draws it, unless the manifest says the project default is already nearest. Before you finish, call run_check with asset_references, then asset_import.'
+  ];
+}
+
+/**
+ * The uploaded section of the report: counts, and kinds of warning with how many.
+ * It names no file, on purpose. Test this before changing it.
+ */
+export function reportLines({ inventory, usage, placeholderCount, localPath }) {
+  const lines = ['### Assets', ''];
+  if (inventory.counts.files === 0) {
+    lines.push(`The project has no files in its declared asset folder, so anything the feature needed is a placeholder (${placeholderCount}).`, '');
+    return lines;
+  }
+  lines.push(
+    `The declared asset folder holds ${countsLine(inventory.counts)}. This change wired in ${usage.wired.length}, the project now uses ${usage.used.length} and ${usage.unused.length} are unused. ${placeholderCount} placeholder(s) remain, named below.`,
+    '',
+    `Which files is on your machine only, in \`${localPath}\`. No file name from that list and no file content is uploaded.`,
+    ''
+  );
+  const kinds = warningKinds(inventory);
+  if (kinds.length > 0) {
+    lines.push('Warnings from the inventory:', '', ...kinds.map(item => `- ${item.count} x ${item.summary}`), '');
+  }
+  return lines;
+}
+
+function localReport({ inventory, usage, placeholders }) {
+  const list = (title, items, empty) => ['', `## ${title}`, '', ...(items.length ? items.map(item => `- ${item}`) : [empty])];
+  const warned = inventory.files.filter(file => file.warnings.length > 0);
+  const wired = new Set(usage.wired);
+  return [
+    '# Assets in this run',
+    '',
+    `Read from \`${inventory.folder}\`: ${countsLine(inventory.counts)}. This file stays on this machine.`,
+    ...list('Used', usage.used.map(name => `\`${name}\`${wired.has(name) ? ' (wired in by this change)' : ''}${usage.built_in_code.includes(name) ? ' (a path built in code, so a likely match)' : ''}`), 'None.'),
+    ...list('Unused', usage.unused.map(name => `\`${name}\``), 'None.'),
+    ...list('Placeholders still to supply', placeholders, 'None.'),
+    ...list('Warnings', [
+      ...inventory.warnings.map(item => item.text),
+      ...warned.flatMap(file => file.warnings.map(item => `\`${file.path}\`: ${item.text}`))
+    ], 'None.'),
+    ''
+  ].join('\n');
+}
+
+/**
+ * Inventory the declared folder and hand back everything a loop needs.
+ *
+ * A folder that was named and cannot be used is a refusal. The default folder being
+ * absent is not: that is a project with no assets yet, and the loop uses placeholders.
+ *
+ * @param {Object} input
+ * @param {string} input.repoRoot
+ * @param {string} input.projectDir
+ * @param {string} [input.folder] default `assets`
+ * @param {number|null} [input.grid] the grid the studio expects, for a warning
+ * @returns {Promise<Object>}
+ */
+export async function prepareAssets({ repoRoot, projectDir, folder, grid = null, dimension = '2d' }) {
+  const named = Boolean(folder);
+  const inventory = await buildInventory({ projectDir, folder: folder || DEFAULT_ASSETS_DIR, grid });
+  if (!inventory.ok) return { ok: false, reason: inventory.reason };
+  if (named && !inventory.exists) return { ok: false, reason: `There is no folder ${folder} in the project.` };
+
+  const prefix = path.relative(repoRoot, projectDir).split(path.sep).join('/');
+  const manifest = manifestText(inventory, prefix);
+  return {
+    ok: true,
+    inventory,
+    manifest,
+    planLines: planLinesFor(inventory),
+    instructions: instructionsFor(dimension),
+    guardRepo: repo => guardRepoTools(repo, { manifest, folder: inventory.folder, prefix }),
+    bindChecks: options => {
+      const bound = createAssetChecks({ projectDir, inventory, ...options });
+      return { ...bound, withChecks: surface => withAssetChecks(surface, bound) };
+    },
+    /** The plan read the manifest, so its list is the one that stands when it gave one. */
+    placeholders: (plan, spec) => {
+      const planned = plan && Array.isArray(plan.placeholders) ? plan.placeholders : null;
+      const expected = (spec && spec.placeholders) || [];
+      return [...new Set(planned || expected)].slice(0, 40);
+    },
+    /**
+     * Write the local files, print the names on this terminal, and answer the lines
+     * for the uploaded report.
+     */
+    report: async ({ runDir, changed = [], placeholders = [], log = () => {} }) => {
+      const usage = await scanUsage({ projectDir, inventory, changed });
+      await mkdir(runDir, { recursive: true });
+      await writeFile(path.join(runDir, LOCAL_MANIFEST_FILE), manifest, 'utf8');
+      await writeFile(path.join(runDir, LOCAL_REPORT_FILE), localReport({ inventory, usage, placeholders }), 'utf8');
+      const localPath = path.relative(repoRoot, path.join(runDir, LOCAL_REPORT_FILE)).split(path.sep).join('/');
+      if (inventory.counts.files > 0) log(`assets: ${usage.wired.length} wired in by this change, ${usage.used.length} used, ${usage.unused.length} unused. ${localPath}`);
+      for (const name of usage.wired) log(`  wired in: ${name}`);
+      return { usage, localPath, reportLines: reportLines({ inventory, usage, placeholderCount: placeholders.length, localPath }) };
+    }
+  };
+}
+
+export { buildInventory, describeFile, manifestText, warningKinds } from './inventory.js';
+export { ASSET_CHECK_NAMES, createAssetChecks, scanUsage } from './integration.js';
+
+export default prepareAssets;