pi-compass 0.2.0

package/dist/storage.d.ts

@@ -0,0 +1,12 @@
+import type { CodeMap, CodeTour, CacheEntry } from "./types.js";
+export declare function getBaseDir(): string;
+export declare function getProjectDir(projectId: string, baseDir?: string): string;
+export declare function getCodemapPath(projectId: string, baseDir?: string): string;
+export declare function getToursDir(projectId: string, baseDir?: string): string;
+export declare function getTourPath(projectId: string, topic: string, baseDir?: string): string;
+export declare function ensureStorageLayout(projectId: string, baseDir?: string): void;
+export declare function loadCachedCodemap(projectId: string, baseDir?: string): CacheEntry<CodeMap> | null;
+export declare function saveCachedCodemap(projectId: string, entry: CacheEntry<CodeMap>, baseDir?: string): void;
+export declare function loadCachedTour(projectId: string, topic: string, baseDir?: string): CacheEntry<CodeTour> | null;
+export declare function saveCachedTour(projectId: string, topic: string, entry: CacheEntry<CodeTour>, baseDir?: string): void;
+//# sourceMappingURL=storage.d.ts.map

package/dist/storage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage.d.ts","sourceRoot":"","sources":["../src/storage.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAEhE,wBAAgB,UAAU,IAAI,MAAM,CAEnC;AAED,wBAAgB,aAAa,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,SAAe,GAAG,MAAM,CAE/E;AAED,wBAAgB,cAAc,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,SAAe,GAAG,MAAM,CAEhF;AAED,wBAAgB,WAAW,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,SAAe,GAAG,MAAM,CAE7E;AAED,wBAAgB,WAAW,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,SAAe,GAAG,MAAM,CAE5F;AAED,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,SAAe,GAAG,IAAI,CAEnF;AAED,wBAAgB,iBAAiB,CAC/B,SAAS,EAAE,MAAM,EACjB,OAAO,SAAe,GACrB,UAAU,CAAC,OAAO,CAAC,GAAG,IAAI,CAO5B;AAED,wBAAgB,iBAAiB,CAC/B,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,UAAU,CAAC,OAAO,CAAC,EAC1B,OAAO,SAAe,GACrB,IAAI,CAMN;AAED,wBAAgB,cAAc,CAC5B,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,MAAM,EACb,OAAO,SAAe,GACrB,UAAU,CAAC,QAAQ,CAAC,GAAG,IAAI,CAO7B;AAED,wBAAgB,cAAc,CAC5B,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,UAAU,CAAC,QAAQ,CAAC,EAC3B,OAAO,SAAe,GACrB,IAAI,CAMN"}

package/dist/storage.js

@@ -0,0 +1,46 @@
+import { mkdirSync, readFileSync, writeFileSync, } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+export function getBaseDir() {
+    return join(homedir(), ".pi", "compass");
+}
+export function getProjectDir(projectId, baseDir = getBaseDir()) {
+    return join(baseDir, "projects", projectId);
+}
+export function getCodemapPath(projectId, baseDir = getBaseDir()) {
+    return join(getProjectDir(projectId, baseDir), "codemap.json");
+}
+export function getToursDir(projectId, baseDir = getBaseDir()) {
+    return join(getProjectDir(projectId, baseDir), "tours");
+}
+export function getTourPath(projectId, topic, baseDir = getBaseDir()) {
+    return join(getToursDir(projectId, baseDir), `${topic}.json`);
+}
+export function ensureStorageLayout(projectId, baseDir = getBaseDir()) {
+    mkdirSync(getToursDir(projectId, baseDir), { recursive: true });
+}
+export function loadCachedCodemap(projectId, baseDir = getBaseDir()) {
+    try {
+        const raw = readFileSync(getCodemapPath(projectId, baseDir), "utf-8");
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+export function saveCachedCodemap(projectId, entry, baseDir = getBaseDir()) {
+    writeFileSync(getCodemapPath(projectId, baseDir), JSON.stringify(entry, null, 2), "utf-8");
+}
+export function loadCachedTour(projectId, topic, baseDir = getBaseDir()) {
+    try {
+        const raw = readFileSync(getTourPath(projectId, topic, baseDir), "utf-8");
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+export function saveCachedTour(projectId, topic, entry, baseDir = getBaseDir()) {
+    writeFileSync(getTourPath(projectId, topic, baseDir), JSON.stringify(entry, null, 2), "utf-8");
+}
+//# sourceMappingURL=storage.js.map

package/dist/storage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage.js","sourceRoot":"","sources":["../src/storage.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,SAAS,EACT,YAAY,EACZ,aAAa,GACd,MAAM,SAAS,CAAC;AACjB,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAGlC,MAAM,UAAU,UAAU;IACxB,OAAO,IAAI,CAAC,OAAO,EAAE,EAAE,KAAK,EAAE,SAAS,CAAC,CAAC;AAC3C,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,SAAiB,EAAE,OAAO,GAAG,UAAU,EAAE;IACrE,OAAO,IAAI,CAAC,OAAO,EAAE,UAAU,EAAE,SAAS,CAAC,CAAC;AAC9C,CAAC;AAED,MAAM,UAAU,cAAc,CAAC,SAAiB,EAAE,OAAO,GAAG,UAAU,EAAE;IACtE,OAAO,IAAI,CAAC,aAAa,CAAC,SAAS,EAAE,OAAO,CAAC,EAAE,cAAc,CAAC,CAAC;AACjE,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,SAAiB,EAAE,OAAO,GAAG,UAAU,EAAE;IACnE,OAAO,IAAI,CAAC,aAAa,CAAC,SAAS,EAAE,OAAO,CAAC,EAAE,OAAO,CAAC,CAAC;AAC1D,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,SAAiB,EAAE,KAAa,EAAE,OAAO,GAAG,UAAU,EAAE;IAClF,OAAO,IAAI,CAAC,WAAW,CAAC,SAAS,EAAE,OAAO,CAAC,EAAE,GAAG,KAAK,OAAO,CAAC,CAAC;AAChE,CAAC;AAED,MAAM,UAAU,mBAAmB,CAAC,SAAiB,EAAE,OAAO,GAAG,UAAU,EAAE;IAC3E,SAAS,CAAC,WAAW,CAAC,SAAS,EAAE,OAAO,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;AAClE,CAAC;AAED,MAAM,UAAU,iBAAiB,CAC/B,SAAiB,EACjB,OAAO,GAAG,UAAU,EAAE;IAEtB,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,YAAY,CAAC,cAAc,CAAC,SAAS,EAAE,OAAO,CAAC,EAAE,OAAO,CAAC,CAAC;QACtE,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAwB,CAAC;IAChD,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED,MAAM,UAAU,iBAAiB,CAC/B,SAAiB,EACjB,KAA0B,EAC1B,OAAO,GAAG,UAAU,EAAE;IAEtB,aAAa,CACX,cAAc,CAAC,SAAS,EAAE,OAAO,CAAC,EAClC,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,EAC9B,OAAO,CACR,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,cAAc,CAC5B,SAAiB,EACjB,KAAa,EACb,OAAO,GAAG,UAAU,EAAE;IAEtB,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,YAAY,CAAC,WAAW,CAAC,SAAS,EAAE,KAAK,EAAE,OAAO,CAAC,EAAE,OAAO,CAAC,CAAC;QAC1E,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAyB,CAAC;IACjD,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED,MAAM,UAAU,cAAc,CAC5B,SAAiB,EACjB,KAAa,EACb,KAA2B,EAC3B,OAAO,GAAG,UAAU,EAAE;IAEtB,aAAa,CACX,WAAW,CAAC,SAAS,EAAE,KAAK,EAAE,OAAO,CAAC,EACtC,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,EAC9B,OAAO,CACR,CAAC;AACJ,CAAC"}

package/dist/tour-command.d.ts

@@ -0,0 +1,5 @@
+import type { ExtensionAPI, ExtensionCommandContext } from "@mariozechner/pi-coding-agent";
+import type { StateRef } from "./types.js";
+export declare const COMMAND_NAME = "tour";
+export declare function handleTourCommand(args: string, ctx: ExtensionCommandContext, pi: ExtensionAPI, stateRef: StateRef): Promise<void>;
+//# sourceMappingURL=tour-command.d.ts.map

package/dist/tour-command.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tour-command.d.ts","sourceRoot":"","sources":["../src/tour-command.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,YAAY,EACZ,uBAAuB,EACxB,MAAM,+BAA+B,CAAC;AAEvC,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAG3C,eAAO,MAAM,YAAY,SAAS,CAAC;AAEnC,wBAAsB,iBAAiB,CACrC,IAAI,EAAE,MAAM,EACZ,GAAG,EAAE,uBAAuB,EAC5B,EAAE,EAAE,YAAY,EAChB,QAAQ,EAAE,QAAQ,GACjB,OAAO,CAAC,IAAI,CAAC,CAkCf"}

package/dist/tour-command.js

@@ -0,0 +1,26 @@
+import { detectAvailableTopics, getOrGenerateTour, formatTourMarkdown } from "./tour-generator.js";
+import { getOrGenerateCodemap } from "./codemap-generator.js";
+export const COMMAND_NAME = "tour";
+export async function handleTourCommand(args, ctx, pi, stateRef) {
+    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" });
+}
+//# sourceMappingURL=tour-command.js.map

package/dist/tour-command.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tour-command.js","sourceRoot":"","sources":["../src/tour-command.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,qBAAqB,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAEnG,OAAO,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AAE9D,MAAM,CAAC,MAAM,YAAY,GAAG,MAAM,CAAC;AAEnC,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,IAAY,EACZ,GAA4B,EAC5B,EAAgB,EAChB,QAAkB;IAElB,MAAM,KAAK,GAAG,QAAQ,CAAC,GAAG,EAAE,CAAC;IAC7B,IAAI,CAAC,KAAK,CAAC,OAAO,EAAE,CAAC;QACnB,GAAG,CAAC,EAAE,CAAC,MAAM,CAAC,wDAAwD,EAAE,OAAO,CAAC,CAAC;QACjF,OAAO;IACT,CAAC;IAED,MAAM,OAAO,GAAG,KAAK,CAAC,aAAa,EAAE,IAAI;WACpC,oBAAoB,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,EAAE,KAAK,CAAC,OAAO,CAAC,EAAE,EAAE,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,OAAO,CAAC;IAE5F,MAAM,KAAK,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC;IAE1B,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,MAAM,MAAM,GAAG,qBAAqB,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;QAClE,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACxB,GAAG,CAAC,EAAE,CAAC,MAAM,CAAC,0CAA0C,EAAE,MAAM,CAAC,CAAC;YAClE,OAAO;QACT,CAAC;QACD,GAAG,CAAC,EAAE,CAAC,MAAM,CAAC,2BAA2B,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,0BAA0B,EAAE,MAAM,CAAC,CAAC;QACrH,OAAO;IACT,CAAC;IAED,MAAM,IAAI,GAAG,iBAAiB,CAC5B,KAAK,CAAC,OAAO,CAAC,IAAI,EAClB,KAAK,EACL,OAAO,EACP,KAAK,CAAC,OAAO,CAAC,EAAE,CACjB,CAAC;IAEF,MAAM,QAAQ,GAAG,kBAAkB,CAAC,IAAI,CAAC,CAAC;IAC1C,EAAE,CAAC,eAAe,CAChB,GAAG,QAAQ,sDAAsD,EACjE,EAAE,SAAS,EAAE,UAAU,EAAE,CAC1B,CAAC;AACJ,CAAC"}

package/dist/tour-generator.d.ts

@@ -0,0 +1,6 @@
+import type { CodeMap, CodeTour } from "./types.js";
+export declare function detectAvailableTopics(_cwd: string, codemap: CodeMap): readonly string[];
+export declare function generateTour(cwd: string, topic: string, codemap: CodeMap): CodeTour;
+export declare function formatTourMarkdown(tour: CodeTour): string;
+export declare function getOrGenerateTour(cwd: string, topic: string, codemap: CodeMap, projectId: string, baseDir?: string): CodeTour;
+//# sourceMappingURL=tour-generator.d.ts.map

package/dist/tour-generator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tour-generator.d.ts","sourceRoot":"","sources":["../src/tour-generator.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAwB,MAAM,YAAY,CAAC;AAO1E,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,OAAO,GACf,SAAS,MAAM,EAAE,CAuBnB;AAED,wBAAgB,YAAY,CAC1B,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,OAAO,GACf,QAAQ,CASV;AAyJD,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,QAAQ,GAAG,MAAM,CAazD;AAED,wBAAgB,iBAAiB,CAC/B,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,OAAO,EAChB,SAAS,EAAE,MAAM,EACjB,OAAO,CAAC,EAAE,MAAM,GACf,QAAQ,CAYV"}

package/dist/tour-generator.js

@@ -0,0 +1,204 @@
+import { readdirSync, statSync } from "node:fs";
+import { join, extname } from "node:path";
+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, codemap) {
+    const topics = [];
+    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, topic, codemap) {
+    const steps = buildTourSteps(cwd, topic);
+    return {
+        projectId: codemap.projectId,
+        topic,
+        generatedAt: new Date().toISOString(),
+        steps,
+    };
+}
+function buildTourSteps(cwd, topic) {
+    const steps = [];
+    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, root, depth) {
+    if (depth <= 0)
+        return [];
+    const results = [];
+    let entries;
+    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) {
+    const steps = [];
+    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) {
+    const steps = [];
+    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) {
+    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) {
+    return SOURCE_EXTENSIONS.has(extname(name));
+}
+function safeIsDir(path) {
+    try {
+        return statSync(path).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+function safeExists(path) {
+    try {
+        statSync(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export function formatTourMarkdown(tour) {
+    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, topic, codemap, projectId, baseDir) {
+    const cached = loadCachedTour(projectId, topic, baseDir);
+    if (cached)
+        return cached.data;
+    const tour = generateTour(cwd, topic, codemap);
+    const entry = {
+        data: tour,
+        contentHash: codemap.contentHash,
+        createdAt: tour.generatedAt,
+    };
+    saveCachedTour(projectId, topic, entry, baseDir);
+    return tour;
+}
+//# sourceMappingURL=tour-generator.js.map

package/dist/tour-generator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tour-generator.js","sourceRoot":"","sources":["../src/tour-generator.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -0,0 +1,89 @@
+export interface ProjectInfo {
+    readonly id: string;
+    readonly name: string;
+    readonly root: string;
+    readonly remote: string;
+}
+export interface DirectoryEntry {
+    readonly name: string;
+    readonly type: "file" | "dir";
+    readonly children?: readonly DirectoryEntry[];
+}
+export type PackageManager = "npm" | "cargo" | "go" | "pip" | "poetry" | "gradle" | "maven" | "composer" | "bundler" | "mix";
+export interface PackageInfo {
+    readonly manager: PackageManager;
+    readonly name: string;
+    readonly version?: string;
+    readonly dependencies: readonly string[];
+}
+export interface FrameworkDetection {
+    readonly name: string;
+    readonly version?: string;
+    readonly confidence: "definite" | "likely";
+    readonly source: string;
+}
+export type EntryPointKind = "main" | "index" | "route" | "handler" | "config";
+export interface EntryPoint {
+    readonly path: string;
+    readonly kind: EntryPointKind;
+}
+export interface BuildScript {
+    readonly name: string;
+    readonly command: string;
+    readonly source: string;
+}
+export interface Convention {
+    readonly source: string;
+    readonly content: string;
+}
+export interface KeyFile {
+    readonly path: string;
+    readonly description: string;
+}
+export interface CodeMap {
+    readonly projectId: string;
+    readonly projectName: string;
+    readonly generatedAt: string;
+    readonly contentHash: string;
+    readonly directoryTree: readonly DirectoryEntry[];
+    readonly packages: readonly PackageInfo[];
+    readonly frameworks: readonly FrameworkDetection[];
+    readonly entryPoints: readonly EntryPoint[];
+    readonly buildScripts: readonly BuildScript[];
+    readonly conventions: readonly Convention[];
+    readonly keyFiles: readonly KeyFile[];
+}
+export interface TourStep {
+    readonly file: string;
+    readonly startLine?: number;
+    readonly endLine?: number;
+    readonly description: string;
+}
+export interface CodeTour {
+    readonly projectId: string;
+    readonly topic: string;
+    readonly generatedAt: string;
+    readonly steps: readonly TourStep[];
+}
+export interface CacheEntry<T> {
+    readonly data: T;
+    readonly contentHash: string;
+    readonly createdAt: string;
+}
+export interface CompassConfig {
+    readonly max_injection_chars: number;
+    readonly inject_on_first_turn: boolean;
+    readonly cache_enabled: boolean;
+}
+export interface StateRef {
+    get: () => CompassState;
+    set: (s: CompassState) => void;
+}
+export interface CompassState {
+    readonly project: ProjectInfo | null;
+    readonly turnCount: number;
+    readonly codemapInjected: boolean;
+    readonly cachedCodemap: CacheEntry<CodeMap> | null;
+    readonly stale: boolean;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/package.json

@@ -0,0 +1,71 @@
+{
+  "name": "pi-compass",
+  "version": "0.2.0",
+  "description": "A Pi extension that generates structured codebase maps and interactive code tours for agent onboarding.",
+  "type": "module",
+  "license": "MIT",
+  "author": "Matt Devy",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/MattDevy/pi-extensions.git",
+    "directory": "packages/pi-compass"
+  },
+  "homepage": "https://github.com/MattDevy/pi-extensions/tree/main/packages/pi-compass#readme",
+  "bugs": {
+    "url": "https://github.com/MattDevy/pi-extensions/issues"
+  },
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "pi-coding-agent",
+    "codebase-onboarding",
+    "codemap",
+    "code-tour",
+    "ai",
+    "llm",
+    "ai-agent",
+    "coding-assistant",
+    "developer-tools"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "dist",
+    "src",
+    "!src/**/*.test.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "pi": {
+    "extensions": [
+      "dist/index.js"
+    ]
+  },
+  "scripts": {
+    "clean": "rm -rf dist tsconfig.build.tsbuildinfo",
+    "build": "npm run clean && tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "lint": "eslint src/",
+    "check": "vitest run && eslint src/ && tsc --noEmit",
+    "prepublishOnly": "npm run build && npm run check",
+    "prepack": "test -d dist || { echo 'Error: dist/ missing. Run npm run build first.' && exit 1; }"
+  },
+  "peerDependencies": {
+    "@mariozechner/pi-coding-agent": "^0.62.0",
+    "@mariozechner/pi-ai": "^0.62.0",
+    "@mariozechner/pi-tui": "^0.62.0",
+    "@sinclair/typebox": "^0.34.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "@typescript-eslint/eslint-plugin": "^8.0.0",
+    "@typescript-eslint/parser": "^8.0.0",
+    "eslint": "^9.0.0",
+    "typescript": "^5.7.0",
+    "vitest": "^3.0.0"
+  }
+}

package/src/analyzers/build-script-detector.ts

@@ -0,0 +1,85 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import type { BuildScript } from "../types.js";
+
+const INTERESTING_SCRIPTS = new Set([
+  "build", "dev", "start", "test", "lint", "check",
+  "typecheck", "format", "deploy", "clean", "serve",
+  "preview", "generate", "migrate", "seed",
+]);
+
+export function detectBuildScripts(cwd: string): readonly BuildScript[] {
+  const results: BuildScript[] = [];
+
+  results.push(...extractNpmScripts(cwd));
+  results.push(...extractMakefileTargets(cwd));
+  results.push(...detectCiFiles(cwd));
+  results.push(...detectContainerFiles(cwd));
+
+  return results;
+}
+
+function extractNpmScripts(cwd: string): BuildScript[] {
+  try {
+    const raw = readFileSync(join(cwd, "package.json"), "utf-8");
+    const pkg = JSON.parse(raw) as Record<string, unknown>;
+    const scripts = pkg["scripts"];
+    if (!scripts || typeof scripts !== "object") return [];
+
+    return Object.entries(scripts as Record<string, unknown>)
+      .filter(([name]) => INTERESTING_SCRIPTS.has(name))
+      .map(([name, cmd]) => ({
+        name,
+        command: typeof cmd === "string" ? cmd : String(cmd),
+        source: "package.json",
+      }));
+  } catch {
+    return [];
+  }
+}
+
+function extractMakefileTargets(cwd: string): BuildScript[] {
+  const makefilePath = join(cwd, "Makefile");
+  try {
+    const content = readFileSync(makefilePath, "utf-8");
+    const targets = [...content.matchAll(/^([a-zA-Z_][\w-]*)\s*:/gm)];
+    return targets
+      .filter(([, name]) => name && !name.startsWith("."))
+      .map(([, name]) => ({
+        name: name!,
+        command: `make ${name}`,
+        source: "Makefile",
+      }));
+  } catch {
+    return [];
+  }
+}
+
+function detectCiFiles(cwd: string): BuildScript[] {
+  const results: BuildScript[] = [];
+
+  if (existsSync(join(cwd, ".github", "workflows"))) {
+    results.push({ name: "ci", command: "GitHub Actions", source: ".github/workflows/" });
+  }
+  if (existsSync(join(cwd, ".gitlab-ci.yml"))) {
+    results.push({ name: "ci", command: "GitLab CI", source: ".gitlab-ci.yml" });
+  }
+  if (existsSync(join(cwd, "Jenkinsfile"))) {
+    results.push({ name: "ci", command: "Jenkins", source: "Jenkinsfile" });
+  }
+
+  return results;
+}
+
+function detectContainerFiles(cwd: string): BuildScript[] {
+  const results: BuildScript[] = [];
+
+  if (existsSync(join(cwd, "Dockerfile"))) {
+    results.push({ name: "docker", command: "docker build", source: "Dockerfile" });
+  }
+  if (existsSync(join(cwd, "docker-compose.yml")) || existsSync(join(cwd, "docker-compose.yaml"))) {
+    results.push({ name: "docker-compose", command: "docker compose up", source: "docker-compose.yml" });
+  }
+
+  return results;
+}

package/src/analyzers/convention-detector.ts

@@ -0,0 +1,52 @@
+import { join } from "node:path";
+import type { Convention } from "../types.js";
+import { readTextFile } from "../fs-utils.js";
+
+const MAX_CONTENT_LENGTH = 2000;
+
+const CONVENTION_FILES: readonly string[] = [
+  "AGENTS.md",
+  "CLAUDE.md",
+  "GEMINI.md",
+  ".editorconfig",
+  "eslint.config.js",
+  "eslint.config.ts",
+  "eslint.config.mjs",
+  ".eslintrc.json",
+  ".eslintrc.js",
+  ".eslintrc.yml",
+  "prettier.config.js",
+  "prettier.config.ts",
+  ".prettierrc",
+  ".prettierrc.json",
+  "biome.json",
+  "biome.jsonc",
+  "rustfmt.toml",
+  ".golangci.yml",
+  ".golangci.yaml",
+  "CONTRIBUTING.md",
+  ".stylelintrc.json",
+  "deno.json",
+  "deno.jsonc",
+];
+
+export function detectConventions(cwd: string): readonly Convention[] {
+  const results: Convention[] = [];
+
+  for (const file of CONVENTION_FILES) {
+    const content = readTextFile(join(cwd, file));
+    if (content !== null) {
+      results.push({
+        source: file,
+        content: truncate(content, MAX_CONTENT_LENGTH),
+      });
+    }
+  }
+
+  return results;
+}
+
+function truncate(text: string, maxLength: number): string {
+  if (text.length <= maxLength) return text;
+  return text.slice(0, maxLength) + "\n... (truncated)";
+}