pi-compass 0.2.0

package/src/index.ts

@@ -0,0 +1,90 @@
+import type {
+  ExtensionAPI,
+  ExtensionCommandContext,
+} from "@mariozechner/pi-coding-agent";
+
+import { detectProject } from "./project.js";
+import { ensureStorageLayout, loadCachedCodemap } from "./storage.js";
+import { computeContentHash } from "./codemap-generator.js";
+import {
+  handleBeforeAgentStart as buildInjection,
+  type BeforeAgentStartEvent,
+} from "./codemap-injector.js";
+import { handleOnboardCommand, COMMAND_NAME as ONBOARD_CMD } from "./onboard-command.js";
+import { handleTourCommand, COMMAND_NAME as TOUR_CMD } from "./tour-command.js";
+import { registerOnboardTools } from "./onboard-tools.js";
+import type { CompassState } from "./types.js";
+
+const DEFAULT_MAX_INJECTION_CHARS = 6000;
+
+export default function (pi: ExtensionAPI): void {
+  let state: CompassState = {
+    project: null,
+    turnCount: 0,
+    codemapInjected: false,
+    cachedCodemap: null,
+    stale: false,
+  };
+
+  const stateRef = {
+    get: () => state,
+    set: (s: CompassState) => { state = s; },
+  };
+
+  pi.on("session_start", async (_event, ctx) => {
+    try {
+      const project = await detectProject(pi, ctx.cwd);
+      ensureStorageLayout(project.id);
+
+      const cached = loadCachedCodemap(project.id);
+      let stale = false;
+      if (cached) {
+        const currentHash = computeContentHash(project.root);
+        stale = cached.contentHash !== currentHash;
+      }
+
+      state = { ...state, project, cachedCodemap: cached, stale };
+
+      registerOnboardTools(pi, stateRef);
+    } catch (err) {
+      console.error("[pi-compass] session_start error:", err);
+    }
+  });
+
+  pi.on("before_agent_start", (event, _ctx) => {
+    try {
+      if (!state.project) return;
+      const result = buildInjection(
+        event as BeforeAgentStartEvent,
+        state,
+        DEFAULT_MAX_INJECTION_CHARS,
+      );
+      if (result) {
+        state = { ...state, codemapInjected: true };
+        return result;
+      }
+    } catch (err) {
+      console.error("[pi-compass] before_agent_start error:", err);
+    }
+  });
+
+  pi.on("turn_end", (_event, _ctx) => {
+    try {
+      state = { ...state, turnCount: state.turnCount + 1 };
+    } catch (err) {
+      console.error("[pi-compass] turn_end error:", err);
+    }
+  });
+
+  pi.registerCommand(ONBOARD_CMD, {
+    description: "Generate a structured codebase map for the current project",
+    handler: (args: string, ctx: ExtensionCommandContext) =>
+      handleOnboardCommand(args, ctx, pi, stateRef),
+  });
+
+  pi.registerCommand(TOUR_CMD, {
+    description: "Take a guided tour of a specific area of the codebase",
+    handler: (args: string, ctx: ExtensionCommandContext) =>
+      handleTourCommand(args, ctx, pi, stateRef),
+  });
+}

package/src/onboard-command.ts

@@ -0,0 +1,60 @@
+import type {
+  ExtensionAPI,
+  ExtensionCommandContext,
+} from "@mariozechner/pi-coding-agent";
+import { generateCodemap } from "./codemap-generator.js";
+import { formatCodemapMarkdown } from "./codemap-formatter.js";
+import { saveCachedCodemap } from "./storage.js";
+import type { StateRef, CacheEntry, CodeMap } from "./types.js";
+
+export const COMMAND_NAME = "onboard";
+
+export async function handleOnboardCommand(
+  args: string,
+  ctx: ExtensionCommandContext,
+  pi: ExtensionAPI,
+  stateRef: StateRef,
+): Promise<void> {
+  const state = stateRef.get();
+  if (!state.project) {
+    ctx.ui.notify("No project detected. Run from within a git repository.", "error");
+    return;
+  }
+
+  const forceRefresh = args.trim() === "--refresh";
+
+  if (!forceRefresh && state.cachedCodemap && !state.stale) {
+    const markdown = formatCodemapMarkdown(state.cachedCodemap.data);
+    pi.sendUserMessage(
+      `Here is the cached codebase map for ${state.project.name}:\n\n${markdown}`,
+      { deliverAs: "followUp" },
+    );
+    return;
+  }
+
+  const codemap = generateCodemap(
+    state.project.root,
+    state.project.id,
+    state.project.name,
+  );
+
+  const entry: CacheEntry<CodeMap> = {
+    data: codemap,
+    contentHash: codemap.contentHash,
+    createdAt: codemap.generatedAt,
+  };
+  saveCachedCodemap(state.project.id, entry);
+
+  stateRef.set({
+    ...state,
+    cachedCodemap: entry,
+    stale: false,
+    codemapInjected: false,
+  });
+
+  const markdown = formatCodemapMarkdown(codemap);
+  pi.sendUserMessage(
+    `Here is the codebase map for ${state.project.name}:\n\n${markdown}`,
+    { deliverAs: "followUp" },
+  );
+}

package/src/onboard-tools.ts

@@ -0,0 +1,116 @@
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { Type } from "@sinclair/typebox";
+import type { StateRef } from "./types.js";
+import { getOrGenerateCodemap } from "./codemap-generator.js";
+import { formatCodemapMarkdown } from "./codemap-formatter.js";
+import { detectAvailableTopics, getOrGenerateTour, formatTourMarkdown } from "./tour-generator.js";
+
+const CodemapParams = Type.Object({});
+
+const TourParams = Type.Object({
+  topic: Type.Optional(
+    Type.String({ description: "Tour topic (e.g., 'auth', 'api', 'testing'). Omit to list available topics." }),
+  ),
+});
+
+function createCodemapTool(stateRef: StateRef) {
+  return {
+    name: "codebase_map" as const,
+    label: "Codebase Map",
+    description: "Returns a structured map of the current codebase including directory tree, packages, frameworks, entry points, build scripts, and conventions",
+    promptSnippet: "Get or generate a structured map of the current codebase",
+    parameters: CodemapParams,
+    async execute(
+      _toolCallId: string,
+      _params: Record<string, never>,
+      _signal: AbortSignal | undefined,
+      _onUpdate: unknown,
+      _ctx: unknown,
+    ) {
+      const state = stateRef.get();
+      if (!state.project) {
+        throw new Error("No project detected.");
+      }
+
+      const { codemap } = getOrGenerateCodemap(
+        state.project.root,
+        state.project.id,
+        state.project.name,
+      );
+
+      const markdown = formatCodemapMarkdown(codemap);
+      return {
+        content: [{ type: "text" as const, text: markdown }],
+        details: { projectId: codemap.projectId, contentHash: codemap.contentHash },
+      };
+    },
+  };
+}
+
+function createTourTool(stateRef: StateRef) {
+  return {
+    name: "code_tour" as const,
+    label: "Code Tour",
+    description: "Returns a guided walkthrough of a specific area of the codebase, or lists available topics",
+    promptSnippet: "Get a guided code tour for a specific topic or area",
+    parameters: TourParams,
+    async execute(
+      _toolCallId: string,
+      params: { topic?: string },
+      _signal: AbortSignal | undefined,
+      _onUpdate: unknown,
+      _ctx: unknown,
+    ) {
+      const state = stateRef.get();
+      if (!state.project) {
+        throw new Error("No project detected.");
+      }
+
+      const codemap = state.cachedCodemap?.data
+        ?? getOrGenerateCodemap(state.project.root, state.project.id, state.project.name).codemap;
+
+      if (!params.topic) {
+        const topics = detectAvailableTopics(state.project.root, codemap);
+        return {
+          content: [{
+            type: "text" as const,
+            text: topics.length > 0
+              ? `Available tour topics: ${topics.join(", ")}`
+              : "No tour topics detected.",
+          }],
+          details: { topics } as Record<string, unknown>,
+        };
+      }
+
+      const tour = getOrGenerateTour(
+        state.project.root,
+        params.topic,
+        codemap,
+        state.project.id,
+      );
+
+      return {
+        content: [{ type: "text" as const, text: formatTourMarkdown(tour) }],
+        details: { topic: tour.topic, steps: tour.steps.length } as Record<string, unknown>,
+      };
+    },
+  };
+}
+
+export function registerOnboardTools(
+  pi: ExtensionAPI,
+  stateRef: StateRef,
+): void {
+  const guidelines = [
+    "Use codebase_map to understand the overall project structure. Use code_tour to walk through specific areas in detail.",
+  ];
+
+  pi.registerTool({
+    ...createCodemapTool(stateRef),
+    promptGuidelines: guidelines,
+  });
+  pi.registerTool({
+    ...createTourTool(stateRef),
+    promptGuidelines: guidelines,
+  });
+}

package/src/project.ts

@@ -0,0 +1,29 @@
+import { createHash } from "node:crypto";
+import { basename } from "node:path";
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import type { ProjectInfo } from "./types.js";
+
+function hashString(input: string): string {
+  return createHash("sha256").update(input).digest("hex").substring(0, 12);
+}
+
+export async function detectProject(
+  pi: ExtensionAPI,
+  cwd: string,
+): Promise<ProjectInfo> {
+  const name = basename(cwd);
+
+  const remoteResult = await pi.exec("git", ["remote", "get-url", "origin"], { cwd });
+  if (remoteResult.code === 0) {
+    const remote = remoteResult.stdout.trim();
+    return { id: hashString(remote), name, root: cwd, remote };
+  }
+
+  const rootResult = await pi.exec("git", ["rev-parse", "--show-toplevel"], { cwd });
+  if (rootResult.code === 0) {
+    const root = rootResult.stdout.trim();
+    return { id: hashString(root), name, root, remote: "" };
+  }
+
+  return { id: "global", name, root: cwd, remote: "" };
+}

package/src/storage.ts

@@ -0,0 +1,82 @@
+import {
+  mkdirSync,
+  readFileSync,
+  writeFileSync,
+} from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+import type { CodeMap, CodeTour, CacheEntry } from "./types.js";
+
+export function getBaseDir(): string {
+  return join(homedir(), ".pi", "compass");
+}
+
+export function getProjectDir(projectId: string, baseDir = getBaseDir()): string {
+  return join(baseDir, "projects", projectId);
+}
+
+export function getCodemapPath(projectId: string, baseDir = getBaseDir()): string {
+  return join(getProjectDir(projectId, baseDir), "codemap.json");
+}
+
+export function getToursDir(projectId: string, baseDir = getBaseDir()): string {
+  return join(getProjectDir(projectId, baseDir), "tours");
+}
+
+export function getTourPath(projectId: string, topic: string, baseDir = getBaseDir()): string {
+  return join(getToursDir(projectId, baseDir), `${topic}.json`);
+}
+
+export function ensureStorageLayout(projectId: string, baseDir = getBaseDir()): void {
+  mkdirSync(getToursDir(projectId, baseDir), { recursive: true });
+}
+
+export function loadCachedCodemap(
+  projectId: string,
+  baseDir = getBaseDir(),
+): CacheEntry<CodeMap> | null {
+  try {
+    const raw = readFileSync(getCodemapPath(projectId, baseDir), "utf-8");
+    return JSON.parse(raw) as CacheEntry<CodeMap>;
+  } catch {
+    return null;
+  }
+}
+
+export function saveCachedCodemap(
+  projectId: string,
+  entry: CacheEntry<CodeMap>,
+  baseDir = getBaseDir(),
+): void {
+  writeFileSync(
+    getCodemapPath(projectId, baseDir),
+    JSON.stringify(entry, null, 2),
+    "utf-8",
+  );
+}
+
+export function loadCachedTour(
+  projectId: string,
+  topic: string,
+  baseDir = getBaseDir(),
+): CacheEntry<CodeTour> | null {
+  try {
+    const raw = readFileSync(getTourPath(projectId, topic, baseDir), "utf-8");
+    return JSON.parse(raw) as CacheEntry<CodeTour>;
+  } catch {
+    return null;
+  }
+}
+
+export function saveCachedTour(
+  projectId: string,
+  topic: string,
+  entry: CacheEntry<CodeTour>,
+  baseDir = getBaseDir(),
+): void {
+  writeFileSync(
+    getTourPath(projectId, topic, baseDir),
+    JSON.stringify(entry, null, 2),
+    "utf-8",
+  );
+}

package/src/tour-command.ts

@@ -0,0 +1,50 @@
+import type {
+  ExtensionAPI,
+  ExtensionCommandContext,
+} from "@mariozechner/pi-coding-agent";
+import { detectAvailableTopics, getOrGenerateTour, formatTourMarkdown } from "./tour-generator.js";
+import type { StateRef } from "./types.js";
+import { getOrGenerateCodemap } from "./codemap-generator.js";
+
+export const COMMAND_NAME = "tour";
+
+export async function handleTourCommand(
+  args: string,
+  ctx: ExtensionCommandContext,
+  pi: ExtensionAPI,
+  stateRef: StateRef,
+): Promise<void> {
+  const state = stateRef.get();
+  if (!state.project) {
+    ctx.ui.notify("No project detected. Run from within a git repository.", "error");
+    return;
+  }
+
+  const codemap = state.cachedCodemap?.data
+    ?? getOrGenerateCodemap(state.project.root, state.project.id, state.project.name).codemap;
+
+  const topic = args.trim();
+
+  if (!topic) {
+    const topics = detectAvailableTopics(state.project.root, codemap);
+    if (topics.length === 0) {
+      ctx.ui.notify("No tour topics detected in this project.", "info");
+      return;
+    }
+    ctx.ui.notify(`Available tour topics:\n${topics.map((t) => `  - ${t}`).join("\n")}\n\nUsage: /tour <topic>`, "info");
+    return;
+  }
+
+  const tour = getOrGenerateTour(
+    state.project.root,
+    topic,
+    codemap,
+    state.project.id,
+  );
+
+  const markdown = formatTourMarkdown(tour);
+  pi.sendUserMessage(
+    `${markdown}\n\nAsk me about any of these files for more detail.`,
+    { deliverAs: "followUp" },
+  );
+}

package/src/tour-generator.ts

@@ -0,0 +1,237 @@
+import { readdirSync, statSync } from "node:fs";
+import { join, extname } from "node:path";
+import type { CodeMap, CodeTour, TourStep, CacheEntry } from "./types.js";
+import { loadCachedTour, saveCachedTour } from "./storage.js";
+
+const TEST_INDICATORS = ["test", "tests", "spec", "__tests__", "e2e"];
+const CI_INDICATORS = [".github", ".gitlab-ci.yml", "Jenkinsfile"];
+const DB_INDICATORS = ["migrations", "prisma", "drizzle", "alembic", "db", "database"];
+
+export function detectAvailableTopics(
+  _cwd: string,
+  codemap: CodeMap,
+): readonly string[] {
+  const topics: string[] = [];
+
+  for (const entry of codemap.directoryTree) {
+    if (entry.type === "dir" && entry.name !== "node_modules" && entry.name !== "dist") {
+      topics.push(entry.name);
+    }
+  }
+
+  const allNames = codemap.directoryTree.map((e) => e.name.toLowerCase());
+  const keyFilePaths = codemap.keyFiles.map((k) => k.path.toLowerCase());
+
+  if (TEST_INDICATORS.some((t) => allNames.includes(t))) {
+    topics.push("testing");
+  }
+  if (CI_INDICATORS.some((c) => allNames.includes(c) || keyFilePaths.some((k) => k.includes(c)))) {
+    topics.push("ci");
+  }
+  if (DB_INDICATORS.some((d) => allNames.includes(d))) {
+    topics.push("database");
+  }
+
+  return [...new Set(topics)];
+}
+
+export function generateTour(
+  cwd: string,
+  topic: string,
+  codemap: CodeMap,
+): CodeTour {
+  const steps = buildTourSteps(cwd, topic);
+
+  return {
+    projectId: codemap.projectId,
+    topic,
+    generatedAt: new Date().toISOString(),
+    steps,
+  };
+}
+
+function buildTourSteps(
+  cwd: string,
+  topic: string,
+): TourStep[] {
+  const steps: TourStep[] = [];
+
+  const topicDir = join(cwd, topic);
+  const srcTopicDir = join(cwd, "src", topic);
+
+  const dir = safeIsDir(topicDir) ? topicDir : safeIsDir(srcTopicDir) ? srcTopicDir : null;
+
+  if (dir) {
+    const files = collectFiles(dir, cwd, 3);
+    for (const file of files.slice(0, 15)) {
+      steps.push({
+        file,
+        description: describeFile(file),
+      });
+    }
+  }
+
+  if (topic === "testing") {
+    steps.push(...findTestFiles(cwd));
+  } else if (topic === "ci") {
+    steps.push(...findCiFiles(cwd));
+  }
+
+  return steps;
+}
+
+function collectFiles(dir: string, root: string, depth: number): string[] {
+  if (depth <= 0) return [];
+  const results: string[] = [];
+
+  let entries: string[];
+  try {
+    entries = readdirSync(dir);
+  } catch {
+    return [];
+  }
+
+  for (const name of entries.sort()) {
+    if (name.startsWith(".")) continue;
+    const full = join(dir, name);
+    const rel = full.slice(root.length + 1);
+
+    try {
+      const stat = statSync(full);
+      if (stat.isFile() && isSourceFile(name)) {
+        results.push(rel);
+      } else if (stat.isDirectory()) {
+        results.push(...collectFiles(full, root, depth - 1));
+      }
+    } catch {
+      continue;
+    }
+  }
+
+  return results;
+}
+
+function findTestFiles(cwd: string): TourStep[] {
+  const steps: TourStep[] = [];
+  for (const dir of TEST_INDICATORS) {
+    const full = join(cwd, dir);
+    if (safeIsDir(full)) {
+      const files = collectFiles(full, cwd, 2);
+      for (const file of files.slice(0, 5)) {
+        steps.push({ file, description: describeFile(file) });
+      }
+    }
+  }
+  return steps;
+}
+
+function findCiFiles(cwd: string): TourStep[] {
+  const steps: TourStep[] = [];
+  const workflowDir = join(cwd, ".github", "workflows");
+  if (safeIsDir(workflowDir)) {
+    try {
+      for (const name of readdirSync(workflowDir)) {
+        steps.push({
+          file: `.github/workflows/${name}`,
+          description: `CI workflow: ${name}`,
+        });
+      }
+    } catch {
+      // ignore
+    }
+  }
+
+  for (const file of [".gitlab-ci.yml", "Jenkinsfile"]) {
+    if (safeExists(join(cwd, file))) {
+      steps.push({ file, description: `CI configuration: ${file}` });
+    }
+  }
+
+  return steps;
+}
+
+function describeFile(filePath: string): string {
+  const parts = filePath.split("/");
+  const fileName = parts[parts.length - 1] ?? filePath;
+  const ext = extname(fileName);
+  const baseName = fileName.replace(ext, "");
+
+  if (fileName.includes("test") || fileName.includes("spec")) {
+    return `Test file for ${baseName.replace(/[._-]?(test|spec)/, "")}`;
+  }
+  if (fileName === "index.ts" || fileName === "index.js") {
+    const parent = parts[parts.length - 2];
+    return parent ? `Entry point for ${parent} module` : "Package entry point";
+  }
+  if (fileName.includes("config")) return `Configuration: ${baseName}`;
+  if (fileName.includes("route") || fileName.includes("router")) return `Routing: ${baseName}`;
+  if (fileName.includes("middleware")) return `Middleware: ${baseName}`;
+  if (fileName.includes("model") || fileName.includes("schema")) return `Data model: ${baseName}`;
+  if (fileName.includes("service")) return `Service: ${baseName}`;
+  if (fileName.includes("controller") || fileName.includes("handler")) return `Handler: ${baseName}`;
+  if (fileName.includes("util") || fileName.includes("helper")) return `Utility: ${baseName}`;
+
+  return `${baseName} module`;
+}
+
+const SOURCE_EXTENSIONS = new Set([
+  ".ts", ".tsx", ".js", ".jsx", ".py", ".go", ".rs", ".java",
+  ".rb", ".php", ".ex", ".exs", ".kt", ".swift", ".c", ".cpp",
+  ".h", ".yml", ".yaml", ".toml", ".json",
+]);
+
+function isSourceFile(name: string): boolean {
+  return SOURCE_EXTENSIONS.has(extname(name));
+}
+
+function safeIsDir(path: string): boolean {
+  try {
+    return statSync(path).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+function safeExists(path: string): boolean {
+  try {
+    statSync(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export function formatTourMarkdown(tour: CodeTour): string {
+  if (tour.steps.length === 0) {
+    return `No files found for topic "${tour.topic}".`;
+  }
+
+  const lines = [`## Code Tour: ${tour.topic}`, ""];
+  for (let i = 0; i < tour.steps.length; i++) {
+    const step = tour.steps[i]!;
+    lines.push(`**${i + 1}.** \`${step.file}\``);
+    lines.push(`   ${step.description}`);
+    lines.push("");
+  }
+  return lines.join("\n");
+}
+
+export function getOrGenerateTour(
+  cwd: string,
+  topic: string,
+  codemap: CodeMap,
+  projectId: string,
+  baseDir?: string,
+): CodeTour {
+  const cached = loadCachedTour(projectId, topic, baseDir);
+  if (cached) return cached.data;
+
+  const tour = generateTour(cwd, topic, codemap);
+  const entry: CacheEntry<CodeTour> = {
+    data: tour,
+    contentHash: codemap.contentHash,
+    createdAt: tour.generatedAt,
+  };
+  saveCachedTour(projectId, topic, entry, baseDir);
+  return tour;
+}