qiksy-mcp 1.53.0 → 1.63.0

package/README.md

@@ -155,6 +155,20 @@ take twenty again. These three keep the flow on your machine, in field NAMES:
 The recipe is a plain JSON file you own — editable, deletable, never uploaded.
 `QIKSY_RECIPES_DIR` moves the folder (e.g. into the project, to share flows with a team).
 
+### Reports land in the project, not in a download folder
+
+This process is started **from the folder you work in**, so it knows which project a run is about
+and files the paperwork there. `qa_report_build` with no `out` writes
+`qiksy-reports/<date>-<subject>.html` under that folder, and the reply carries the path. The
+panel's own **Report** button goes to the same place while the bridge is connected, and falls back
+to an ordinary browser download when it is not — the toast says which of the two happened.
+
+Why there and not `~/.qiksy`, where the recipes live: a recipe is a tool, and the same login flow
+serves every project; a report is the work itself, attached to a ticket and read by somebody else,
+so it belongs beside the code it is about. `QIKSY_REPORTS_DIR` moves the folder, and `off` means
+write nothing unless a path is named. A folder with none of `.git` / `package.json` / `CLAUDE.md` /
+`AGENTS.md` is not treated as a project, and neither is your home directory.
+
 ### Pictures, and a shelf both hands can reach
 
 A screenshot usually leaves the tool the moment it is taken, and everything after that is

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "qiksy-mcp",
-  "version": "1.53.0",
+  "version": "1.63.0",
   "description": "Browser MCP server for the Chrome tab you already have open — your session, your logins. Gives Claude Code, Cursor, Codex and VS Code the live page: findings, forms, failed requests with server bodies.",
   "keywords": [
     "mcp",
@@ -33,6 +33,7 @@
     "widgets.mjs",
     "project.mjs",
     "gaps.mjs",
+    "reports.mjs",
     "gallery.mjs",
     "svg-shot.mjs",
     "connect.mjs",

package/reports.mjs

@@ -0,0 +1,78 @@
+/**
+ * WHERE A REPORT GOES WHEN NOBODY SAID.
+ *
+ * Owner, 28.09.2026: «чтобы Bridge понимал, в контексте какого это проекта, и в этой папке
+ * создавал» — reports that pile up in the browser's download folder belong to nobody, and a week
+ * later nothing says which of them was about which product.
+ *
+ * The bridge already knew the answer and was not using it: this process is started BY the agent,
+ * FROM the folder the person is working in, and the docs installer already tests that folder for
+ * the marks of a project before writing its guide into it. The same test decides here.
+ *
+ * WHY NOT ~/.qiksy, WHERE THE RECIPES LIVE. A recipe is a tool — the same login flow serves every
+ * project, so it is filed by project INSIDE our folder. A report is the work itself: it is
+ * attached to a ticket, read by a client, and it belongs with the code it is about. Somebody who
+ * has never heard of this tool should find it by opening the project.
+ *
+ * Kept out of server.mjs so it can be held to account without a browser, a socket or a port —
+ * every decision here is a string and a file test, which is exactly the kind of thing that breaks
+ * quietly and is never noticed until somebody goes looking for a report that was never written.
+ */
+import { existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+
+/** The marks that make a folder somebody's project rather than somebody's home directory. */
+export const PROJECT_MARKS = ['.git', 'package.json', 'CLAUDE.md', 'AGENTS.md'];
+
+/**
+ * The folder the agent was started in, if it looks like a project.
+ *
+ * Deliberately NOT a walk up the tree: the agent is started in the folder the person is working
+ * in, and climbing from a subdirectory would file a report about one package into the root of a
+ * monorepo — quietly, and in the one place nobody would look for it. `home` is refused for the
+ * same reason a stray `rm` refuses it: a home directory is not a project, and writing into it is
+ * never what somebody meant.
+ */
+export function projectRoot({ cwd, home = homedir(), exists = existsSync } = {}) {
+  if (!cwd) return null;
+  const dir = resolve(cwd);
+  if (dir === resolve(home) || dirname(dir) === dir) return null;
+  return PROJECT_MARKS.some((m) => exists(join(dir, m))) ? dir : null;
+}
+
+/**
+ * Where reports go when the caller names no path: the project's own folder, an explicit override,
+ * or nowhere at all.
+ *
+ * `off` exists because writing a file is an act on somebody's disk, and a person who wants to be
+ * asked every time must have a way to say so that does not involve remembering an argument.
+ */
+export function reportsDir({ cwd, env = process.env, home = homedir(), exists = existsSync } = {}) {
+  const set = env.QIKSY_REPORTS_DIR;
+  if (set === 'off') return null;
+  if (set) return resolve(set);
+  const root = projectRoot({ cwd, home, exists });
+  return root ? join(root, 'qiksy-reports') : null;
+}
+
+const slug = (s) =>
+  String(s ?? '')
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 60);
+
+/**
+ * `2026-09-28-the-form-swallows-the-error.html` — sortable first, readable second.
+ *
+ * The subject comes from the document's own first block, because that is what the person called
+ * the thing; a name built from the host or the tool would file twenty reports about twenty
+ * different problems under one name and let the newest quietly replace the rest.
+ */
+export function reportFileName(blocks, kind, { now = new Date() } = {}) {
+  const first = (Array.isArray(blocks) ? blocks : []).find((b) => b && (b.title || b.text));
+  const subject = slug(first?.title || first?.text) || slug(kind) || 'report';
+  const day = now.toISOString().slice(0, 10);
+  return `${day}-${subject}.html`;
+}

package/server.mjs

@@ -34,6 +34,7 @@ import { fileURLToPath } from 'node:url';
 import { LIBRARIES, datePlan, hintsFor, recipeFor, classifyNode, classifySnapshot, classifyBehaviour, diffDigest } from './widgets.mjs';
 import { project } from './project.mjs';
 import { recordGap, listGaps, gapInvite, GAPS_FILE } from './gaps.mjs';
+import { reportsDir, reportFileName } from './reports.mjs';
 import { STATES, STATE_KEYS, renderGallery } from './gallery.mjs';
 import { renderSearchableSvg } from './svg-shot.mjs';
 import { connectAgents, toClipboard, pairingInPlace } from './connect.mjs';
@@ -1264,6 +1265,29 @@ function onConnection(ws, req) {
       ws.send(JSON.stringify({ t: 'pong', ts: msg.ts }));
       return;
     }
+    /* THE ONE THING THE BROWSER SIDE MAY ASK FOR: file this document under the project.
+     *
+     * Deliberately narrow. The extension sends a name and the bytes; THIS side decides the
+     * folder, because a directory chosen by the browser side is a directory chosen by a web page
+     * one bug later. The name is reduced to a bare file name for the same reason — `..` and `/`
+     * are how «a report» becomes «a file anywhere on this disk». Followers cannot use it: the
+     * frame is only honoured on the extension's own connection. */
+    if (msg.t === 'file' && msg.id && !isFollower) {
+      const reply = (ok, extra) => safeSend(ws, { t: 'filed', id: msg.id, ok, ...extra });
+      try {
+        const dir = whereReportsGo();
+        if (!dir) { reply(false, { error: 'no project folder here — the agent was started outside one, or QIKSY_REPORTS_DIR is off' }); return; }
+        const name = basename(String(msg.name || '')).replace(/[^\w.@-]+/g, '-').slice(0, 120) || 'report.html';
+        const full = join(dir, name);
+        mkdirSync(dir, { recursive: true });
+        writeFileSync(full, String(msg.content ?? ''), 'utf8');
+        log(`filed ${name} → ${dir}`);
+        reply(true, { path: full });
+      } catch (e) {
+        reply(false, { error: e?.message || String(e) });
+      }
+      return;
+    }
     // A follower's call: run it against the extension as if it were ours and hand the
     // answer back under the follower's own id. Ours is a fresh randomUUID, so the two
     // id spaces cannot collide.
@@ -1729,6 +1753,13 @@ function stepsFromJournal(url) {
 
 // ── Recipes on disk ────────────────────────────────────────────────────────────
 const RECIPES_DIR = process.env.QIKSY_RECIPES_DIR || join(homedir(), '.qiksy', 'recipes');
+
+/* REPORTS LAND IN THE PROJECT, NOT IN «DOWNLOADS» — the rules, and why, live in mcp/reports.mjs
+   so they can be held to account without a browser, a socket or a port. `cwd` is read here, at
+   the moment of use, because the folder can be deleted under a long-running process. */
+function whereReportsGo() {
+  try { return reportsDir({ cwd: process.cwd() }); } catch { return null; }
+}
 const slug = (s) =>
   String(s ?? '')
     .toLowerCase()
@@ -5044,7 +5075,7 @@ server.registerTool(
       'The reply is an INVENTORY — blocks, pictures embedded, findings, points, bytes, warnings — not the word «done».',
     inputSchema: {
       tabId: tabIdArg,
-      out: z.string().optional().describe('Write the HTML here. Without it the document comes back inline, which for a report with pictures in it is usually the wrong trade.'),
+      out: z.string().optional().describe('Write the HTML here. WITHOUT IT THE REPORT IS FILED UNDER THE PROJECT you are working in — `qiksy-reports/<date>-<subject>.html` next to the code it is about, because a report belongs with the thing it describes rather than in a download folder. The reply says the path either way. Set QIKSY_REPORTS_DIR to file them elsewhere, or to `off` to write nothing unless asked.'),
       save: z
         .union([z.boolean(), z.string()])
         .optional()
@@ -5066,13 +5097,20 @@ server.registerTool(
       const kept = r.saved
         ? { saved: r.saved, savedNote: 'kept in the extension: the panel’s Shots tab lists it under Reports, and qa_reports reads it back by that name' }
         : {};
-      if (out) {
-        const full = resolve(out);
-        mkdirSync(dirname(full), { recursive: true });
-        writeFileSync(full, r.html, 'utf8');
+      /* Named path wins; otherwise the project's own reports folder — see reportsDir(). */
+      const home = out ? null : whereReportsGo();
+      const target = out ? resolve(out) : (home ? join(home, reportFileName(blocks, kind)) : null);
+      if (target) {
+        mkdirSync(dirname(target), { recursive: true });
+        writeFileSync(target, r.html, 'utf8');
         /* The funnel's question has been answered by the act itself; it must not ask again. */
         for (const [host, v] of reportFunnel) reportFunnel.set(host, { ...v, built: true });
-        return asText({ ok: true, path: full, blocks: r.blocks, shotsEmbedded: r.shotsEmbedded, findings: r.findings, points: r.points, bytes: r.bytes, warnings: r.warnings, ...kept, note: 'Open it and print to PDF; the structure is the same on paper.' });
+        return asText({
+          ok: true, path: target, blocks: r.blocks, shotsEmbedded: r.shotsEmbedded, findings: r.findings,
+          points: r.points, bytes: r.bytes, warnings: r.warnings, ...kept,
+          ...(out ? {} : { filedIn: home, filedNote: 'No path was given, so it was filed under the project you are working in. Name `out` to put it somewhere else, or set QIKSY_REPORTS_DIR (or `off`) to change where this goes.' }),
+          note: 'Open it and print to PDF; the structure is the same on paper.',
+        });
       }
       return asText({ ok: true, blocks: r.blocks, shotsEmbedded: r.shotsEmbedded, findings: r.findings, points: r.points, bytes: r.bytes, warnings: r.warnings, ...kept, html: r.html });
     } finally {
@@ -6770,6 +6808,7 @@ server.registerTool(
       'Use it after anything whose answer arrives later than a click settles: an order confirmation, a slow save, a list that repopulates, a button that ungreys when validation finishes. ' +
       'A condition already true when you call returns immediately. ' +
       'ON TIMEOUT IT SAYS WHAT IT SAW — how many matched, how many were visible, the nearest names on the page, and anything announced — so a wait that failed on a typo tells you so instead of just running out. ' +
+      'A SIGN-IN IS WHAT THIS IS FOR, MORE THAN ANYTHING ELSE. When the site hands over to a password, a code from a phone or a hardware key, that step is the person\'s — do not drive it and do not call it a failure. Tell them to sign in, then `qa_wait_for { urlContains: "<the site you came from>", timeoutMs: 180000 }`: it is answered by the extension, so it survives the navigation, and if the tab never moves at all it says THAT instead of just running out. ' +
       'Read-only: waiting is not acting, so this needs no Pro and no consent — the same footing as qa_wait_ready. ' +
       'There is no "until quiet" (that is what every action already does) and no "until the network is idle" (the interceptor sees only the page\'s own fetch/XHR in the top frame, so the number would not mean what its name says).',
     inputSchema: {
@@ -6784,7 +6823,7 @@ server.registerTool(
       exactly: z.number().optional().describe('With countOf: wait until exactly this many match'),
       announced: z.union([z.string(), z.boolean()]).optional().describe('Wait until a live region speaks — a string waits for one containing it, true for any'),
       urlContains: z.string().optional().describe('Wait until the tab address contains this. Answered by the extension itself, so it survives the navigation it is waiting for.'),
-      timeoutMs: z.number().optional().describe('Give up after this long (default 15000, max 60000)'),
+      timeoutMs: z.number().optional().describe('Give up after this long (default 15000, max 60000 — or up to 300000 with urlContains, which is how you wait for a person to sign in)'),
     },
   },
   async (args) => {