@looop-games/cli 0.1.7 → 0.1.8

package/lib/feedback.mjs

@@ -8,18 +8,117 @@
 // looop.engine pin, and this CLI's version. A delivered file is stamped
 // `sent:` + `id:` in its frontmatter so it never ships twice; a failed send
 // leaves the file unstamped and is retried on the next run.
-import { readdirSync, readFileSync, writeFileSync, existsSync } from 'node:fs';
-import { basename, join } from 'node:path';
+import { readdirSync, readFileSync, writeFileSync, existsSync, statSync, realpathSync } from 'node:fs';
+import { basename, join, resolve, relative, isAbsolute, sep } from 'node:path';
 import { findProject } from './project.mjs';
 import { getToken, getApiBase } from './config.mjs';
 import { DEFAULT_API_BASE } from './llm-shim.mjs';
 
 const CLI_VERSION = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version;
 
+// Attachment caps. The riven report cited game.js:56 and riven-render.js:302 —
+// source files, not screenshots — so attachments are TEXT. Kept well under the
+// intake's own ceiling so an oversized set is caught HERE, with a readable
+// message: Cloudflare replaces a Pages Function's 5xx body with its own HTML
+// page, which would reach the creator as an unreadable wall.
+export const MAX_ATTACHMENTS = 20;
+export const MAX_ATTACHMENT_BYTES = 256 * 1024; // per file
+export const MAX_ATTACHMENTS_BYTES = 1024 * 1024; // all of them together
+
+const frontmatter = (text) => /^---\n([\s\S]*?)\n---/.exec(text)?.[1] ?? '';
+
 // A report is "sent" when its frontmatter carries a `sent:` stamp.
 function isSent(text) {
-  const fm = /^---\n([\s\S]*?)\n---/.exec(text);
-  return fm ? /^sent:\s*\S/m.test(fm[1]) : false;
+  return /^sent:\s*\S/m.test(frontmatter(text));
+}
+
+// `attachments:` in the report's frontmatter, in either YAML shape agents write:
+//
+//   attachments:          attachments: [game.js, src/render.js]
+//     - game.js
+//     - src/render.js
+export function parseAttachments(text) {
+  const fm = frontmatter(text);
+  const inline = /^attachments:\s*\[(.*)\]\s*$/m.exec(fm);
+  if (inline) {
+    return inline[1]
+      .split(',')
+      .map((s) => s.trim().replace(/^['"]|['"]$/g, ''))
+      .filter(Boolean);
+  }
+  const block = /^attachments:\s*$/m.exec(fm);
+  if (!block) return [];
+  const out = [];
+  for (const line of fm.slice(block.index).split('\n').slice(1)) {
+    const item = /^\s*-\s*(.+?)\s*$/.exec(line);
+    if (!item) break; // the list ends at the first non-item line
+    out.push(item[1].replace(/^['"]|['"]$/g, ''));
+  }
+  return out;
+}
+
+// The agent chooses this list, so it is arbitrary filesystem read access over a
+// network. Every path must land inside the game folder — resolved, not merely
+// inspected, because a symlink's string looks innocent. An escape is a hard
+// error, never a skipped file.
+function readAttachments(projectDir, paths, reportName) {
+  if (paths.length > MAX_ATTACHMENTS) {
+    throw new Error(
+      `${reportName} lists ${paths.length} attachments (max ${MAX_ATTACHMENTS}) — attach only the files the diagnosis rests on.`,
+    );
+  }
+
+  const root = realpathSync(projectDir);
+  const inside = (candidate) => candidate === root || candidate.startsWith(root + sep);
+  const escaped = (p, resolved) => {
+    throw new Error(
+      `${reportName} attaches "${p}", which resolves outside the game folder (${resolved}). ` +
+        `Feedback may only attach files from this game.`,
+    );
+  };
+
+  const files = [];
+  let total = 0;
+
+  for (const p of paths) {
+    // Containment is checked BEFORE existence, and on the lexical path first:
+    // "../../.ssh/id_rsa" is refused for what it asks for, not for whether it
+    // happens to be there. Then again after realpath — a symlink's string looks
+    // perfectly innocent.
+    const full = resolve(root, p);
+    if (isAbsolute(p) || !inside(full)) escaped(p, full);
+
+    let real;
+    try {
+      real = realpathSync(full);
+    } catch {
+      throw new Error(`${reportName} attaches "${p}", which does not exist in the game folder.`);
+    }
+    if (!inside(real)) escaped(p, real);
+    if (!statSync(real).isFile()) throw new Error(`${reportName} attaches "${p}", which is not a file.`);
+
+    const bytes = statSync(real).size;
+    if (bytes > MAX_ATTACHMENT_BYTES) {
+      throw new Error(
+        `${reportName} attaches "${p}" (${Math.round(bytes / 1024)} KiB) — too large, the per-file cap is ${MAX_ATTACHMENT_BYTES / 1024} KiB.`,
+      );
+    }
+    total += bytes;
+    if (total > MAX_ATTACHMENTS_BYTES) {
+      throw new Error(
+        `${reportName}'s attachments are too large together (over ${MAX_ATTACHMENTS_BYTES / 1024} KiB) — attach fewer files.`,
+      );
+    }
+
+    const content = readFileSync(real, 'utf8');
+    if (content.includes('\0')) {
+      throw new Error(`${reportName} attaches "${p}", which is not a text file. Attach source, logs, or config.`);
+    }
+    // Report the path the creator wrote (project-relative), not the real one —
+    // it is what the report's prose cites.
+    files.push({ path: relative(root, real).split(sep).join('/'), content });
+  }
+  return files;
 }
 
 function titleOf(text, path) {
@@ -61,12 +160,16 @@ export async function sendFeedback({
   const sent = [];
   for (const path of unsent) {
     const body = readFileSync(path, 'utf8');
+    // Read + guard the attachments BEFORE the request: a bad path must fail the
+    // send outright, leaving the report unstamped and retryable.
+    const files = readAttachments(project.dir, parseAttachments(body), basename(path));
     const report = {
       title: titleOf(body, path),
       body,
       slug: project.slug,
       engine: project.pkg?.looop?.engine,
       cli: CLI_VERSION,
+      ...(files.length ? { files } : {}),
     };
     const res = await fetch(`${apiBase}/api/creator/feedback`, {
       method: 'POST',
@@ -79,8 +182,9 @@ export async function sendFeedback({
     }
     const { id } = await res.json();
     writeFileSync(path, stamp(body, id));
-    log(`✅ Sent ${basename(path)} → ${id}`);
-    sent.push({ file: path, id });
+    const withFiles = files.length ? ` (+${files.length} file${files.length === 1 ? '' : 's'})` : '';
+    log(`✅ Sent ${basename(path)}${withFiles} → ${id}`);
+    sent.push({ file: path, id, files: files.map((f) => f.path) });
   }
   log(`${sent.length} report${sent.length === 1 ? '' : 's'} delivered to the Looop team.`);
   return { sent };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@looop-games/cli",
-  "version": "0.1.7",
+  "version": "0.1.8",
   "description": "Looop game development CLI — dev server, login, and publishing for standalone Looop games.",
   "type": "module",
   "license": "Apache-2.0",

package/template/.claude/skills/feedback/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: feedback
-description: File feedback to the Looop team when something in Looop ITSELF seems broken or missing — the engine, a shared component, the looop CLI, login, publishing, the platform. Use the moment you or the creator notice "this looks like a Looop bug, not our game" — offer to file it right away, don't wait to be asked.
+description: File feedback to the Looop team when something in Looop ITSELF is broken or missing — the engine, a shared component, the looop CLI, login, publishing, the platform. Use the moment you or the creator think "this looks like a Looop bug, not our game" — AND, just as importantly, whenever you discover your own game breaking a Looop rule, because Looop's own instructions may be what put it there. Offer to file it right away; don't wait to be asked.
 ---
 
 # /feedback — tell Looop when Looop is the problem
@@ -13,6 +13,34 @@ that lied, a missing capability every game would want — **offer to file it**:
 
 This game's own bugs are NOT feedback — they're `/todo`s or just fixes.
 
+## The defect you will not notice
+
+There is one class of Looop bug the reflex above is blind to, and it is the most
+valuable class there is: **a defect Looop's own guidance caused.**
+
+It looks like this. You discover your game violating a Looop rule — it's routing
+state the wrong way, using an API it shouldn't. The symptom is in *your* code, so
+the conclusion writes itself: *"our bug, not the engine's."* You fix your game and
+move on, and Looop never hears about it.
+
+That inference is locally correct and globally wrong. **Looop's instructions are
+not a fixed point — they are a suspect.** They contradict each other sometimes.
+The mandatory ones (this repo's `AGENTS.md`, injected into every session) can be
+wrong while an opt-in practices doc is right, and you will have followed the
+mandatory one without ever noticing there was a choice.
+
+So, the rule:
+
+> **When you find your game violating a Looop rule, work out what led you there
+> BEFORE you fix it.**
+
+Retrace it honestly. Did a Looop-authored source — `AGENTS.md`, a
+`shared/practices/` doc, a library README, a skill — point you this way? If yes,
+**that is a Looop defect and it gets filed**, even though your game is also wrong.
+Both are true at the same time; fix your game *and* file the report. If you'd have
+made the same mistake with no guidance at all, it's just your bug — fix it and
+move on.
+
 ## What to file
 
 Write the report to `notes/feedback/<YYYY-MM-DD-HHMM>-<short-slug>.md`
@@ -26,6 +54,9 @@ detail you leave out is a detail they'll have to guess. Include:
 created: YYYY-MM-DD
 engine: <the looop.engine pin from package.json>
 cli: <@looop-games/cli version from package.json devDependencies>
+attachments:
+  - game.js
+  - src/net.js
 ---
 # <One line: what's wrong>
 
@@ -40,6 +71,10 @@ custom port, offline, …).
 The smallest steps/snippet that shows it. Exact commands **with their full
 output pasted verbatim** — never summarize an error message.
 
+## What led us here (if a Looop source did)
+The file and line that pointed you wrong, quoted, and the doc that contradicts
+it. This is the section that gets the guidance itself fixed.
+
 ## Transcript
 The conversation that surfaced this, quoted verbatim — from the creator's
 request that first hit the problem through your diagnosis: what they asked,
@@ -54,18 +89,37 @@ Trim game-specific noise, never evidence: cut what's irrelevant to the
 defect, keep everything that shows it. (The intake caps a report at 256 KiB —
 if the transcript pushes past that, cut it down to the relevant exchange.)
 
+## Attach the files you're talking about
+
+A report that cites `game.js:56` is only as good as the reader's ability to see
+line 56. **List the files your diagnosis rests on in the `attachments:`
+frontmatter** — they ship with the report, and the team reads them beside it.
+
+This applies to **any** report, whatever its reason: a bug, a missing capability,
+a rule that led you wrong, a module you had to fork. Whatever your evidence is,
+attach it.
+
+- **You pick the files** — you wrote the diagnosis, so you know what it rests on.
+- Paths are **relative to the game folder** and must stay inside it. Anything
+  pointing outside is refused outright.
+- **Text only** (source, logs, config) — up to 20 files, 256 KiB each, 1 MiB total.
+- Attach what the report *argues from*: the file with the bug, the module you
+  worked around, the config that reproduces it. Not the whole game.
+
 ## Send it
 
 1. Run **`npx looop feedback`** — it delivers every unsent report under
    `notes/feedback/` to the Looop team (login required; it's the same account
-   as publishing) and stamps each delivered file with `sent:` + `id:` in its
-   frontmatter so it never ships twice.
-2. If the send fails (offline, not logged in), the file stays unstamped —
-   just run `npx looop feedback` again later; it retries everything unsent.
+   as publishing), attachments included, and stamps each delivered file with
+   `sent:` + `id:` in its frontmatter so it never ships twice.
+2. If the send fails (offline, not logged in, a bad attachment path), the file
+   stays unstamped — fix what it says and run `npx looop feedback` again; it
+   retries everything unsent.
 
 ## Why bother
 
 An override that patches an engine bug is a fork that stops receiving updates;
-feedback is how the fix lands upstream so the fork can be deleted. And a
-missing capability filed from a real game is exactly how the engine decides
-what to build next.
+feedback is how the fix lands upstream so the fork can be deleted. A missing
+capability filed from a real game is exactly how the engine decides what to build
+next. And a rule that led you wrong will lead **every** creator wrong, in every
+game, until somebody says so.