@rmrdeveloper/sideroom-pi 8.11.0 → 8.13.0

package/extensions/visual-context/session.ts

@@ -0,0 +1,192 @@
+import type {
+  ExtensionAPI,
+  ExtensionContext,
+} from '@earendil-works/pi-coding-agent';
+import { type Static, Type } from 'typebox';
+import { Check } from 'typebox/value';
+import {
+  addSelection,
+  assertSelectionCapacity,
+  MAX_CANDIDATES,
+  MAX_SELECTIONS,
+  type PendingSelection,
+  parseSelection,
+  SelectionSchema,
+  selectionContext,
+  VISUAL_SNAPSHOT,
+  type VisualSelection,
+} from './model.ts';
+import { candidateIsCurrent, resolveSelection } from './source.ts';
+
+const CandidateSchema = Type.Object(
+  {
+    path: Type.String({
+      minLength: 1,
+      maxLength: 2_048,
+      pattern: '^[^\\x00-\\x1f\\x7f]*$',
+    }),
+    startLine: Type.Integer({ minimum: 1 }),
+    endLine: Type.Integer({ minimum: 1 }),
+    fingerprint: Type.String({ pattern: '^[a-f0-9]{64}$' }),
+    score: Type.Integer({ minimum: 0 }),
+    reasons: Type.Array(Type.String({ maxLength: 200 }), { maxItems: 40 }),
+  },
+  { additionalProperties: false },
+);
+const SnapshotSchema = Type.Object(
+  {
+    pending: Type.Array(
+      Type.Object(
+        {
+          selection: SelectionSchema,
+          resolution: Type.Object(
+            {
+              candidates: Type.Array(CandidateSchema, {
+                maxItems: MAX_CANDIDATES,
+              }),
+              truncated: Type.Boolean(),
+              capped: Type.Boolean(),
+            },
+            { additionalProperties: false },
+          ),
+          chosen: Type.Optional(CandidateSchema),
+        },
+        { additionalProperties: false },
+      ),
+      { maxItems: MAX_SELECTIONS },
+    ),
+  },
+  { additionalProperties: false },
+);
+
+export interface VisualStore {
+  pending: readonly PendingSelection[];
+}
+
+export function createVisualStore(): VisualStore {
+  return { pending: [] };
+}
+
+export function commitPending({
+  store,
+  pi,
+  pending,
+}: {
+  readonly store: VisualStore;
+  readonly pi: Pick<ExtensionAPI, 'appendEntry'>;
+  readonly pending: readonly PendingSelection[];
+}): void {
+  store.pending = pending;
+  pi.appendEntry(VISUAL_SNAPSHOT, { pending });
+}
+
+export function receiveSelection({
+  store,
+  pi,
+  cwd,
+  selection,
+}: {
+  readonly store: VisualStore;
+  readonly pi: Pick<ExtensionAPI, 'appendEntry'>;
+  readonly cwd: string;
+  readonly selection: VisualSelection;
+}): { readonly candidates: number } {
+  const existing = store.pending.find(
+    (entry) => entry.selection.id === selection.id,
+  );
+  if (existing) {
+    return { candidates: existing.resolution.candidates.length };
+  }
+  assertSelectionCapacity(store.pending);
+  const resolution = resolveSelection(cwd, selection);
+  commitPending({
+    store,
+    pi,
+    pending: addSelection(store.pending, { selection, resolution }),
+  });
+  return { candidates: resolution.candidates.length };
+}
+
+export function restorePending({
+  store,
+  ctx,
+}: {
+  readonly store: VisualStore;
+  readonly ctx: Pick<ExtensionContext, 'sessionManager' | 'cwd'>;
+}): void {
+  store.pending = [];
+  const branch = ctx.sessionManager.getBranch();
+  for (let index = branch.length - 1; index >= 0; index -= 1) {
+    const entry = branch[index];
+    if (entry?.type !== 'custom' || entry.customType !== VISUAL_SNAPSHOT) {
+      continue;
+    }
+    if (!Check(SnapshotSchema, entry.data)) {
+      return;
+    }
+    const snapshot: Static<typeof SnapshotSchema> = entry.data;
+    store.pending = snapshot.pending.flatMap((pending) => {
+      const candidates = pending.resolution.candidates.filter(
+        (candidate) =>
+          candidate.startLine <= candidate.endLine &&
+          candidateIsCurrent(ctx.cwd, candidate),
+      );
+      let selection: VisualSelection;
+      try {
+        selection = parseSelection(pending.selection);
+      } catch (cause) {
+        throw new Error(
+          'Cannot restore browser context: invalid page address in the session.',
+          { cause },
+        );
+      }
+      const chosen = candidates.find(
+        (candidate) =>
+          candidate.path === pending.chosen?.path &&
+          candidate.startLine === pending.chosen.startLine &&
+          candidate.fingerprint === pending.chosen.fingerprint,
+      );
+      return [
+        {
+          selection,
+          resolution: { ...pending.resolution, candidates },
+          chosen,
+        },
+      ];
+    });
+    return;
+  }
+}
+
+export function prepareContext({
+  store,
+  cwd,
+}: {
+  readonly store: VisualStore;
+  readonly cwd: string;
+}):
+  | { readonly text: string; readonly selectionIds: readonly string[] }
+  | undefined {
+  if (store.pending.length === 0) {
+    return undefined;
+  }
+  const pending = store.pending.map((entry) => {
+    const candidates = entry.resolution.candidates.filter((candidate) =>
+      candidateIsCurrent(cwd, candidate),
+    );
+    const chosen =
+      entry.chosen && candidates.includes(entry.chosen)
+        ? entry.chosen
+        : undefined;
+    return {
+      ...entry,
+      resolution: { ...entry.resolution, candidates },
+      chosen,
+    };
+  });
+  const context = selectionContext(pending);
+  return {
+    text: context,
+    selectionIds: pending.map((entry) => entry.selection.id),
+  };
+}

package/extensions/visual-context/source.ts

@@ -0,0 +1,197 @@
+import { readdirSync, readFileSync, realpathSync, statSync } from 'node:fs';
+import { extname, join, relative, sep } from 'node:path';
+import ignore from 'ignore';
+import { projectRelativePath } from '../shared/file-path.ts';
+import { isMissingFile } from '../shared/read-file.ts';
+import { InvalidMarkup } from './markup.ts';
+import { matchSource, sourceFingerprint } from './match.ts';
+import {
+  MAX_CANDIDATES,
+  type SourceCandidate,
+  type SourceResolution,
+  type VisualSelection,
+} from './model.ts';
+
+const SOURCE_EXTENSIONS = new Set([
+  '.html',
+  '.htm',
+  '.vue',
+  '.svelte',
+  '.astro',
+  '.jsx',
+  '.tsx',
+]);
+const SKIP_DIRECTORIES = new Set([
+  'node_modules',
+  'dist',
+  'build',
+  'coverage',
+  'vendor',
+]);
+const IGNORE_FILES = ['.gitignore', '.ignore', '.fdignore'];
+const MAX_ENTRIES = 4_096;
+const MAX_FILE_BYTES = 262_144;
+const MAX_SOURCE_BYTES = 8_388_608;
+const MAX_DEPTH = 16;
+const SENSITIVE_NAME =
+  /secret|credential|password|private.?key|(?:^|[._-])env(?:[._-]|$)/iu;
+
+export function resolveSelection(
+  cwd: string,
+  selection: VisualSelection,
+): SourceResolution {
+  const root = realpathSync(cwd);
+  const candidates: SourceCandidate[] = [];
+  let entriesRead = 0;
+  let sourceBytes = 0;
+  let truncated = false;
+  function walk({
+    directory,
+    patterns,
+    depth,
+  }: {
+    readonly directory: string;
+    readonly patterns: readonly string[];
+    readonly depth: number;
+  }): void {
+    if (depth > MAX_DEPTH) {
+      truncated = true;
+      return;
+    }
+    const localPatterns = [...patterns, ...ignorePatterns(directory, root)];
+    const matcher = ignore().add(localPatterns);
+    for (const entry of readdirSync(directory, { withFileTypes: true }).sort(
+      (left, right) => left.name.localeCompare(right.name),
+    )) {
+      entriesRead += 1;
+      if (entriesRead > MAX_ENTRIES || sourceBytes >= MAX_SOURCE_BYTES) {
+        truncated = true;
+        return;
+      }
+      if (
+        entry.name.startsWith('.') ||
+        [...entry.name].some(
+          (character) =>
+            character.charCodeAt(0) < 32 || character.charCodeAt(0) === 127,
+        ) ||
+        SENSITIVE_NAME.test(entry.name) ||
+        entry.isSymbolicLink()
+      ) {
+        continue;
+      }
+      const absolutePath = join(directory, entry.name);
+      const path = relative(root, absolutePath).split(sep).join('/');
+      if (matcher.ignores(entry.isDirectory() ? `${path}/` : path)) {
+        continue;
+      }
+      if (entry.isDirectory()) {
+        if (!SKIP_DIRECTORIES.has(entry.name)) {
+          walk({
+            directory: absolutePath,
+            patterns: localPatterns,
+            depth: depth + 1,
+          });
+        }
+        continue;
+      }
+      if (
+        !entry.isFile() ||
+        !SOURCE_EXTENSIONS.has(extname(entry.name).toLowerCase())
+      ) {
+        continue;
+      }
+      const size = statSync(absolutePath).size;
+      if (size > MAX_FILE_BYTES || sourceBytes + size > MAX_SOURCE_BYTES) {
+        truncated = true;
+        continue;
+      }
+      sourceBytes += size;
+      const source = readFileSync(absolutePath, 'utf8');
+      try {
+        candidates.push(...matchSource({ path, source, selection }));
+      } catch (cause) {
+        if (cause instanceof InvalidMarkup) {
+          truncated = true;
+          continue;
+        }
+        throw new Error(`Cannot inspect visual source ${path}`, { cause });
+      }
+    }
+  }
+  walk({ directory: root, patterns: [], depth: 0 });
+  candidates.sort(
+    (left, right) =>
+      right.score - left.score ||
+      left.path.localeCompare(right.path) ||
+      left.startLine - right.startLine,
+  );
+  return {
+    candidates: candidates.slice(0, MAX_CANDIDATES),
+    truncated,
+    capped: candidates.length > MAX_CANDIDATES,
+  };
+}
+
+function ignorePatterns(directory: string, root: string): readonly string[] {
+  const prefix = relative(root, directory).split(sep).join('/');
+  const patterns: string[] = [];
+  for (const file of IGNORE_FILES) {
+    let source: string;
+    try {
+      source = readFileSync(join(directory, file), 'utf8');
+    } catch (cause) {
+      if (isMissingFile(cause)) {
+        continue;
+      }
+      throw new Error(`Cannot read ignore file ${file}`, { cause });
+    }
+    for (const line of source.split(/\r?\n/u)) {
+      if (!line || line.startsWith('#')) {
+        continue;
+      }
+      const negated = line.startsWith('!');
+      const pattern = negated ? line.slice(1) : line;
+      const nested = prefix
+        ? `${prefix}/${pattern.startsWith('/') ? pattern.slice(1) : pattern.includes('/') ? pattern : `**/${pattern}`}`
+        : pattern;
+      patterns.push(`${negated ? '!' : ''}${nested}`);
+    }
+  }
+  return patterns;
+}
+
+export function candidateIsCurrent(
+  cwd: string,
+  candidate: SourceCandidate,
+): boolean {
+  try {
+    const absolutePath = realpathSync(join(cwd, candidate.path));
+    if (
+      projectRelativePath(cwd, absolutePath) === undefined ||
+      statSync(absolutePath).size > MAX_FILE_BYTES
+    ) {
+      return false;
+    }
+    const source = readFileSync(absolutePath, 'utf8');
+    return (
+      sourceFingerprint(source) === candidate.fingerprint &&
+      candidate.endLine <= source.split('\n').length
+    );
+  } catch (cause) {
+    if (isGone(cause)) {
+      return false;
+    }
+    throw new Error(`Cannot verify selected source ${candidate.path}`, {
+      cause,
+    });
+  }
+}
+
+// A path that turned into a file on the way reports ENOTDIR, which means the
+// remembered source is gone rather than unreadable.
+function isGone(cause: unknown): boolean {
+  return (
+    isMissingFile(cause) ||
+    (cause instanceof Error && 'code' in cause && cause.code === 'ENOTDIR')
+  );
+}

package/extensions/visual-context/ui.ts

@@ -0,0 +1,57 @@
+import { fileURLToPath } from 'node:url';
+import type { ExtensionContext, Theme } from '@earendil-works/pi-coding-agent';
+import {
+  candidateLabel,
+  elementLabel,
+  type PendingSelection,
+  VISUAL_WIDGET,
+} from './model.ts';
+
+export const BROWSER_EXTENSION_DIRECTORY = fileURLToPath(
+  new URL('../../assets/visual-context/browser/', import.meta.url),
+);
+
+function pendingLabel({ resolution, chosen }: PendingSelection): string {
+  if (chosen) {
+    return `${candidateLabel(chosen)} (selected candidate)`;
+  }
+  const truncated = resolution.truncated ? ' · search truncated' : '';
+  const capped = resolution.capped ? ' · more candidates' : '';
+  return `${String(resolution.candidates.length)} candidates${truncated}${capped}`;
+}
+
+export function renderVisualWidget(
+  pending: readonly PendingSelection[],
+  theme: Theme,
+): readonly string[] {
+  return [
+    '',
+    theme.fg(
+      'dim',
+      `Browser elements (${String(pending.length)}) · F7: review`,
+    ),
+    ...pending.map((entry) =>
+      theme.fg(
+        entry.chosen ? 'accent' : 'muted',
+        `${elementLabel(entry.selection)} — ${pendingLabel(entry)}`,
+      ),
+    ),
+  ];
+}
+
+export function refreshVisualWidget(
+  pending: readonly PendingSelection[],
+  ctx: Pick<ExtensionContext, 'ui' | 'mode'>,
+): void {
+  if (ctx.mode !== 'tui') {
+    return;
+  }
+  if (pending.length === 0) {
+    ctx.ui.setWidget(VISUAL_WIDGET, undefined);
+    return;
+  }
+  ctx.ui.setWidget(VISUAL_WIDGET, (_tui, theme) => ({
+    render: () => [...renderVisualWidget(pending, theme)],
+    invalidate() {},
+  }));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rmrdeveloper/sideroom-pi",
-  "version": "8.11.0",
+  "version": "8.13.0",
   "description": "Pi coding-agent package that asks clarifying questions, shows a live todo board, enforces coding guidelines, and will not call it done while your checks are red.",
   "type": "module",
   "files": [
@@ -17,14 +17,15 @@
     "commitlint": "commitlint",
     "types": "tsc --noEmit",
     "test": "node --test 'extensions/**/*.test.ts' 'scripts/**/*.test.mjs'",
-    "lint": "biome lint extensions scripts commitlint.config.mjs",
-    "lint:fix": "biome lint --write extensions scripts commitlint.config.mjs",
-    "format": "biome format --write extensions scripts package.json biome.json commitlint.config.mjs .changeset/config.json",
-    "format:check": "biome format extensions scripts package.json biome.json commitlint.config.mjs .changeset/config.json",
+    "lint": "biome lint extensions assets/visual-context/browser scripts commitlint.config.mjs",
+    "lint:fix": "biome lint --write extensions assets/visual-context/browser scripts commitlint.config.mjs",
+    "format": "biome format --write extensions assets/visual-context/browser scripts package.json biome.json commitlint.config.mjs .changeset/config.json",
+    "format:check": "biome format extensions assets/visual-context/browser scripts package.json biome.json commitlint.config.mjs .changeset/config.json",
     "preview": "node scripts/render-preview.mjs",
     "cache:report": "node scripts/cache-report.mjs",
+    "package:browser": "node scripts/package-browser.mjs",
     "check:if-blocks": "node scripts/check-if-blocks.mjs",
-    "check": "npm run types && npm run check:if-blocks && biome check extensions scripts package.json biome.json commitlint.config.mjs .changeset/config.json && npm test"
+    "check": "npm run types && npm run check:if-blocks && biome check extensions assets/visual-context/browser scripts package.json biome.json commitlint.config.mjs .changeset/config.json && npm test"
   },
   "engines": {
     "node": ">=22.19.0"
@@ -92,10 +93,18 @@
     "@earendil-works/pi-coding-agent": "0.87.1",
     "@earendil-works/pi-tui": "0.87.1",
     "@types/node": "^22.20.1",
+    "@types/ws": "^8.18.2",
+    "fflate": "0.8.3",
     "typebox": "1.3.7",
     "typescript": "^5.6.0"
   },
   "dependencies": {
-    "ignore": "7.0.5"
+    "@astrojs/compiler": "^4.0.0",
+    "@babel/parser": "^7.29.9",
+    "@vue/compiler-dom": "^3.5.43",
+    "ignore": "7.0.5",
+    "parse5": "^8.0.1",
+    "svelte": "^5.57.2",
+    "ws": "^8.22.0"
   }
 }

package/skills/sideroom-architecture/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: sideroom-architecture
-description: "Surface the architectural decisions a change forces so they are asked, not silently assumed. Use when a feature or change touches module boundaries, data ownership, integration contracts, failure behavior, quality attributes, operations, cost, lock-in, or reversibility, or when the user says the architecture is not settled. Do not use for a trivial or reversible change, a pure glossary lookup, or an already-closed spec."
+description: "Resolve architectural choices before code: module boundaries, data ownership, API or integration contracts, persistence, failure and retry behavior, deployment, capacity, cost, or provider choice. Use when designing or changing these and the repository or user has not settled the choice, even if the feature requirements are clear. Skip routine changes that reuse established contracts; use sideroom-grill when the broader plan is also open."
 license: MIT
 metadata:
   author: RMRdeveloper
@@ -25,8 +25,10 @@ throughput, availability), operations, cost, lock-in, or the difficulty of
 changing course later. It runs under `sideroom-grill` for the architectural
 part of an interview, and on its own when only the architecture is open.
 
-Do not load it for a minor decision (reversible, no boundary or contract
-impact), or for a word conflict — that is `sideroom-domain-modeling`.
+Clear feature requirements do not settle the architecture by themselves.
+Load this skill if a consequential choice remains, even when it is reversible.
+Do not load it for routine changes that reuse established boundaries and
+contracts, or for a word conflict — that is `sideroom-domain-modeling`.
 
 ## Hard Rules
 

package/skills/sideroom-codebase-design/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Matt Pocock
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.