create-interview-cockpit 0.24.0 → 0.25.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-interview-cockpit",
-  "version": "0.24.0",
+  "version": "0.25.0",
   "description": "Scaffold a personal AI-powered interview prep cockpit",
   "type": "module",
   "bin": {

package/template/client/src/components/FileViewerModal.tsx

@@ -1,4 +1,4 @@
-import { useEffect, useRef, useState, useCallback } from "react";
+import { memo, useEffect, useMemo, useRef, useState, useCallback } from "react";
 import { Prism as SyntaxHighlighter } from "react-syntax-highlighter";
 import { oneDark } from "react-syntax-highlighter/dist/esm/styles/prism";
 import {
@@ -72,9 +72,208 @@ const MIN_W = 380;
 const MIN_H = 260;
 const DEFAULT_W = 720;
 const DEFAULT_H = 520;
+const LARGE_FILE_LINE_THRESHOLD = 2_500;
+const LARGE_FILE_CHAR_THRESHOLD = 220_000;
+const VIRTUAL_ROW_HEIGHT = 20;
+const VIRTUAL_OVERSCAN = 24;
 
 type ResizeDir = "e" | "s" | "se" | "sw" | "w" | "ne" | "nw" | "n" | null;
 
+interface CodeViewerContentProps {
+  content: string;
+  lang: string;
+  selectedLines: Set<number>;
+  chatContextLines: Set<number>;
+  codeAnnotations: CodeAnnotation[];
+  onLineClick: (e: React.MouseEvent, lineNumber: number) => void;
+}
+
+const CodeViewerContent = memo(function CodeViewerContent({
+  content,
+  lang,
+  selectedLines,
+  chatContextLines,
+  codeAnnotations,
+  onLineClick,
+}: CodeViewerContentProps) {
+  const annotationLineSet = useMemo(
+    () => new Set(codeAnnotations.map((annotation) => annotation.lineNumber)),
+    [codeAnnotations],
+  );
+  const lineCount = useMemo(() => content.split(/\r?\n/).length, [content]);
+  const isLargeFile =
+    lineCount > LARGE_FILE_LINE_THRESHOLD ||
+    content.length > LARGE_FILE_CHAR_THRESHOLD;
+
+  if (isLargeFile) {
+    return (
+      <VirtualizedPlainCodeViewer
+        content={content}
+        selectedLines={selectedLines}
+        chatContextLines={chatContextLines}
+        annotationLineSet={annotationLineSet}
+        onLineClick={onLineClick}
+      />
+    );
+  }
+
+  return (
+    <div className="h-full overflow-auto">
+      <SyntaxHighlighter
+        language={lang}
+        style={oneDark}
+        showLineNumbers
+        wrapLines
+        wrapLongLines={false}
+        lineProps={(lineNumber) => {
+          const hasAnnotation = annotationLineSet.has(lineNumber);
+          const isChatCtx = chatContextLines.has(lineNumber);
+          const isSelected = selectedLines.has(lineNumber);
+          let bg: string | undefined;
+          let outline: string | undefined;
+          if (hasAnnotation) {
+            bg = "rgba(139, 92, 246, 0.2)";
+            outline = "1px solid rgba(139, 92, 246, 0.35)";
+          } else if (isChatCtx) {
+            bg = "rgba(245, 158, 11, 0.15)";
+            outline = "1px solid rgba(245, 158, 11, 0.3)";
+          } else if (isSelected) {
+            bg = "rgba(6, 182, 212, 0.15)";
+            outline = "1px solid rgba(6, 182, 212, 0.3)";
+          }
+          return {
+            onClick: (e: React.MouseEvent) =>
+              lineNumber !== undefined && onLineClick(e, lineNumber),
+            style: {
+              display: "block",
+              cursor: "pointer",
+              backgroundColor: bg,
+              outline,
+            },
+          };
+        }}
+        customStyle={{
+          margin: 0,
+          borderRadius: 0,
+          background: "#0f172a",
+          fontSize: "0.75rem",
+          lineHeight: "1.6",
+          minHeight: "100%",
+        }}
+        lineNumberStyle={{ color: "#334155", minWidth: "2.8em" }}
+      >
+        {content}
+      </SyntaxHighlighter>
+    </div>
+  );
+});
+
+interface VirtualizedPlainCodeViewerProps {
+  content: string;
+  selectedLines: Set<number>;
+  chatContextLines: Set<number>;
+  annotationLineSet: Set<number>;
+  onLineClick: (e: React.MouseEvent, lineNumber: number) => void;
+}
+
+function VirtualizedPlainCodeViewer({
+  content,
+  selectedLines,
+  chatContextLines,
+  annotationLineSet,
+  onLineClick,
+}: VirtualizedPlainCodeViewerProps) {
+  const lines = useMemo(() => content.split(/\r?\n/), [content]);
+  const containerRef = useRef<HTMLDivElement>(null);
+  const [scrollTop, setScrollTop] = useState(0);
+  const [viewportHeight, setViewportHeight] = useState(0);
+
+  useEffect(() => {
+    const el = containerRef.current;
+    if (!el) return;
+    const update = () => setViewportHeight(el.clientHeight);
+    update();
+    const observer = new ResizeObserver(update);
+    observer.observe(el);
+    return () => observer.disconnect();
+  }, []);
+
+  const visibleStart = Math.max(
+    0,
+    Math.floor(scrollTop / VIRTUAL_ROW_HEIGHT) - VIRTUAL_OVERSCAN,
+  );
+  const visibleEnd = Math.min(
+    lines.length,
+    Math.ceil((scrollTop + viewportHeight) / VIRTUAL_ROW_HEIGHT) +
+      VIRTUAL_OVERSCAN,
+  );
+  const visibleLines = lines.slice(visibleStart, visibleEnd);
+
+  return (
+    <div
+      ref={containerRef}
+      className="h-full overflow-auto bg-slate-950 font-mono text-xs text-slate-300"
+      onScroll={(e) => setScrollTop(e.currentTarget.scrollTop)}
+    >
+      <div
+        style={{
+          height: lines.length * VIRTUAL_ROW_HEIGHT,
+          position: "relative",
+          minWidth: "max-content",
+        }}
+      >
+        <div
+          style={{
+            position: "absolute",
+            top: visibleStart * VIRTUAL_ROW_HEIGHT,
+            left: 0,
+            right: 0,
+          }}
+        >
+          {visibleLines.map((line, offset) => {
+            const lineNumber = visibleStart + offset + 1;
+            const hasAnnotation = annotationLineSet.has(lineNumber);
+            const isChatCtx = chatContextLines.has(lineNumber);
+            const isSelected = selectedLines.has(lineNumber);
+            const backgroundColor = hasAnnotation
+              ? "rgba(139, 92, 246, 0.2)"
+              : isChatCtx
+                ? "rgba(245, 158, 11, 0.15)"
+                : isSelected
+                  ? "rgba(6, 182, 212, 0.15)"
+                  : undefined;
+            const outline = hasAnnotation
+              ? "1px solid rgba(139, 92, 246, 0.35)"
+              : isChatCtx
+                ? "1px solid rgba(245, 158, 11, 0.3)"
+                : isSelected
+                  ? "1px solid rgba(6, 182, 212, 0.3)"
+                  : undefined;
+
+            return (
+              <div
+                key={lineNumber}
+                onClick={(e) => onLineClick(e, lineNumber)}
+                className="flex cursor-pointer whitespace-pre leading-none hover:bg-slate-800/60"
+                style={{
+                  height: VIRTUAL_ROW_HEIGHT,
+                  backgroundColor,
+                  outline,
+                }}
+              >
+                <span className="sticky left-0 z-10 w-12 shrink-0 select-none bg-slate-950 pr-3 text-right text-slate-600">
+                  {lineNumber}
+                </span>
+                <span className="pr-6">{line || " "}</span>
+              </div>
+            );
+          })}
+        </div>
+      </div>
+    </div>
+  );
+}
+
 export default function FileViewerModal({ filePath, onClose }: Props) {
   const {
     addSnippet,
@@ -598,7 +797,7 @@ export default function FileViewerModal({ filePath, onClose }: Props) {
         </div>
 
         {/* ── Content ── */}
-        <div className="flex-1 overflow-auto">
+        <div className="flex-1 min-h-0">
           {loading && (
             <div className="flex items-center justify-center h-full">
               <Loader2 className="w-5 h-5 text-cyan-400 animate-spin" />
@@ -610,53 +809,14 @@ export default function FileViewerModal({ filePath, onClose }: Props) {
             </div>
           )}
           {!loading && !error && content !== null && (
-            <SyntaxHighlighter
-              language={lang}
-              style={oneDark}
-              showLineNumbers
-              wrapLines
-              wrapLongLines={false}
-              lineProps={(lineNumber) => {
-                const hasAnnotation = codeAnnotations.some(
-                  (a) => a.lineNumber === lineNumber,
-                );
-                const isChatCtx = chatContextLines.has(lineNumber);
-                const isSelected = selectedLines.has(lineNumber);
-                let bg: string | undefined;
-                let outline: string | undefined;
-                if (hasAnnotation) {
-                  bg = "rgba(139, 92, 246, 0.2)";
-                  outline = "1px solid rgba(139, 92, 246, 0.35)";
-                } else if (isChatCtx) {
-                  bg = "rgba(245, 158, 11, 0.15)";
-                  outline = "1px solid rgba(245, 158, 11, 0.3)";
-                } else if (isSelected) {
-                  bg = "rgba(6, 182, 212, 0.15)";
-                  outline = "1px solid rgba(6, 182, 212, 0.3)";
-                }
-                return {
-                  onClick: (e: React.MouseEvent) =>
-                    lineNumber !== undefined && handleLineClick(e, lineNumber),
-                  style: {
-                    display: "block",
-                    cursor: "pointer",
-                    backgroundColor: bg,
-                    outline,
-                  },
-                };
-              }}
-              customStyle={{
-                margin: 0,
-                borderRadius: 0,
-                background: "#0f172a",
-                fontSize: "0.75rem",
-                lineHeight: "1.6",
-                minHeight: "100%",
-              }}
-              lineNumberStyle={{ color: "#334155", minWidth: "2.8em" }}
-            >
-              {content}
-            </SyntaxHighlighter>
+            <CodeViewerContent
+              content={content}
+              lang={lang}
+              selectedLines={selectedLines}
+              chatContextLines={chatContextLines}
+              codeAnnotations={codeAnnotations}
+              onLineClick={handleLineClick}
+            />
           )}
         </div>
 

package/template/cockpit.json

@@ -1,3 +1,3 @@
 {
-  "version": "0.23.1"
+  "version": "0.24.0"
 }

package/template/server/src/index.ts

@@ -17,6 +17,7 @@ import {
   tool,
   stepCountIs,
   type LanguageModel,
+  type ToolSet,
 } from "ai";
 import { z } from "zod";
 import { createOpenAI } from "@ai-sdk/openai";
@@ -345,6 +346,727 @@ function createReadFileTool(fileRegistry: Map<string, ReferenceFileEntry>) {
 const PORT = process.env.PORT || 3001;
 const CODE_CONTEXT_DIR = process.env.CODE_CONTEXT_DIR || "";
 
+const MAX_CODE_TOOL_LIST_RESULTS = 400;
+const MAX_CODE_TOOL_SEARCH_RESULTS = 80;
+const MAX_CODE_TOOL_SEARCH_FILE_BYTES = 512 * 1024;
+const MAX_CODE_TOOL_READ_BYTES = 256 * 1024;
+const MAX_CODE_TOOL_CONTEXT_LINES = 5;
+const MAX_CODE_TOOL_LINE_CHARS = 600;
+
+function normalizeCodeContextRelPath(value: string): string | null {
+  const raw = value.replaceAll("\\", "/").trim();
+  if (!raw || raw.includes("\0") || path.isAbsolute(raw)) return null;
+  const normalized = path.posix.normalize(raw.replace(/^\.\//, ""));
+  if (!normalized || normalized === ".") return null;
+  if (normalized === ".." || normalized.startsWith("../")) return null;
+  return normalized;
+}
+
+function resolveCodeContextFilePath(relPath: string): string | null {
+  if (!CODE_CONTEXT_DIR) return null;
+  const normalized = normalizeCodeContextRelPath(relPath);
+  if (!normalized || !isCodeContextPathAllowed(normalized)) return null;
+
+  const root = path.resolve(CODE_CONTEXT_DIR);
+  const resolved = path.resolve(root, normalized);
+  const relativeToRoot = path.relative(root, resolved);
+  if (relativeToRoot.startsWith("..") || path.isAbsolute(relativeToRoot)) {
+    return null;
+  }
+  return resolved;
+}
+
+async function getScopedCodeContextFiles(
+  selectedFiles: unknown,
+): Promise<string[]> {
+  if (!CODE_CONTEXT_DIR || !Array.isArray(selectedFiles)) return [];
+
+  const selected = selectedFiles
+    .filter((file): file is string => typeof file === "string")
+    .map((file) => normalizeCodeContextRelPath(file))
+    .filter((file): file is string => Boolean(file));
+
+  if (selected.length === 0) return [];
+
+  try {
+    const visibleFiles = new Set(await walkDir(CODE_CONTEXT_DIR));
+    return uniqueStrings(selected).filter((file) => visibleFiles.has(file));
+  } catch {
+    return [];
+  }
+}
+
+function escapeRegExp(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+function clampNumber(
+  value: unknown,
+  min: number,
+  max: number,
+  fallback: number,
+) {
+  const n =
+    typeof value === "number" && Number.isFinite(value) ? value : fallback;
+  return Math.min(Math.max(Math.floor(n), min), max);
+}
+
+function trimToolLine(line: string): string {
+  return line.length > MAX_CODE_TOOL_LINE_CHARS
+    ? `${line.slice(0, MAX_CODE_TOOL_LINE_CHARS)}…`
+    : line;
+}
+
+function codePathMatchesFilter(relPath: string, filter?: string): boolean {
+  const normalizedFilter = filter?.trim().replaceAll("\\", "/").toLowerCase();
+  if (!normalizedFilter) return true;
+  return relPath.toLowerCase().includes(normalizedFilter);
+}
+
+function formatCodeFileTree(paths: string[], limit: number): string {
+  const lines: string[] = [];
+  const seenDirs = new Set<string>();
+  for (const relPath of paths.slice(0, limit)) {
+    const parts = relPath.split("/");
+    for (let i = 0; i < parts.length - 1; i++) {
+      const dirPath = parts.slice(0, i + 1).join("/");
+      if (seenDirs.has(dirPath)) continue;
+      seenDirs.add(dirPath);
+      lines.push(`${"  ".repeat(i)}${parts[i]}/`);
+    }
+    lines.push(`${"  ".repeat(Math.max(0, parts.length - 1))}${parts.at(-1)}`);
+  }
+  return lines.join("\n");
+}
+
+async function readCodeTextWithinLimit(
+  relPath: string,
+  maxBytes = MAX_CODE_TOOL_READ_BYTES,
+): Promise<{ content: string; truncated: boolean; byteLength: number }> {
+  const resolved = resolveCodeContextFilePath(relPath);
+  if (!resolved) throw new Error("Access denied");
+  const buffer = await fs.readFile(resolved);
+  const truncated = buffer.byteLength > maxBytes;
+  return {
+    content: buffer.slice(0, maxBytes).toString("utf-8"),
+    truncated,
+    byteLength: buffer.byteLength,
+  };
+}
+
+async function searchCodeInFiles(
+  scopedFiles: string[],
+  params: {
+    query: string;
+    isRegex?: boolean;
+    caseSensitive?: boolean;
+    pathFilter?: string;
+    maxResults?: number;
+    contextLines?: number;
+    wholeWord?: boolean;
+  },
+) {
+  const query = params.query.trim();
+  if (!query) return { type: "error", error: "query is required" };
+  if (query.length > 500) {
+    return { type: "error", error: "query is too long" };
+  }
+
+  const maxResults = clampNumber(
+    params.maxResults,
+    1,
+    MAX_CODE_TOOL_SEARCH_RESULTS,
+    50,
+  );
+  const contextLines = clampNumber(
+    params.contextLines,
+    0,
+    MAX_CODE_TOOL_CONTEXT_LINES,
+    1,
+  );
+
+  let matcher: RegExp;
+  try {
+    const source = params.isRegex ? query : escapeRegExp(query);
+    const wholeWord =
+      params.wholeWord && /^[A-Za-z_$][\w$]*$/.test(query)
+        ? `\\b${source}\\b`
+        : source;
+    matcher = new RegExp(wholeWord, params.caseSensitive ? "" : "i");
+  } catch (err: any) {
+    return { type: "error", error: err?.message || "Invalid regex" };
+  }
+
+  const candidateFiles = scopedFiles.filter((file) =>
+    codePathMatchesFilter(file, params.pathFilter),
+  );
+  const matches: Array<{
+    path: string;
+    line: number;
+    lineText: string;
+    before: Array<{ line: number; text: string }>;
+    after: Array<{ line: number; text: string }>;
+  }> = [];
+  const truncatedFiles: string[] = [];
+  const unreadableFiles: string[] = [];
+
+  for (const relPath of candidateFiles) {
+    let content: string;
+    try {
+      const read = await readCodeTextWithinLimit(
+        relPath,
+        MAX_CODE_TOOL_SEARCH_FILE_BYTES,
+      );
+      content = read.content;
+      if (read.truncated) truncatedFiles.push(relPath);
+    } catch {
+      unreadableFiles.push(relPath);
+      continue;
+    }
+
+    const lines = content.split(/\r?\n/);
+    for (let i = 0; i < lines.length; i++) {
+      if (!matcher.test(lines[i])) continue;
+      matcher.lastIndex = 0;
+      const beforeStart = Math.max(0, i - contextLines);
+      const afterEnd = Math.min(lines.length, i + contextLines + 1);
+      matches.push({
+        path: relPath,
+        line: i + 1,
+        lineText: trimToolLine(lines[i]),
+        before: lines.slice(beforeStart, i).map((text, offset) => ({
+          line: beforeStart + offset + 1,
+          text: trimToolLine(text),
+        })),
+        after: lines.slice(i + 1, afterEnd).map((text, offset) => ({
+          line: i + offset + 2,
+          text: trimToolLine(text),
+        })),
+      });
+      if (matches.length >= maxResults) {
+        return {
+          query,
+          searchedFiles: candidateFiles.length,
+          truncated: true,
+          truncatedFiles,
+          unreadableFiles,
+          matches,
+        };
+      }
+    }
+  }
+
+  return {
+    query,
+    searchedFiles: candidateFiles.length,
+    truncated: false,
+    truncatedFiles,
+    unreadableFiles,
+    matches,
+  };
+}
+
+function classifyConfigFile(relPath: string): string | null {
+  const lower = relPath.toLowerCase();
+  const base = lower.split("/").at(-1) || lower;
+  if (/^\.github\/workflows\/.+\.ya?ml$/.test(lower)) {
+    return "github-actions-workflow";
+  }
+  if (base === "action.yml" || base === "action.yaml") return "github-action";
+  if (base === "azure-pipelines.yml" || base === "azure-pipelines.yaml") {
+    return "azure-pipelines";
+  }
+  if (base === ".gitlab-ci.yml" || base === ".gitlab-ci.yaml") {
+    return "gitlab-ci";
+  }
+  if (base === "config.yml" && lower.includes(".circleci/")) {
+    return "circleci";
+  }
+  if (base === "jenkinsfile") return "jenkins";
+  if (lower.includes("buildkite") && lower.endsWith(".yml")) {
+    return "buildkite";
+  }
+  if (base === "package.json") return "package-json";
+  if (base === "dockerfile" || base.endsWith(".dockerfile")) {
+    return "dockerfile";
+  }
+  if (
+    base === "docker-compose.yml" ||
+    base === "docker-compose.yaml" ||
+    base === "compose.yml" ||
+    base === "compose.yaml"
+  ) {
+    return "docker-compose";
+  }
+  if (lower.endsWith(".tf") || lower.endsWith(".tfvars")) return "terraform";
+  if (lower.includes("terraform/") && lower.endsWith(".hcl")) {
+    return "terraform-hcl";
+  }
+  return null;
+}
+
+function summarizeConfigStructure(relPath: string, content: string) {
+  const lower = relPath.toLowerCase();
+  if (lower.endsWith(".json")) {
+    try {
+      const parsed = JSON.parse(content);
+      if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+        const record = parsed as Record<string, unknown>;
+        return {
+          topLevelKeys: Object.keys(record).slice(0, 50),
+          scripts:
+            record.scripts && typeof record.scripts === "object"
+              ? Object.keys(record.scripts as Record<string, unknown>).slice(
+                  0,
+                  50,
+                )
+              : undefined,
+        };
+      }
+    } catch {
+      return { parseError: "Invalid JSON" };
+    }
+  }
+
+  if (/\.ya?ml$/i.test(relPath)) {
+    const topLevelKeys = uniqueStrings(
+      content
+        .split(/\r?\n/)
+        .map((line) => line.match(/^([A-Za-z0-9_.-]+):/)?.[1] || "")
+        .filter(Boolean),
+    ).slice(0, 50);
+    return { topLevelKeys };
+  }
+
+  if (/\.(tf|tfvars|hcl)$/i.test(relPath)) {
+    const blocks = uniqueStrings(
+      content
+        .split(/\r?\n/)
+        .map(
+          (line) =>
+            line
+              .trim()
+              .match(
+                /^(terraform|provider|resource|module|variable|output|data|locals|backend)\b.*$/,
+              )?.[0],
+        )
+        .filter((line): line is string => Boolean(line)),
+    ).slice(0, 60);
+    return { blocks };
+  }
+
+  return {};
+}
+
+function extractConfigHighlights(content: string) {
+  const interesting =
+    /\b(terraform\s+(init|plan|apply)|backend-config|azurerm|workflow_call|secrets:\s*inherit|uses:|runs-on:|permissions:|concurrency:|jobs:|steps:|env:|provider\s+"|backend\s+"|resource\s+")/i;
+  return content
+    .split(/\r?\n/)
+    .map((text, index) => ({ line: index + 1, text: trimToolLine(text) }))
+    .filter(({ text }) => interesting.test(text))
+    .slice(0, 30);
+}
+
+function createCodeContextTools(scopedCodeFiles: string[]): ToolSet {
+  if (!CODE_CONTEXT_DIR || scopedCodeFiles.length === 0) return {};
+
+  const files = uniqueStrings(scopedCodeFiles).sort((a, b) =>
+    a.localeCompare(b),
+  );
+  const fileSet = new Set(files);
+
+  return {
+    listCodeFiles: tool({
+      description:
+        "List code-context files that are available to the model. This is read-only and restricted to files the user selected in Code Context, under CODE_CONTEXT_DIR, after ignore rules are applied.",
+      inputSchema: z.object({
+        query: z
+          .string()
+          .optional()
+          .describe(
+            "Optional case-insensitive path substring to filter files.",
+          ),
+        folder: z
+          .string()
+          .optional()
+          .describe(
+            "Optional folder prefix or path substring to narrow results.",
+          ),
+        limit: z
+          .number()
+          .int()
+          .min(1)
+          .max(MAX_CODE_TOOL_LIST_RESULTS)
+          .optional(),
+      }),
+      execute: async ({ query, folder, limit }) => {
+        const cappedLimit = clampNumber(
+          limit,
+          1,
+          MAX_CODE_TOOL_LIST_RESULTS,
+          120,
+        );
+        const filtered = files.filter(
+          (file) =>
+            codePathMatchesFilter(file, query) &&
+            codePathMatchesFilter(file, folder),
+        );
+        const listed = filtered.slice(0, cappedLimit);
+        return {
+          scope: "selected-code-context-files",
+          totalAvailable: files.length,
+          totalMatched: filtered.length,
+          truncated: filtered.length > listed.length,
+          files: listed,
+          tree: formatCodeFileTree(listed, cappedLimit),
+        };
+      },
+    }),
+    searchCode: tool({
+      description:
+        "Search text across available code-context files. Use this before opening many files. It cannot see ignored or unselected files.",
+      inputSchema: z.object({
+        query: z.string().describe("Text or regex to search for."),
+        isRegex: z
+          .boolean()
+          .optional()
+          .describe("Treat query as a JavaScript regular expression."),
+        caseSensitive: z.boolean().optional(),
+        pathFilter: z
+          .string()
+          .optional()
+          .describe(
+            "Optional path substring, e.g. .github/workflows or terraform.",
+          ),
+        maxResults: z
+          .number()
+          .int()
+          .min(1)
+          .max(MAX_CODE_TOOL_SEARCH_RESULTS)
+          .optional(),
+        contextLines: z
+          .number()
+          .int()
+          .min(0)
+          .max(MAX_CODE_TOOL_CONTEXT_LINES)
+          .optional(),
+      }),
+      execute: async (params) => searchCodeInFiles(files, params),
+    }),
+    readCodeFile: tool({
+      description:
+        "Read one available code-context file by relative path, optionally with a 1-based line range. Restricted to selected, non-ignored files.",
+      inputSchema: z.object({
+        path: z
+          .string()
+          .describe("Relative path from the code context file list."),
+        startLine: z.number().int().min(1).optional(),
+        endLine: z.number().int().min(1).optional(),
+      }),
+      execute: async ({ path: requestedPath, startLine, endLine }) => {
+        const relPath = normalizeCodeContextRelPath(requestedPath || "");
+        if (!relPath || !fileSet.has(relPath)) {
+          return {
+            type: "error",
+            error:
+              "File is not available. Use listCodeFiles first; only selected, non-ignored files can be read.",
+          };
+        }
+
+        try {
+          const read = await readCodeTextWithinLimit(relPath);
+          const lines = read.content.split(/\r?\n/);
+          const totalLines = lines.length;
+          const first = clampNumber(startLine, 1, totalLines || 1, 1);
+          const last = clampNumber(
+            endLine,
+            first,
+            totalLines || first,
+            totalLines || first,
+          );
+          const numbered = lines
+            .slice(first - 1, last)
+            .map((line, index) => `${first + index}: ${line}`)
+            .join("\n");
+          return {
+            path: relPath,
+            startLine: first,
+            endLine: last,
+            totalLines,
+            byteLength: read.byteLength,
+            truncated: read.truncated,
+            content: numbered,
+          };
+        } catch (err: any) {
+          return {
+            type: "error",
+            error: err?.message || "Could not read file",
+          };
+        }
+      },
+    }),
+    findCodeReferences: tool({
+      description:
+        "Find textual references to a symbol, function name, workflow name, file name, variable, or config key across available code-context files.",
+      inputSchema: z.object({
+        symbol: z.string().describe("Exact symbol or phrase to find."),
+        pathFilter: z.string().optional(),
+        caseSensitive: z.boolean().optional(),
+        maxResults: z
+          .number()
+          .int()
+          .min(1)
+          .max(MAX_CODE_TOOL_SEARCH_RESULTS)
+          .optional(),
+        contextLines: z
+          .number()
+          .int()
+          .min(0)
+          .max(MAX_CODE_TOOL_CONTEXT_LINES)
+          .optional(),
+      }),
+      execute: async ({
+        symbol,
+        pathFilter,
+        caseSensitive,
+        maxResults,
+        contextLines,
+      }) =>
+        searchCodeInFiles(files, {
+          query: symbol,
+          pathFilter,
+          caseSensitive,
+          maxResults,
+          contextLines,
+          wholeWord: true,
+        }),
+    }),
+    inspectCiConfig: tool({
+      description:
+        "Find and summarize CI/CD, GitHub Actions, Docker, package script, and Terraform config files among the available code-context files.",
+      inputSchema: z.object({
+        pathFilter: z.string().optional(),
+        maxFiles: z.number().int().min(1).max(30).optional(),
+      }),
+      execute: async ({ pathFilter, maxFiles }) => {
+        const limit = clampNumber(maxFiles, 1, 30, 12);
+        const candidates = files
+          .map((file) => ({ file, kind: classifyConfigFile(file) }))
+          .filter(
+            (entry): entry is { file: string; kind: string } =>
+              Boolean(entry.kind) &&
+              codePathMatchesFilter(entry.file, pathFilter),
+          );
+
+        const inspected = [];
+        for (const { file, kind } of candidates.slice(0, limit)) {
+          try {
+            const read = await readCodeTextWithinLimit(file);
+            inspected.push({
+              path: file,
+              kind,
+              truncated: read.truncated,
+              structure: summarizeConfigStructure(file, read.content),
+              highlights: extractConfigHighlights(read.content),
+            });
+          } catch (err: any) {
+            inspected.push({
+              path: file,
+              kind,
+              error: err?.message || "Could not inspect file",
+            });
+          }
+        }
+
+        return {
+          totalConfigFiles: candidates.length,
+          truncated: candidates.length > inspected.length,
+          files: inspected,
+        };
+      },
+    }),
+    runReadOnlyCodeCommand: tool({
+      description:
+        "Run a safe, whitelisted, read-only repository inspection command without a shell. Allowed commands: pwd, find, rg, git-ls-files, git-log, git-blame. Results are restricted to selected code-context files.",
+      inputSchema: z.object({
+        command: z.enum([
+          "pwd",
+          "find",
+          "rg",
+          "git-ls-files",
+          "git-log",
+          "git-blame",
+        ]),
+        query: z
+          .string()
+          .optional()
+          .describe("Required for rg. Optional for find."),
+        path: z
+          .string()
+          .optional()
+          .describe("Required for git-log and git-blame."),
+        pathFilter: z.string().optional(),
+        startLine: z.number().int().min(1).optional(),
+        endLine: z.number().int().min(1).optional(),
+        maxResults: z
+          .number()
+          .int()
+          .min(1)
+          .max(MAX_CODE_TOOL_LIST_RESULTS)
+          .optional(),
+      }),
+      execute: async ({
+        command,
+        query,
+        path: requestedPath,
+        pathFilter,
+        startLine,
+        endLine,
+        maxResults,
+      }) => {
+        const limit = clampNumber(
+          maxResults,
+          1,
+          MAX_CODE_TOOL_LIST_RESULTS,
+          100,
+        );
+        if (command === "pwd") {
+          return {
+            command: "pwd",
+            output: CODE_CONTEXT_DIR,
+            note: "Read-only tools are still restricted to selected, non-ignored code-context files.",
+          };
+        }
+        if (command === "find") {
+          const filtered = files
+            .filter(
+              (file) =>
+                codePathMatchesFilter(file, query) &&
+                codePathMatchesFilter(file, pathFilter),
+            )
+            .slice(0, limit);
+          return {
+            command: "find",
+            files: filtered,
+            truncated: filtered.length >= limit,
+          };
+        }
+        if (command === "rg") {
+          if (!query?.trim())
+            return { type: "error", error: "query is required for rg" };
+          return searchCodeInFiles(files, {
+            query,
+            pathFilter,
+            maxResults: Math.min(limit, MAX_CODE_TOOL_SEARCH_RESULTS),
+            contextLines: 1,
+          });
+        }
+
+        if (command === "git-ls-files") {
+          try {
+            const result = await runGit(["ls-files", "-z"], {
+              cwd: CODE_CONTEXT_DIR,
+              allowFail: true,
+              timeoutMs: 5000,
+              maxBuffer: 1024 * 1024,
+            });
+            if (result.code !== 0) {
+              return {
+                type: "error",
+                error: result.stderr.trim() || "git ls-files failed",
+              };
+            }
+            const tracked = new Set(result.stdout.split("\0").filter(Boolean));
+            const filtered = files
+              .filter(
+                (file) =>
+                  tracked.has(file) && codePathMatchesFilter(file, pathFilter),
+              )
+              .slice(0, limit);
+            return {
+              command: "git ls-files",
+              files: filtered,
+              truncated: filtered.length >= limit,
+            };
+          } catch (err: any) {
+            return {
+              type: "error",
+              error: err?.message || "git ls-files failed",
+            };
+          }
+        }
+
+        const relPath = normalizeCodeContextRelPath(requestedPath || "");
+        if (!relPath || !fileSet.has(relPath)) {
+          return {
+            type: "error",
+            error:
+              "path must be one of the selected, non-ignored code-context files",
+          };
+        }
+
+        if (command === "git-log") {
+          try {
+            const result = await runGit(
+              [
+                "log",
+                "--oneline",
+                "--decorate",
+                `--max-count=${Math.min(limit, 50)}`,
+                "--",
+                relPath,
+              ],
+              {
+                cwd: CODE_CONTEXT_DIR,
+                allowFail: true,
+                timeoutMs: 5000,
+                maxBuffer: 512 * 1024,
+              },
+            );
+            return {
+              command: "git log",
+              path: relPath,
+              output:
+                result.stdout.trim() ||
+                result.stderr.trim() ||
+                "No git history found.",
+            };
+          } catch (err: any) {
+            return { type: "error", error: err?.message || "git log failed" };
+          }
+        }
+
+        try {
+          const args = ["blame", "--date=short"];
+          if (startLine || endLine) {
+            const first = Math.max(1, startLine ?? 1);
+            const last = Math.max(first, endLine ?? first);
+            args.push("-L", `${first},${last}`);
+          }
+          args.push("--", relPath);
+          const result = await runGit(args, {
+            cwd: CODE_CONTEXT_DIR,
+            allowFail: true,
+            timeoutMs: 5000,
+            maxBuffer: 512 * 1024,
+          });
+          return {
+            command: "git blame",
+            path: relPath,
+            output:
+              result.stdout.trim() ||
+              result.stderr.trim() ||
+              "No git blame output.",
+          };
+        } catch (err: any) {
+          return { type: "error", error: err?.message || "git blame failed" };
+        }
+      },
+    }),
+  };
+}
+
 // ─── AI Providers (Vercel AI SDK) ────────────────────────
 // Set the provider + model in .env. Supports: openai, google, anthropic
 
@@ -1984,12 +2706,14 @@ app.post("/api/chat", async (req, res) => {
     }
   }
 
+  const scopedCodeContextFiles =
+    await getScopedCodeContextFiles(codeContextFiles);
+
   // Code-context files from the project directory
-  if (codeContextFiles?.length && CODE_CONTEXT_DIR) {
-    for (const filePath of codeContextFiles as string[]) {
-      const fullPath = path.join(CODE_CONTEXT_DIR, filePath);
-      const resolved = path.resolve(fullPath);
-      if (!resolved.startsWith(path.resolve(CODE_CONTEXT_DIR))) continue;
+  if (scopedCodeContextFiles.length && CODE_CONTEXT_DIR) {
+    for (const filePath of scopedCodeContextFiles) {
+      const resolved = resolveCodeContextFilePath(filePath);
+      if (!resolved) continue;
       fileRegistry.set(
         `code:${filePath}`,
         makeCodeReferenceFileEntry(`[code] ${filePath}`, () =>
@@ -2029,6 +2753,17 @@ For image files, readFile returns visual image data so you can inspect what is v
 
     if (codeFilePaths.length > 0) {
       system += `
+--- Code Context Exploration Tools ---
+You also have read-only code tools for the selected Code Context files:
+- listCodeFiles: see the selected, non-ignored file tree.
+- searchCode: search exact text or regex across selected files.
+- readCodeFile: open a selected file, optionally by line range.
+- findCodeReferences: trace textual usages of a symbol, config key, workflow, or file name.
+- inspectCiConfig: summarize CI/CD, package, Docker, and Terraform config among selected files.
+- runReadOnlyCodeCommand: safe whitelisted equivalents for pwd/find/rg/git-ls-files/git-log/git-blame.
+
+These tools cannot access files outside CODE_CONTEXT_DIR, files hidden by ignore rules, or files the user did not select. If something is missing, ask the user to select more code context or adjust ignore settings.
+
 --- Linking Code Files in Your Response ---
 When you mention or reference one of the **[code]** files above in your response text, format it as a clickable link so the user can open it directly:
 
@@ -2160,6 +2895,7 @@ Examples (illustrative only — use real ids and names from the list above):
               readFile: createReadFileTool(fileRegistry),
             }
           : {}),
+        ...createCodeContextTools(scopedCodeContextFiles),
       },
       stopWhen: stepCountIs(selectedResponseProfile.maxSteps),
     });
@@ -2359,6 +3095,24 @@ function hasIgnoredExtension(fileNameLower: string): boolean {
   return false;
 }
 
+function isCodeContextPathAllowed(relPath: string): boolean {
+  const normalized = normalizeCodeContextRelPath(relPath);
+  if (!normalized) return false;
+
+  const parts = normalized.split("/");
+  for (let i = 0; i < parts.length - 1; i++) {
+    const prefix = parts.slice(0, i + 1).join("/");
+    if (IGNORE_DIRS.has(normalizeName(parts[i])) || shouldIgnorePath(prefix)) {
+      return false;
+    }
+  }
+
+  const fileName = parts.at(-1)?.toLowerCase() ?? "";
+  if (!fileName || IGNORE_FILES.has(fileName)) return false;
+  if (shouldIgnorePath(normalized)) return false;
+  return !hasIgnoredExtension(fileName);
+}
+
 async function walkDir(dir: string, prefix = ""): Promise<string[]> {
   const entries = await fs.readdir(dir, { withFileTypes: true });
   const files: string[] = [];
@@ -2395,15 +3149,15 @@ app.get("/api/code-context/file", async (req, res) => {
   const filePath = req.query.path as string;
   if (!filePath) return res.status(400).json({ error: "Path required" });
 
-  const fullPath = path.join(CODE_CONTEXT_DIR, filePath);
-  const resolved = path.resolve(fullPath);
-  if (!resolved.startsWith(path.resolve(CODE_CONTEXT_DIR))) {
+  const normalized = normalizeCodeContextRelPath(filePath);
+  const resolved = normalized ? resolveCodeContextFilePath(normalized) : null;
+  if (!normalized || !resolved) {
     return res.status(403).json({ error: "Access denied" });
   }
 
   try {
     const content = await fs.readFile(resolved, "utf-8");
-    res.json({ path: filePath, content });
+    res.json({ path: normalized, content });
   } catch {
     res.status(404).json({ error: "File not found" });
   }
@@ -2971,11 +3725,13 @@ app.post("/api/code-line-ask", async (req, res) => {
       }
     }
 
-    if (codeContextFiles?.length && CODE_CONTEXT_DIR) {
-      for (const fp of codeContextFiles as string[]) {
-        const fullPath = path.join(CODE_CONTEXT_DIR, fp);
-        const resolved = path.resolve(fullPath);
-        if (!resolved.startsWith(path.resolve(CODE_CONTEXT_DIR))) continue;
+    const scopedCodeContextFiles =
+      await getScopedCodeContextFiles(codeContextFiles);
+
+    if (scopedCodeContextFiles.length && CODE_CONTEXT_DIR) {
+      for (const fp of scopedCodeContextFiles) {
+        const resolved = resolveCodeContextFilePath(fp);
+        if (!resolved) continue;
         fileRegistry.set(
           `code:${fp}`,
           makeCodeReferenceFileEntry(`[code] ${fp}`, () =>
@@ -3020,7 +3776,7 @@ app.post("/api/code-line-ask", async (req, res) => {
       }
 
       if (codeFilePaths.length > 0) {
-        system += `\n--- Linking Code Files in Your Response ---\nWhen you mention a [code] file, format it as a clickable link:\n  [DisplayText](coderef://relative/path/to/file)\nOnly use coderef:// for [code] files.`;
+        system += `\n--- Code Context Exploration Tools ---\nYou also have read-only tools to list, search, read line ranges, trace textual references, inspect CI/CD config, and run whitelisted read-only inspection commands. These tools are restricted to selected, non-ignored files under CODE_CONTEXT_DIR. If something is missing, ask the user to select more code context or adjust ignore settings.\n\n--- Linking Code Files in Your Response ---\nWhen you mention a [code] file, format it as a clickable link:\n  [DisplayText](coderef://relative/path/to/file)\nOnly use coderef:// for [code] files.`;
       }
     }
 
@@ -3054,9 +3810,12 @@ app.post("/api/code-line-ask", async (req, res) => {
       system,
       prompt: `File: ${filePath || "unknown"}\n\nHighlighted code:\n\`\`\`\n${selectedCode}\n\`\`\`\n\nQuestion: ${prompt.trim()}`,
       tools:
-        fileRegistry.size > 0
+        fileRegistry.size > 0 || scopedCodeContextFiles.length > 0
           ? {
-              readFile: createReadFileTool(fileRegistry),
+              ...(fileRegistry.size > 0
+                ? { readFile: createReadFileTool(fileRegistry) }
+                : {}),
+              ...createCodeContextTools(scopedCodeContextFiles),
             }
           : undefined,
       stopWhen: stepCountIs(4),