@rmrdeveloper/sideroom-pi 8.13.0 → 9.0.0

package/README.md

@@ -91,7 +91,7 @@ wall of tool calls, it:
   each agent run, the agent must read the shared contract and the one complete
   guide matching the target language. Premature `write`/`edit` calls are
   blocked. The guides cover guard clauses, braced conditionals, fail-fast
-  errors, focused units, and all 19 canonical rules without dumping them into
+  errors, focused units, and all 20 canonical rules without dumping them into
   the system prompt.
 - **Finds the skills below the working directory.** In a trusted monorepo, Pi
   normally ignores project skills stored under child folders. Sideroom scans
@@ -149,8 +149,11 @@ a destination if several Pi sessions are open. Press `Alt+Shift+S` to select
 several elements without opening the popup; Escape or the shortcut exits.
 Review their local source candidates in Pi and send your
 instruction. The click prepares context; it never starts the agent. No project
-configuration or framework plugin is needed. Source ranges are real, but the
-DOM-to-source relationship is inferred and stays labelled as a candidate.
+configuration or framework plugin is needed for inferred source candidates.
+For more precise locations, ask Pi to enable visual compiler context in one
+project. It prepares the development dependency and configuration, including
+projects below your working folder. Compiler locations are checked against local
+markup; missing or mismatched locations stay unresolved.
 Download [the companion ZIP](https://github.com/RMRdeveloper/sideroom-pi/releases/latest/download/sideroom-browser-extension.zip)
 from GitHub Releases, extract it, and load its folder in your browser's developer mode.
 No extension store is required; installation and updates are manual. The same
@@ -190,15 +193,21 @@ scope and preserves behavior and compatibility. See
 ### Guidelines — a gate, not a novel
 
 A short system-prompt contract points at the packaged
-`sideroom-guidelines` skill. Before `write` or `edit`, a guard requires a
-full read of the packaged skill and, for supported targets, the one complete
-language guide under `skills/sideroom-guidelines/references/languages/`.
-Each guide mirrors all 19 rules in the canonical seed with idiomatic examples.
+`sideroom-guidelines` skill. Before `write` or `edit`, call
+`sideroom_guidelines` with the target file's `path` to load the complete skill
+and matching language guide from the packaged catalog. Unsupported languages
+load only the general skill. Full `read` calls of the packaged documents also
+satisfy the same guard; failed or incomplete loads do not. Reuse loaded guides
+in the same run and reload after compaction or a new run. Requires Pi and
+pi-tui 1.2.0 or later; call the tool directly, not through another tool.
+Each guide mirrors all 20 rules in the canonical seed with idiomatic examples.
 The seed, `assets/artifacts/GUIDELINES_TEMPLATE.md`, is never pasted into the
 system prompt. After any successful mutation, one hidden review steer fires when
 the turn settles and asks the agent to re-check every changed file against the
 loaded guide and run the relevant formatter, linter, type checks, and tests —
-so the contract is applied, not just read.
+so the contract is applied, not just read. Rule 20, Decomposition by intent,
+asks for coherent named operations that clarify the caller's flow, even with
+one caller. It keeps tightly coupled steps together and imposes no line limit.
 
 ### Monorepo skills — child skills are still project skills
 
@@ -231,7 +240,8 @@ to TypeSafe's decision model about the changed file and, when available, up to
 four directly related source files. It checks guard clauses, fail fast,
 command/query separation, null handling, immutability, repeated validation,
 responsibility, dependency direction, comments, testability, redundant
-abstractions, consumer compatibility and test quality only when the supplied
+abstractions, decomposition by intent, consumer compatibility and test quality
+only when the supplied
 files support the question. An answer above the cutoff travels with the
 end-of-run guidelines review instead of interrupting each edit. READMEs, JSON,
 lockfiles, deletion-only edits, and files outside the project are never sent.

package/assets/artifacts/GUIDELINES_TEMPLATE.md

@@ -1,6 +1,6 @@
 # Coding Guidelines
 
-Rules every change in this repo must follow. Ordered by how often they're violated and how cheap they are to check — mechanical rules first, judgment calls last.
+Rules every change in this repo must follow. The index identifies mechanical checks and rules that need review judgment.
 
 **Adapting this template to a new language:** keep `RULE` and `WHY` text as-is unless the language genuinely doesn't support the concept (e.g. Python has no braces — see rule 1). Swap the code fence language tag and rewrite the bad/good snippet idiomatically. Do not add prose. Do not merge two rules into one section.
 
@@ -27,6 +27,7 @@ Rules every change in this repo must follow. Ordered by how often they're violat
 | 17 | [Dependency direction](#17-dependency-direction) | architectural |
 | 18 | [Testability](#18-testability-as-a-design-constraint) | architectural |
 | 19 | [Comments](#19-comments) | architectural |
+| 20 | [Decomposition by intent](#20-decomposition-by-intent) | structural |
 
 ---
 
@@ -265,8 +266,38 @@ counter++;
 setInterval(checkPaymentStatus, 5000);
 ```
 
+### 20. Decomposition by intent
+RULE: Extract a block into a named function when it represents a coherent operation and its name and contract let the caller understand the flow without reading its implementation. Keep orchestration separate from implementation details. Do not split solely to reduce line count; keep tightly coupled steps together when separating them would introduce shared mutable state, excessive parameters, or require reading both functions to understand either.
+WHY: Good decomposition reduces how much a reader must understand at once. Function length is a review signal; extraction must improve comprehension rather than merely move code elsewhere.
+```js
+// bad
+function createPackingSlip(items, destination) {
+  let unitCount = 0;
+  let weightGrams = 0;
+  for (const item of items) {
+    unitCount += item.quantity;
+    weightGrams += item.quantity * item.unitWeightGrams;
+  }
+  return { destination, totals: { unitCount, weightGrams } };
+}
+// good
+function createPackingSlip(items, destination) {
+  return { destination, totals: calculatePackingTotals(items) };
+}
+
+function calculatePackingTotals(items) {
+  let unitCount = 0;
+  let weightGrams = 0;
+  for (const item of items) {
+    unitCount += item.quantity;
+    weightGrams += item.quantity * item.unitWeightGrams;
+  }
+  return { unitCount, weightGrams };
+}
+```
+
 ---
 
 **When in doubt:** fail fast, keep it flat, keep it small.
 
-**Enforcement note:** rules 1–2 (mechanical) should be backed by a linter/formatter in the target language, not left to this document alone — text-only compliance from an agent caps out well below what a lint rule enforces. Rules 3–10 (structural) are catchable by targeted lint rules or code review checklists in most languages. Rules 11–19 (architectural) require judgment and stay as review guidance.
+**Enforcement note:** rules 1–2 (mechanical) should be backed by a linter/formatter in the target language, not left to this document alone — text-only compliance from an agent caps out well below what a lint rule enforces. Rules 3–10 and 20 are structural; rules 11–19 are architectural. Rule 20 requires semantic review, not a line-count limit or mechanical length detector. Rules 11–20 require judgment and stay as review guidance.

package/assets/visual-context/browser/INSTALL.md

@@ -29,7 +29,11 @@ replace the files in the same folder, and reload the extension from the browser'
 extensions page. Do not remove and reinstall it unless you want to pair again.
 The extension connects only to authorized local Pi installations; it captures
 DOM descriptions, not form values or editable text. Source locations are inferred
-candidates, never proven mappings.
+candidates by default. Ask Pi to enable compiler context in a selected project
+for locations checked against local markup. Pi can run in a parent folder;
+F7 can associate a page with a child project. After setup, restart the development
+server and refresh the page. This companion requires visual protocol version 3;
+upgrade/reload Pi and the companion together without changing the pairing address.
 
 ## Español
 
@@ -63,7 +67,12 @@ extensión desde la página de extensiones del navegador. No la elimines y
 reinstales salvo que quieras volver a emparejarla.
 La extensión solo se conecta a instalaciones locales de Pi que hayas autorizado;
 recoge descripciones de los elementos, no valores de formularios ni texto editable.
-Los archivos de origen son candidatos inferidos, no correspondencias demostradas.
+Por defecto, los archivos de origen son candidatos inferidos. Pide a Pi que active
+el contexto del compilador en un proyecto elegido para obtener ubicaciones
+comprobadas contra el código local. Pi puede estar en la carpeta padre; F7 permite
+asociar una página con un proyecto hijo. Tras configurarlo, reinicia el servidor
+de desarrollo y actualiza la página. Esta versión requiere el protocolo visual 3:
+actualiza y recarga Pi y la extensión juntos, conservando el emparejamiento.
 
 Full guide / Guía completa:
 https://github.com/RMRdeveloper/sideroom-pi/blob/main/docs/extensions/visual-context.md

package/assets/visual-context/browser/background.js

@@ -1,10 +1,14 @@
-const PROTOCOL_VERSION = 2;
+importScripts('destinations.js');
+
+const PROTOCOL_VERSION = 3;
 const BRIDGE_PATH = '/sideroom-visual-context';
 const HEARTBEAT_MS = 20_000;
 const RESPONSE_TIMEOUT_MS = 10_000;
 const RETRY_MS = 2_000;
 const RETRY_ALARM = 'sideroom-reconnect';
 const MAX_INSTALLATIONS = 4;
+const MAX_PENDING_RECEIPTS = 8;
+const MAX_MESSAGE_BYTES = 8_192;
 const INSPECTOR_COMMAND = 'toggle-inspector';
 const IDLE_TITLE = 'Select an element for Pi';
 const ACTIVE_TITLE =
@@ -25,10 +29,7 @@ const activeTabs = new Map();
 const receipts = new Map();
 const connections = new Map();
 let paused = false;
-let sessions = [];
-let selected;
-let preferredId;
-let automaticSelection = false;
+const destinations = createDestinations();
 let lastAddress = '';
 let lastNotice = 'Pair once with each Pi installation to select elements.';
 const isConnected = () =>
@@ -75,6 +76,25 @@ async function sendToTab(tabId, message) {
   }
 }
 
+function encodeSelectionFrame(selection, target) {
+  const frame = JSON.stringify({ type: MESSAGE.selection, selection, target });
+  if (new TextEncoder().encode(frame).byteLength > MAX_MESSAGE_BYTES) {
+    throw new Error(
+      'The selected element exceeds the message limit. Select a smaller element.',
+    );
+  }
+  return frame;
+}
+
+async function notifyReceipt({ endpoint, selectionId, notice }) {
+  const receipt = receipts.get(selectionId);
+  if (!receipt || receipt.endpoint !== endpoint) {
+    return;
+  }
+  receipts.delete(selectionId);
+  await sendToTab(receipt.tabId, { action: 'receipt', message: notice });
+}
+
 async function showInspectorIndicator(tabId, { text, title }) {
   await chrome.action.setBadgeBackgroundColor({ tabId, color: '#ffb340' });
   await chrome.action.setBadgeText({ tabId, text });
@@ -97,13 +117,13 @@ async function stopInspectors() {
 }
 
 async function startInspector(tab) {
-  if (!selected || !isConnected()) {
+  const target = destinations.current();
+  if (!target || !isConnected()) {
     throw new Error('Choose an available Pi session first.');
   }
   if (!tab?.id || !/^https?:\/\//u.test(tab.url ?? '')) {
     throw new Error('Open the web page you want to inspect.');
   }
-  const target = selected;
   await chrome.scripting.executeScript({
     target: { tabId: tab.id },
     files: ['content.js'],
@@ -112,7 +132,7 @@ async function startInspector(tab) {
   const shortcut = commands.find(
     (command) => command.name === INSPECTOR_COMMAND,
   )?.shortcut;
-  if (selected !== target) {
+  if (destinations.current() !== target) {
     throw new Error('The destination changed. Start the inspector again.');
   }
   activeTabs.set(tab.id, target);
@@ -144,19 +164,9 @@ async function toggleInspector(commandTab) {
 }
 
 function updateSessions(available) {
-  const previous = selected;
-  sessions = available;
-  selected = sessions.find(
-    (session) => session.id === (preferredId ?? previous?.id),
-  );
-  if (automaticSelection && sessions.length > 1) {
-    selected = undefined;
-    automaticSelection = false;
-  }
-  if (!selected && !preferredId && sessions.length === 1) {
-    selected = sessions[0];
-    automaticSelection = true;
-  }
+  const previous = destinations.current();
+  destinations.update(available);
+  const selected = destinations.current();
   if (
     previous?.id !== selected?.id ||
     previous?.revision !== selected?.revision
@@ -167,7 +177,7 @@ function updateSessions(available) {
   }
   lastNotice = selected
     ? `Connected to ${selected.name}.`
-    : sessions.length
+    : destinations.all().length
       ? 'Choose which Pi session receives your selections.'
       : WAITING_NOTICE;
 }
@@ -188,9 +198,7 @@ async function disconnect() {
   for (const entry of connections.values()) {
     closeConnection(entry);
   }
-  sessions = [];
-  selected = undefined;
-  preferredId = undefined;
+  destinations.clear();
   await stopInspectors();
 }
 
@@ -260,25 +268,29 @@ async function openConnection(entry) {
         }
         if (message.type === MESSAGE.received) {
           lastNotice = `${String(message.candidates)} source candidates. Review in Pi (F7).`;
-          const receipt = receipts.get(message.id);
-          receipts.delete(message.id);
-          if (receipt?.endpoint === entry.endpoint) {
-            await sendToTab(receipt.tabId, {
-              action: 'receipt',
-              message: lastNotice,
-            });
-          }
+          await notifyReceipt({
+            endpoint: entry.endpoint,
+            selectionId: message.id,
+            notice: lastNotice,
+          });
         }
         if (message.type === MESSAGE.error) {
           lastNotice = message.message;
-          for (const [selectionId, receipt] of receipts) {
-            if (receipt.endpoint === entry.endpoint) {
-              receipts.delete(selectionId);
-              await sendToTab(receipt.tabId, {
-                action: 'receipt',
-                message: lastNotice,
-              });
-            }
+          if (typeof message.id === 'string') {
+            await notifyReceipt({
+              endpoint: entry.endpoint,
+              selectionId: message.id,
+              notice: lastNotice,
+            });
+            return;
+          }
+          // Older brokers and connection failures can only identify the installation.
+          for (const selectionId of [...receipts.keys()]) {
+            await notifyReceipt({
+              endpoint: entry.endpoint,
+              selectionId,
+              notice: lastNotice,
+            });
           }
         }
       } catch (cause) {
@@ -331,7 +343,7 @@ async function reconnect(entry) {
   if (!entry.attempt) {
     entry.attempt = openConnection(entry)
       .catch((cause) => {
-        if (!selected) {
+        if (!destinations.current()) {
           lastNotice = cause.message;
         }
         scheduleReconnect(entry);
@@ -412,6 +424,7 @@ async function handleMessage(message, sender) {
     if (message.action !== 'selection' || !target || !isConnected()) {
       throw new Error('Connect to Pi and start the inspector first.');
     }
+    const selected = destinations.current();
     if (target.id !== selected?.id || target.revision !== selected?.revision) {
       throw new Error('The destination changed. Start the inspector again.');
     }
@@ -426,7 +439,7 @@ async function handleMessage(message, sender) {
     if (!entry || entry.socket?.readyState !== WebSocket.OPEN) {
       throw new Error('The destination is no longer available.');
     }
-    if (receipts.size >= 8) {
+    if (receipts.size >= MAX_PENDING_RECEIPTS) {
       throw new Error('Pi is still processing selections. Try again shortly.');
     }
     const page = parseUrl(
@@ -437,13 +450,17 @@ async function handleMessage(message, sender) {
       ...message.selection,
       page: `${page.origin}${page.pathname}`,
     };
+    const frame = encodeSelectionFrame(selection, target);
     receipts.set(selection.id, {
       tabId: sender.tab.id,
       endpoint: entry.endpoint,
     });
-    entry.socket.send(
-      JSON.stringify({ type: MESSAGE.selection, selection, target }),
-    );
+    try {
+      entry.socket.send(frame);
+    } catch (cause) {
+      receipts.delete(selection.id);
+      throw new Error('Cannot send the selected element to Pi.', { cause });
+    }
     return { ok: true };
   }
   if (message.action === 'status') {
@@ -455,8 +472,8 @@ async function handleMessage(message, sender) {
       connected: isConnected(),
       notice: lastNotice,
       address: lastAddress,
-      sessions,
-      selectedId: selected?.id ?? '',
+      sessions: destinations.all(),
+      selectedId: destinations.current()?.id ?? '',
       paused,
       installations: connections.size,
     };
@@ -482,8 +499,8 @@ async function handleMessage(message, sender) {
       ok: true,
       connected: isConnected(),
       notice: lastNotice,
-      sessions,
-      selectedId: selected?.id ?? '',
+      sessions: destinations.all(),
+      selectedId: destinations.current()?.id ?? '',
       address: lastAddress,
     };
   }
@@ -510,21 +527,16 @@ async function handleMessage(message, sender) {
     };
   }
   if (message.action === 'choose') {
-    const destination = sessions.find((session) => session.id === message.id);
-    if (!destination) {
-      throw new Error('That Pi session is no longer available.');
-    }
+    destinations.choose(message.id);
+    const destination = destinations.current();
     await stopInspectors();
-    selected = destination;
-    preferredId = destination.id;
-    automaticSelection = false;
-    lastNotice = `Connected to ${selected.name}.`;
+    lastNotice = `Connected to ${destination.name}.`;
     return {
       ok: true,
       connected: isConnected(),
       notice: lastNotice,
-      sessions,
-      selectedId: selected.id,
+      sessions: destinations.all(),
+      selectedId: destination.id,
     };
   }
   if (message.action === 'inspect') {

package/assets/visual-context/browser/content.js

@@ -6,6 +6,8 @@
   const MAX_TEXT = 160;
   const MAX_CLASSES = 32;
   const MAX_ANCESTORS = 4;
+  const SOURCE_ATTRIBUTE = 'data-insp-path';
+  const MAX_SOURCE_PATH = 2_048;
   const BORDER = '#ffb340';
   let active = false;
   let root;
@@ -35,6 +37,41 @@
     };
   }
 
+  function sourceLocation(element) {
+    const marker = element.getAttribute(SOURCE_ATTRIBUTE);
+    if (!marker) {
+      return undefined;
+    }
+    const parts = marker.match(/^(.*):(\d+):(\d+):([^:]+)$/u);
+    if (
+      !parts?.[1] ||
+      parts[1].length > MAX_SOURCE_PATH ||
+      [...parts[1]].some(
+        (character) =>
+          character.charCodeAt(0) < 32 || character.charCodeAt(0) === 127,
+      )
+    ) {
+      throw new Error(
+        'Invalid compiler location. Refresh the development page.',
+      );
+    }
+    const line = Number(parts[2]);
+    const column = Number(parts[3]);
+    if (
+      !Number.isSafeInteger(line) ||
+      !Number.isSafeInteger(column) ||
+      line < 1 ||
+      column < 1 ||
+      line > 1_000_000 ||
+      column > 1_000_000
+    ) {
+      throw new Error(
+        'Invalid compiler position. Refresh the development page.',
+      );
+    }
+    return { path: parts[1], line, column };
+  }
+
   function visibleText(element) {
     if (element.closest('input,textarea,select,[contenteditable]')) {
       return '';
@@ -91,15 +128,16 @@
       ancestors.push(describe(parent));
       parent = parent.parentElement;
     }
-    const selection = {
-      id: crypto.randomUUID(),
-      page: `${location.origin}${location.pathname}`,
-      element: describe(element),
-      text: visibleText(element),
-      ancestors,
-    };
     caption.textContent = 'Sending selection to Pi…';
     try {
+      const selection = {
+        id: crypto.randomUUID(),
+        page: `${location.origin}${location.pathname}`,
+        element: describe(element),
+        text: visibleText(element),
+        ancestors,
+        source: sourceLocation(element),
+      };
       const response = await chrome.runtime.sendMessage({
         action: 'selection',
         selection,

package/assets/visual-context/browser/destinations.js

@@ -0,0 +1,40 @@
+globalThis.createDestinations = function createDestinations() {
+  let sessions = [];
+  let selected;
+  let preferredId;
+  let automaticSelection = false;
+
+  return {
+    update(available) {
+      sessions = [...available];
+      selected = sessions.find(
+        (session) => session.id === (preferredId ?? selected?.id),
+      );
+      if (automaticSelection && sessions.length > 1) {
+        selected = undefined;
+        automaticSelection = false;
+      }
+      if (!selected && !preferredId && sessions.length === 1) {
+        selected = sessions[0];
+        automaticSelection = true;
+      }
+    },
+    choose(id) {
+      const destination = sessions.find((session) => session.id === id);
+      if (!destination) {
+        throw new Error('That Pi session is no longer available.');
+      }
+      selected = destination;
+      preferredId = destination.id;
+      automaticSelection = false;
+    },
+    clear() {
+      sessions = [];
+      selected = undefined;
+      preferredId = undefined;
+      automaticSelection = false;
+    },
+    current: () => selected,
+    all: () => [...sessions],
+  };
+};

package/assets/visual-context/browser/manifest.json

@@ -1,7 +1,7 @@
 {
   "manifest_version": 3,
   "name": "Sideroom Visual Context",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "Select a page element and attach local source candidates to your Pi session.",
   "minimum_chrome_version": "116",
   "permissions": ["activeTab", "scripting", "storage", "alarms"],

package/extensions/guidelines/catalog.ts

@@ -7,6 +7,8 @@ const LANGUAGE_GUIDE_DIRECTORY = join(
   'skills/sideroom-guidelines/references/languages',
 );
 
+export const GUIDELINES_TOOL_NAME = 'sideroom_guidelines';
+
 export const GUIDELINE_SKILL_PATH = join(
   PACKAGE_ROOT,
   'skills/sideroom-guidelines/SKILL.md',
@@ -36,6 +38,13 @@ export const LANGUAGE_TARGET_LABELS: readonly string[] = LANGUAGE_GUIDES.map(
   ({ extensions }) => extensions.join('/'),
 );
 
+export function languageGuideFor(path: string): string | undefined {
+  const normalizedPath = path.replaceAll('\\', '/').toLowerCase();
+  return LANGUAGE_GUIDES.find(({ extensions }) =>
+    extensions.some((extension) => normalizedPath.endsWith(extension)),
+  )?.path;
+}
+
 function languageGuide(
   fileName: string,
   extensions: readonly string[],

package/extensions/guidelines/execute.ts

@@ -0,0 +1,26 @@
+import { readFileSync } from 'node:fs';
+import { GUIDELINE_SKILL_PATH, languageGuideFor } from './catalog.ts';
+
+export interface GuidelinesToolResult {
+  readonly content: { readonly type: 'text'; readonly text: string }[];
+  readonly details: { readonly paths: readonly string[] };
+}
+
+export function executeGuidelines(
+  path: string,
+  readDocument: (path: string) => string = (path) => readFileSync(path, 'utf8'),
+): GuidelinesToolResult {
+  const guidePath = languageGuideFor(path);
+  const paths = [
+    GUIDELINE_SKILL_PATH,
+    ...(guidePath === undefined ? [] : [guidePath]),
+  ];
+  const content = paths.map((documentPath) => {
+    const text = readDocument(documentPath);
+    if (text.trim().length === 0) {
+      throw new Error(`Empty guidelines document: ${documentPath}`);
+    }
+    return { type: 'text' as const, text };
+  });
+  return { content, details: { paths } };
+}