pi-skill-search 0.1.0

package/src/scanner.ts

@@ -0,0 +1,85 @@
+/**
+ * Custom directory scanner — doc skills tu thu muc chinh thuc
+ * do pi-skill-search quan ly, doc lap voi Pi's skill discovery.
+ *
+ * Scan `skills/` trong extension root, parse SKILL.md frontmatter,
+ * tra ve PiSkill[] de extension index.
+ * Pi KHONG quet thu muc nay khi khoi dong — extension tu scan.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import type { PiSkill } from "./types.ts";
+
+/**
+ * Parse YAML frontmatter tu SKILL.md content.
+ * Chi extract `name` va `description` — cac fields khac bo qua.
+ */
+export function parseFrontmatter(content: string): { name: string; description: string } | null {
+	const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+	if (!match) return null;
+	const fm = match[1];
+	let name = "";
+	let description = "";
+	for (const line of fm.split(/\r?\n/)) {
+		const nameMatch = line.match(/^name:\s*(.+)$/);
+		if (nameMatch) name = nameMatch[1].trim();
+		const descMatch = line.match(/^description:\s*(.+)$/);
+		if (descMatch) description = descMatch[1].trim();
+	}
+	if (!name) return null;
+	return { name, description };
+}
+
+/**
+ * Scan mot thu muc de tim tat ca SKILL.md.
+ * Moi subdirectory chua SKILL.md la mot skill.
+ */
+export function scanSkillDirectory(dir: string): PiSkill[] {
+	if (!fs.existsSync(dir)) return [];
+
+	const skills: PiSkill[] = [];
+
+	try {
+		const entries = fs.readdirSync(dir, { withFileTypes: true });
+		for (const entry of entries) {
+			if (!entry.isDirectory()) continue;
+			const skillFile = path.join(dir, entry.name, "SKILL.md");
+			if (!fs.existsSync(skillFile)) continue;
+
+			try {
+				const content = fs.readFileSync(skillFile, "utf-8");
+				const parsed = parseFrontmatter(content);
+				if (!parsed) continue;
+
+				skills.push({
+					name: parsed.name,
+					description: parsed.description,
+					filePath: skillFile,
+					disableModelInvocation: false,
+				});
+			} catch {
+				// Skip unreadable files
+			}
+		}
+	} catch {
+		// Directory unreadable
+	}
+
+	return skills;
+}
+
+/**
+ * Resolve extension root — thu muc chua index.ts cua extension.
+ * Jiti/TS loader suong __dirname tu import.meta.
+ */
+export function resolveExtensionRoot(): string {
+	const thisFile = path.dirname(
+		new URL(import.meta.url).pathname
+			// Windows: strip leading / from file:///C:/...
+			.replace(/^\/([A-Z]:)/, "$1"),
+	);
+	// thisFile = <root>/src khi chay tu src, hoac <root> khi chay tu index.ts
+	// Check: neu thisFile ten la "src" thi len 1 level
+	if (path.basename(thisFile) === "src") return path.dirname(thisFile);
+	return thisFile;
+}

package/src/search.ts

@@ -0,0 +1,89 @@
+import { expandQuery } from "./synonyms.ts";
+import { tokenize } from "./text.ts";
+/**
+ * Search algorithm — tinh diem va rank skills theo query.
+ * Implement theo SPEC §5.1 scoring formula.
+ */
+import type { SearchResult, SkillIndex } from "./types.ts";
+
+/**
+ * Tim kiem skills trong index theo query.
+ *
+ * Scoring per SPEC §5.1:
+ *   +50  exact name match
+ *   +20  per name-token match
+ *   +3   per first-120-char description-token match
+ *   +1   per remaining description-token match
+ *   +5   per category-keyword match
+ *
+ * Synonym expansion truoc khi scoring (expandQuery).
+ * Sort by score desc, ties broken by name asc.
+ */
+export function search(index: SkillIndex, query: string, limit: number): SearchResult[] {
+	// Expand query voi synonyms
+	const expandedTokens = expandQuery(query);
+	const queryTokens = tokenize(query);
+
+	if (queryTokens.size === 0 && expandedTokens.size === 0) {
+		return [];
+	}
+
+	const results: SearchResult[] = [];
+
+	for (const entry of index.entries.values()) {
+		let score = 0;
+		const nameLower = entry.name.toLowerCase();
+
+		// Exact name match
+		if (nameLower === query.toLowerCase().trim()) {
+			score += 50;
+		}
+
+		// Score moi expanded token
+		for (const token of expandedTokens) {
+			// Name token match
+			if (entry.nameTokens.has(token)) {
+				score += 20;
+			}
+
+			// Description split at 120 chars
+			const desc = entry.description;
+			const first120 = desc.slice(0, 120).toLowerCase();
+			const rest = desc.slice(120).toLowerCase();
+
+			const first120Tokens = tokenize(first120);
+			const restTokens = tokenize(rest);
+
+			if (first120Tokens.has(token)) {
+				score += 5;
+			}
+			if (restTokens.has(token)) {
+				score += 2;
+			}
+
+			// Category keyword match
+			for (const cat of entry.categories) {
+				if (cat.toLowerCase().includes(token)) {
+					score += 5;
+				}
+			}
+		}
+
+		if (score > 0) {
+			results.push({
+				name: entry.name,
+				description: entry.description,
+				path: entry.path,
+				score,
+			});
+		}
+	}
+
+	// Sort: score desc, then name asc
+	results.sort((a, b) => {
+		if (b.score !== a.score) return b.score - a.score;
+		return a.name.localeCompare(b.name);
+	});
+
+	return results.slice(0, limit);
+}

package/src/strip.ts

@@ -0,0 +1,29 @@
+/**
+ * Strip regex — loai bo Pi's auto-injected <available_skills> block.
+ * Implement theo SPEC §7.3.
+ */
+
+/**
+ * Regex de match <available_skills> block tu Pi's formatSkillsForPrompt().
+ * Anchor vao lead-in sentence: "The following skills provide specialized instructions"
+ * Ket thuc bang </available_skills> tag.
+ */
+export const AVAILABLE_SKILLS_BLOCK_REGEX =
+	/\n*The following skills provide specialized instructions[\s\S]*?<\/available_skills>/;
+
+/**
+ * Strip <available_skills> block tu system prompt.
+ * Neu khong tim thay → no-op, tra ve original string.
+ */
+export function stripAvailableSkillsBlock(systemPrompt: string): string {
+	return systemPrompt.replace(AVAILABLE_SKILLS_BLOCK_REGEX, "");
+}
+
+/**
+ * Drift detector — kiem tra xem regex co match trong systemPrompt khong.
+ * Tra ve true neu block duoc tim thay va stripped.
+ * Tra ve false neu khong tim thay (Pi co the da thay doi format).
+ */
+export function detectSkillsBlock(systemPrompt: string): boolean {
+	return AVAILABLE_SKILLS_BLOCK_REGEX.test(systemPrompt);
+}

package/src/synonyms.ts

@@ -0,0 +1,83 @@
+/**
+ * Tu dong ngu (synonym dictionary) — SPEC §5.2.
+ * Moi entry key → danh sach tu dong ngu, cho phep expand query.
+ */
+import { tokenize } from "./text.ts";
+
+/**
+ * Bang tu dong ngu. Moi key danh cho cac tu co cung nghia.
+ * Bidirectional — moi cap phai duoc mirror thuan nghich.
+ */
+export const SYNONYMS: Record<string, string[]> = {
+	// Chemistry
+	molecule: ["molecular", "molecules", "compound"],
+	molecular: ["molecule", "molecules", "compound"],
+	drug: ["pharmaceutical", "medicinal"],
+	chem: ["chemistry", "chemical", "rdkit", "cheminformatics"],
+	docking: ["dock", "binding", "pose", "diffdock"],
+	admet: ["absorption", "distribution", "metabolism", "excretion", "toxicity"],
+	metabolism: ["metabolic", "metabolite", "pathway", "flux"],
+	metabolic: ["metabolism", "metabolite", "pathway", "flux"],
+	smiles: ["rdkit", "molecular", "cheminformatics", "compound"],
+
+	// Biology
+	gene: ["genomic", "genomics", "sequence", "dna", "rna"],
+	protein: ["proteomics", "peptide", "amino acid"],
+	"single-cell": ["scrna-seq", "single cell", "scrnaseq", "scanpy", "anndata"],
+	"rna-seq": ["transcriptom", "rna seq", "expression", "scrna"],
+	dna: ["genome", "genomic", "sequence", "biopython"],
+	sequence: ["dna", "rna", "protein", "genome", "alignment"],
+
+	// ML
+	ml: ["machine learning", "machine-learning"],
+	dl: ["deep learning", "deep-learning", "neural network"],
+	nlp: ["natural language", "text mining"],
+
+	// Clinical
+	clinical: ["medical", "patient", "healthcare"],
+
+	// Physics
+	quantum: ["qubit", "quantum computing"],
+
+	// General
+	viz: ["visualization", "plotting", "chart", "matplotlib", "seaborn"],
+	stats: ["statistics", "statistical", "scipy"],
+	db: ["database"],
+	// Search & tools
+	pdf: ["markitdown", "convert", "document"],
+	markitdown: ["pdf", "convert", "document", "docx", "pptx"],
+	// Agent/dev workflow
+	delegation: ["subagent", "dispatch", "parallel"],
+	parallel: ["concurrent", "delegation", "dispatch"],
+	agent: ["subagent", "delegation", "worker"],
+	// Lab
+	robot: ["opentrons", "pylabrobot", "automation"],
+	opentrons: ["robot", "lab automation", "liquid handling"],
+	// Neural network
+	"neural network": ["pytorch", "deep learning", "tensorflow"],
+	"deep learning": ["pytorch", "neural network", "tensorflow"],
+};
+
+/**
+ * Expand query tokens voi tu dong ngu.
+ * Tokenize query truoc, sau do union them tat ca synonym values.
+ */
+export function expandQuery(query: string): Set<string> {
+	const tokens = tokenize(query);
+	const expanded = new Set(tokens);
+
+	for (const token of tokens) {
+		const synonyms = SYNONYMS[token];
+		if (synonyms) {
+			for (const syn of synonyms) {
+				// Tokenize moi synonym vi co the la multi-word ("machine learning")
+				const synTokens = tokenize(syn);
+				for (const st of synTokens) {
+					expanded.add(st);
+				}
+			}
+		}
+	}
+
+	return expanded;
+}

package/src/text.ts

@@ -0,0 +1,118 @@
+/**
+ * Tokenization — chuyen text thanh set cua tokens.
+ * Implement theo SPEC §5.3.
+ */
+
+/**
+ * Tokenize text thanh Set cua lowercase tokens.
+ * - Split hyphenated names (-, _, /)
+ * - Remove punctuation va non-alphanumeric chars
+ * - Skip 1-char tokens (deliberate trade-off)
+ * - Deduplicate qua Set
+ */
+const STOPWORDS = new Set([
+	"the",
+	"a",
+	"an",
+	"is",
+	"are",
+	"was",
+	"were",
+	"be",
+	"been",
+	"being",
+	"have",
+	"has",
+	"had",
+	"do",
+	"does",
+	"did",
+	"will",
+	"would",
+	"could",
+	"should",
+	"may",
+	"might",
+	"shall",
+	"can",
+	"to",
+	"of",
+	"in",
+	"for",
+	"on",
+	"with",
+	"at",
+	"by",
+	"from",
+	"as",
+	"into",
+	"through",
+	"during",
+	"before",
+	"after",
+	"above",
+	"below",
+	"and",
+	"or",
+	"but",
+	"not",
+	"no",
+	"nor",
+	"it",
+	"its",
+	"this",
+	"that",
+	"these",
+	"those",
+	"i",
+	"me",
+	"my",
+	"we",
+	"our",
+	"you",
+	"your",
+	"he",
+	"she",
+	"they",
+	"them",
+	"their",
+	"what",
+	"which",
+	"who",
+	"whom",
+	"how",
+	"when",
+	"where",
+	"why",
+	"all",
+	"each",
+	"every",
+	"both",
+	"few",
+	"more",
+	"most",
+	"other",
+	"some",
+	"such",
+	"than",
+	"too",
+	"very",
+	"just",
+	"about",
+	"also",
+	"then",
+	"up",
+	"out",
+	"if",
+]);
+
+export function tokenize(text: string): Set<string> {
+	return new Set(
+		text
+			.toLowerCase()
+			.replace(/[-_/]/g, " ")
+			.replace(/[^a-z0-9\s]/g, "")
+			.split(/\s+/)
+			.filter((w) => w.length >= 2 && !STOPWORDS.has(w)),
+	);
+}

package/src/types.ts

@@ -0,0 +1,64 @@
+/**
+ * Domain types cho pi-skill-search extension.
+ * PiSkill la subset cua Pi's Skill interface (skills.ts:75).
+ * Extension khong import Skill tu package vi no khong duoc export.
+ */
+import type {
+	BeforeAgentStartEvent,
+	BeforeAgentStartEventResult,
+	BuildSystemPromptOptions,
+	ExtensionAPI,
+	ToolCallEvent,
+} from "@earendil-works/pi-coding-agent";
+
+// Re-export Pi event types cho convenience
+export type {
+	BeforeAgentStartEvent,
+	BeforeAgentStartEventResult,
+	BuildSystemPromptOptions,
+	ExtensionAPI,
+	ToolCallEvent,
+};
+
+/**
+ * Subset cua Pi's Skill interface (skills.ts:75) ma extension can.
+ * Khong export tu @earendil-works/pi-coding-agent — phai khai bao local.
+ */
+export interface PiSkill {
+	name: string;
+	description: string;
+	filePath: string;
+	disableModelInvocation: boolean;
+}
+
+/** Internal representation cua mot skill da duoc index */
+export interface SkillEntry {
+	name: string;
+	description: string;
+	path: string;
+	categories: string[];
+	nameTokens: Set<string>;
+	descTokens: Set<string>;
+}
+
+/** Ket qua tim kiem cho mot skill */
+export interface SearchResult {
+	name: string;
+	description: string;
+	path: string;
+	score: number;
+}
+
+/** Tom tat mot category voi so luong va vi du */
+export interface CategorySummary {
+	name: string;
+	count: number;
+	examples: string[];
+}
+
+/** Index chinh cua toan bo skills */
+export interface SkillIndex {
+	entries: Map<string, SkillEntry>;
+	categories: CategorySummary[];
+	nameIndex: Map<string, string>;
+}