@rmrdeveloper/sideroom-pi 8.12.0 → 8.14.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.12.0",
+  "version": "8.14.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-codebase-design/SKILL.md

@@ -4,7 +4,7 @@ description: "Improve an existing codebase for long-term maintainability and sca
 license: MIT
 metadata:
   author: RMRdeveloper
-  version: "1.0"
+  version: "1.1"
 ---
 
 # Sideroom codebase design
@@ -33,6 +33,29 @@ A review request does not authorize a rewrite. An implementation request does
 not require pausing after every recommendation. Ask only about consequential
 choices or missing facts that the user and repository have not settled.
 
+## Vocabulary (use these terms exactly)
+
+Use these terms consistently in all recommendations and designs. Do not substitute "component", "service", "API", "boundary", "unit" or similar loose words. Consistent language is the point.
+
+| Term | Meaning | Avoid |
+|------|---------|-------|
+| **Module** | Anything with an interface and an implementation. Scale-agnostic: a function, class, package, or tier-spanning slice. | unit, component, service |
+| **Interface** | Everything a caller must know to use the module correctly: the type signature, plus invariants, ordering constraints, error modes, required configuration, and relevant performance or resource behaviour. | API, signature |
+| **Implementation** | The code inside the module. Distinct from Adapter. | — |
+| **Depth** | Leverage at the interface: the amount of useful behaviour a caller (or test) can exercise per unit of interface they have to learn. A module is **deep** when a large amount of behaviour sits behind a small interface, **shallow** when the interface is nearly as complex as the implementation. | — |
+| **Seam** | A place where you can alter behaviour without editing in that place (Michael Feathers). It is the *location* at which a module's interface lives. Where to put the seam is its own design decision, distinct from what goes behind it. | boundary |
+| **Adapter** | A concrete thing that satisfies an interface at a seam. Describes *role* (what slot it fills), not substance. | — |
+| **Leverage** | What callers get from depth: more capability per unit of interface they learn. One implementation pays back across many call sites and tests. | — |
+| **Locality** | What maintainers get from depth: change, bugs, knowledge, and verification concentrate in one place rather than spreading across callers. | — |
+
+**Principles that follow from the vocabulary:**
+- Depth is a property of the **interface**, not of the implementation size. A deep module can be internally composed of small, mockable, swappable parts; they just aren't part of the interface.
+- The **deletion test**: imagine deleting the module. If complexity vanishes, it was a pass-through. If complexity reappears across callers, it was earning its keep.
+- The interface is the test surface. Callers and tests cross the same seam. If you want to test past the interface, the module is probably the wrong shape.
+- One adapter means a hypothetical seam. Two adapters (e.g. production + test stand-in) means a real one. Don't introduce a seam unless something actually varies across it.
+
+When writing recommendations, use these terms. Explain any necessary design term once if the user is unfamiliar, then stick to them. Respect the project's existing domain vocabulary (`CONTEXT.md` or equivalent) for business concepts — do not replace established domain names just to impose this design glossary.
+
 ## Inspect before recommending
 
 1. Read project instructions, existing domain vocabulary (`CONTEXT.md`, or the
@@ -55,6 +78,8 @@ choices or missing facts that the user and repository have not settled.
 
 ## Design principles
 
+Apply the vocabulary above. In particular:
+
 - A **module** presents an **interface** and hides an implementation. Its
   interface includes everything callers must understand: inputs, outputs,
   invariants, errors, ordering, configuration, and relevant resource behavior.
@@ -141,6 +166,8 @@ verification, and unresolved facts. After implementation, report changes,
 checks, and remaining limitations. Keep review results in the conversation
 unless the user requests a document. No graphic or HTML artifact is produced.
 
+**Use the design vocabulary (module, interface, depth, seam, adapter, leverage, locality) consistently** in all recommendations and designs.
+
 ## Attribution
 
 Adapted from Matt Pocock's