@rmrdeveloper/sideroom-pi 8.14.0 → 9.0.1

package/extensions/visual-context/session.ts

@@ -10,13 +10,16 @@ import {
   MAX_CANDIDATES,
   MAX_SELECTIONS,
   type PendingSelection,
+  PROJECT_BINDINGS,
   parseSelection,
   SelectionSchema,
+  SOURCE_METHOD,
   selectionContext,
   VISUAL_SNAPSHOT,
   type VisualSelection,
 } from './model.ts';
-import { candidateIsCurrent, resolveSelection } from './source.ts';
+import { inspectProject } from './projects.ts';
+import { currentCandidates, resolveProjectSelection } from './source.ts';
 
 const CandidateSchema = Type.Object(
   {
@@ -30,6 +33,8 @@ const CandidateSchema = Type.Object(
     fingerprint: Type.String({ pattern: '^[a-f0-9]{64}$' }),
     score: Type.Integer({ minimum: 0 }),
     reasons: Type.Array(Type.String({ maxLength: 200 }), { maxItems: 40 }),
+    method: Type.Optional(Type.Literal('compiler')),
+    startColumn: Type.Optional(Type.Integer({ minimum: 1 })),
   },
   { additionalProperties: false },
 );
@@ -46,6 +51,7 @@ const SnapshotSchema = Type.Object(
               }),
               truncated: Type.Boolean(),
               capped: Type.Boolean(),
+              issue: Type.Optional(Type.String({ maxLength: 512 })),
             },
             { additionalProperties: false },
           ),
@@ -61,36 +67,129 @@ const SnapshotSchema = Type.Object(
 
 export interface VisualStore {
   pending: readonly PendingSelection[];
+  bindings: readonly ProjectBinding[];
+}
+
+interface ProjectBinding {
+  readonly origin: string;
+  readonly project: string;
+}
+const BindingsSchema = Type.Object(
+  {
+    bindings: Type.Array(
+      Type.Object(
+        {
+          origin: Type.String({ maxLength: 2_048 }),
+          project: Type.String({
+            minLength: 1,
+            maxLength: 2_048,
+            pattern: '^[^\\x00-\\x1f\\x7f]*$',
+          }),
+        },
+        { additionalProperties: false },
+      ),
+      { maxItems: 64 },
+    ),
+  },
+  { additionalProperties: false },
+);
+
+function pageOrigin(page: string): string {
+  let url: URL;
+  try {
+    url = new URL(page);
+  } catch (cause) {
+    throw new Error('Invalid browser page address for project association.', {
+      cause,
+    });
+  }
+  if (!['http:', 'https:'].includes(url.protocol)) {
+    throw new Error('Associate an HTTP or HTTPS page.');
+  }
+  return url.origin;
+}
+
+function projectFor(store: VisualStore, page: string): string | undefined {
+  return store.bindings.find((binding) => binding.origin === pageOrigin(page))
+    ?.project;
 }
 
 export function createVisualStore(): VisualStore {
-  return { pending: [] };
+  return { pending: [], bindings: [] };
+}
+
+interface ProjectBindingInput {
+  readonly store: VisualStore;
+  readonly pi: Pick<ExtensionAPI, 'appendEntry'>;
+  readonly cwd: string;
+  readonly project: string;
+  readonly page: string;
 }
 
-export function commitPending({
+export function bindProject({
   store,
   pi,
-  pending,
-}: {
+  cwd,
+  project,
+  page,
+}: ProjectBindingInput): void {
+  const inspected = inspectProject(cwd, project);
+  const origin = pageOrigin(page);
+  const bindings = [
+    ...store.bindings.filter((binding) => binding.origin !== origin),
+    { origin, project: inspected.path },
+  ];
+  if (bindings.length > 64) {
+    throw new Error(
+      'The session already has 64 project associations. Reuse an existing origin.',
+    );
+  }
+  const pending = store.pending.map((entry) => {
+    if (pageOrigin(entry.selection.page) !== origin) {
+      return entry;
+    }
+    const resolution = resolveProjectSelection({
+      cwd,
+      selection: entry.selection,
+      project: inspected.path,
+    });
+    return {
+      selection: entry.selection,
+      resolution,
+      chosen: resolution.candidates.find(
+        (candidate) => candidate.method === SOURCE_METHOD.compiler,
+      ),
+    };
+  });
+  store.bindings = bindings;
+  pi.appendEntry(PROJECT_BINDINGS, { bindings });
+  commitPending({ store, pi, pending });
+}
+
+interface PendingCommit {
   readonly store: VisualStore;
   readonly pi: Pick<ExtensionAPI, 'appendEntry'>;
   readonly pending: readonly PendingSelection[];
-}): void {
+}
+
+export function commitPending({ store, pi, pending }: PendingCommit): void {
   store.pending = pending;
   pi.appendEntry(VISUAL_SNAPSHOT, { pending });
 }
 
+interface ReceiveSelectionInput {
+  readonly store: VisualStore;
+  readonly pi: Pick<ExtensionAPI, 'appendEntry'>;
+  readonly cwd: string;
+  readonly selection: VisualSelection;
+}
+
 export function receiveSelection({
   store,
   pi,
   cwd,
   selection,
-}: {
-  readonly store: VisualStore;
-  readonly pi: Pick<ExtensionAPI, 'appendEntry'>;
-  readonly cwd: string;
-  readonly selection: VisualSelection;
-}): { readonly candidates: number } {
+}: ReceiveSelectionInput): { readonly candidates: number } {
   const existing = store.pending.find(
     (entry) => entry.selection.id === selection.id,
   );
@@ -98,11 +197,21 @@ export function receiveSelection({
     return { candidates: existing.resolution.candidates.length };
   }
   assertSelectionCapacity(store.pending);
-  const resolution = resolveSelection(cwd, selection);
+  const resolution = resolveProjectSelection({
+    cwd,
+    selection,
+    project: projectFor(store, selection.page),
+  });
   commitPending({
     store,
     pi,
-    pending: addSelection(store.pending, { selection, resolution }),
+    pending: addSelection(store.pending, {
+      selection,
+      resolution,
+      chosen: resolution.candidates.find(
+        (candidate) => candidate.method === SOURCE_METHOD.compiler,
+      ),
+    }),
   });
   return { candidates: resolution.candidates.length };
 }
@@ -115,7 +224,20 @@ export function restorePending({
   readonly ctx: Pick<ExtensionContext, 'sessionManager' | 'cwd'>;
 }): void {
   store.pending = [];
+  store.bindings = [];
   const branch = ctx.sessionManager.getBranch();
+  for (const entry of [...branch].reverse()) {
+    if (entry.type !== 'custom' || entry.customType !== PROJECT_BINDINGS) {
+      continue;
+    }
+    if (Check(BindingsSchema, entry.data)) {
+      store.bindings = entry.data.bindings.map((binding) => ({
+        ...binding,
+        origin: pageOrigin(binding.origin),
+      }));
+    }
+    break;
+  }
   for (let index = branch.length - 1; index >= 0; index -= 1) {
     const entry = branch[index];
     if (entry?.type !== 'custom' || entry.customType !== VISUAL_SNAPSHOT) {
@@ -125,11 +247,16 @@ export function restorePending({
       return;
     }
     const snapshot: Static<typeof SnapshotSchema> = entry.data;
+    const current = new Set(
+      currentCandidates(
+        ctx.cwd,
+        snapshot.pending.flatMap((pending) => pending.resolution.candidates),
+      ),
+    );
     store.pending = snapshot.pending.flatMap((pending) => {
       const candidates = pending.resolution.candidates.filter(
         (candidate) =>
-          candidate.startLine <= candidate.endLine &&
-          candidateIsCurrent(ctx.cwd, candidate),
+          candidate.startLine <= candidate.endLine && current.has(candidate),
       );
       let selection: VisualSelection;
       try {
@@ -170,9 +297,15 @@ export function prepareContext({
   if (store.pending.length === 0) {
     return undefined;
   }
+  const current = new Set(
+    currentCandidates(
+      cwd,
+      store.pending.flatMap((entry) => entry.resolution.candidates),
+    ),
+  );
   const pending = store.pending.map((entry) => {
     const candidates = entry.resolution.candidates.filter((candidate) =>
-      candidateIsCurrent(cwd, candidate),
+      current.has(candidate),
     );
     const chosen =
       entry.chosen && candidates.includes(entry.chosen)

package/extensions/visual-context/setup.ts

@@ -0,0 +1,146 @@
+import { readFileSync, statSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
+import { Type } from 'typebox';
+import { compilerPackage, INSPECTOR_VERSION } from './compiler-config.ts';
+import { configureSource } from './configure.ts';
+import { allowedPath, MAX_FILE_BYTES } from './files.ts';
+import { discoverProjects, inspectProject, readManifest } from './projects.ts';
+
+export const VISUAL_SETUP_TOOL = 'sideroom_visual_setup';
+const SetupSchema = Type.Object(
+  {
+    action: Type.Union([
+      Type.Literal('discover'),
+      Type.Literal('prepare'),
+      Type.Literal('bind'),
+    ]),
+    project: Type.Optional(
+      Type.String({
+        minLength: 1,
+        maxLength: 2_048,
+        pattern: '^[^\\x00-\\x1f\\x7f]*$',
+      }),
+    ),
+    page: Type.Optional(Type.String({ minLength: 1, maxLength: 2_048 })),
+  },
+  { additionalProperties: false },
+);
+
+export function prepareSetup(cwd: string, project: string) {
+  const inspected = inspectProject(cwd, project);
+  if (!inspected.config || !inspected.kind) {
+    throw new Error(
+      'No supported build configuration was found. Create or identify the framework configuration before preparing inspector setup.',
+    );
+  }
+  const config = allowedPath(cwd, inspected.config);
+  if (!config || statSync(config).size > MAX_FILE_BYTES) {
+    throw new Error('The configuration is missing, excluded, or too large.');
+  }
+  const root = dirname(config);
+  const manifest = readManifest(root);
+  const nextVersion =
+    manifest.dependencies?.next ?? manifest.devDependencies?.next;
+  const original = readFileSync(config, 'utf8');
+  const prepared = configureSource({
+    source: original,
+    kind: inspected.kind,
+    commonjs: config.endsWith('.cjs'),
+    typescript: /\.(ts|mts)$/u.test(config),
+    nextMajor: nextVersion ? Number(nextVersion.match(/\d+/u)?.[0]) : undefined,
+  });
+  return {
+    project: inspected,
+    edit: {
+      path: inspected.config,
+      oldText: original,
+      newText: prepared.source,
+    },
+    install: {
+      cwd: join(cwd, inspected.path),
+      command: inspected.manager,
+      args:
+        inspected.manager === 'npm'
+          ? [
+              'install',
+              '--save-dev',
+              `${compilerPackage(inspected.kind)}@${INSPECTOR_VERSION}`,
+            ]
+          : [
+              'add',
+              '--dev',
+              `${compilerPackage(inspected.kind)}@${INSPECTOR_VERSION}`,
+            ],
+    },
+    checkScripts: Object.keys(manifest.scripts ?? {}).filter((script) =>
+      ['check', 'typecheck', 'lint', 'test', 'build'].includes(script),
+    ),
+    instructions:
+      'Apply this plan through normal Pi edit/bash tools. Follow sideroom-visual-setup for runtime path portability, installation and browser verification.',
+  };
+}
+
+export function registerVisualSetup(
+  pi: ExtensionAPI,
+  onBind: (binding: {
+    readonly project: string;
+    readonly page: string;
+    readonly cwd: string;
+  }) => void,
+): void {
+  pi.registerTool({
+    name: VISUAL_SETUP_TOOL,
+    label: 'Sideroom Visual Setup',
+    description:
+      'Discover child web projects, prepare a compiler-location integration for one selected project, or associate a browser page with its project. Prepare returns an exact configuration edit and dependency installation command; apply them through the normal Pi edit and bash tools. Does not edit project files itself.',
+    promptSnippet:
+      'Set up precise browser source locations in a selected web project, including projects below the Pi working directory.',
+    promptGuidelines: [
+      'Read sideroom-visual-setup before enabling or reviewing compiler context. The skill owns project selection, runtime path portability, installation and verification; prepare supplies the configuration template and commands.',
+    ],
+    parameters: SetupSchema,
+    executionMode: 'sequential',
+    execute: async (_id, params, _signal, _update, ctx) => {
+      if (!ctx.isProjectTrusted()) {
+        throw new Error(
+          'Trust this workspace in Pi before setting up visual context.',
+        );
+      }
+      if (params.action === 'discover') {
+        const discovery = discoverProjects(ctx.cwd);
+        return {
+          content: [{ type: 'text', text: JSON.stringify(discovery, null, 2) }],
+          details: discovery,
+        };
+      }
+      if (!params.project) {
+        throw new Error(
+          'Choose an explicit project path relative to the Pi working directory.',
+        );
+      }
+      if (params.action === 'prepare') {
+        const plan = prepareSetup(ctx.cwd, params.project);
+        return {
+          content: [{ type: 'text', text: JSON.stringify(plan, null, 2) }],
+          details: plan,
+        };
+      }
+      if (!params.page) {
+        throw new Error(
+          'Provide the browser page to associate with the selected project.',
+        );
+      }
+      onBind({ project: params.project, page: params.page, cwd: ctx.cwd });
+      return {
+        content: [
+          {
+            type: 'text',
+            text: 'The page is associated with the project. Pending selections were resolved again; compiler locations still require local markup validation.',
+          },
+        ],
+        details: {},
+      };
+    },
+  });
+}