@hienlh/ppm 0.9.80 → 0.9.82

package/src/services/ppm-dir.ts

@@ -0,0 +1,14 @@
+import { resolve } from "node:path";
+import { homedir } from "node:os";
+
+let _dir: string | undefined;
+
+/** Centralized PPM directory resolution. Respects PPM_HOME env var for test isolation. */
+export function getPpmDir(): string {
+  return (_dir ??= resolve(process.env.PPM_HOME || resolve(homedir(), ".ppm")));
+}
+
+/** Reset cached dir (for test teardown if needed) */
+export function _resetPpmDir(): void {
+  _dir = undefined;
+}

package/src/services/slash-discovery/builtin-commands.ts

@@ -0,0 +1,53 @@
+import type { SlashItem } from "./types.ts";
+
+export interface BuiltinSlashCommand {
+  name: string;
+  summary: string;
+  category: "session" | "tools" | "config";
+  argumentHint?: string;
+  aliases?: string[];
+  /** "ppm" = PPM intercepts and executes, "sdk" = passed through to Claude SDK */
+  handler: "ppm" | "sdk";
+}
+
+/** Static registry of built-in slash commands */
+const BUILTIN_COMMANDS: BuiltinSlashCommand[] = [
+  // PPM-executed commands (intercepted before SDK)
+  { name: "skills", summary: "List available skills and their sources", category: "tools", aliases: ["sk"], handler: "ppm" },
+  { name: "version", summary: "Show PPM and SDK version info", category: "session", handler: "ppm" },
+  // SDK-passthrough commands (picker hints, SDK handles execution)
+  { name: "help", summary: "Show available commands and skills", category: "session", handler: "sdk" },
+  { name: "status", summary: "Show session status and context usage", category: "session", handler: "sdk" },
+  { name: "cost", summary: "Show token usage and estimated cost", category: "session", handler: "sdk" },
+  { name: "compact", summary: "Compact conversation to reduce context", category: "session", handler: "sdk" },
+  { name: "model", summary: "View or change the AI model", category: "config", argumentHint: "[model-name]", handler: "sdk" },
+  { name: "config", summary: "View or modify configuration", category: "config", handler: "sdk" },
+  { name: "memory", summary: "View or edit AI memory", category: "config", handler: "sdk" },
+];
+
+/** Convert builtin commands to SlashItem[] for the picker */
+export function getBuiltinSlashItems(): SlashItem[] {
+  return BUILTIN_COMMANDS.map((cmd) => ({
+    type: "builtin" as const,
+    name: cmd.name,
+    description: cmd.summary,
+    argumentHint: cmd.argumentHint,
+    scope: "bundled" as const,
+    category: cmd.category,
+    aliases: cmd.aliases,
+  }));
+}
+
+/** Look up a builtin command by name (or alias) */
+export function getBuiltinByName(name: string): BuiltinSlashCommand | undefined {
+  const lower = name.toLowerCase();
+  return BUILTIN_COMMANDS.find(
+    (cmd) => cmd.name === lower || cmd.aliases?.includes(lower),
+  );
+}
+
+/** Check if a command name is PPM-handled (not passed through to SDK) */
+export function isPpmHandled(name: string): boolean {
+  const cmd = getBuiltinByName(name);
+  return cmd?.handler === "ppm";
+}

package/src/services/slash-discovery/builtin-handlers.ts

@@ -0,0 +1,65 @@
+import { VERSION } from "../../version.ts";
+import { getBuiltinByName } from "./builtin-commands.ts";
+import { discoverSkillRoots } from "./discover-skill-roots.ts";
+import { loadItemsFromRoots } from "./skill-loader.ts";
+import { resolveOverrides } from "./resolve-overrides.ts";
+
+/**
+ * Handle the /skills built-in command.
+ * Returns a formatted text listing of discovered skills.
+ */
+function handleSkills(projectPath: string): string {
+  // Call pipeline directly to avoid circular dependency with index.ts
+  const roots = discoverSkillRoots(projectPath);
+  const rawItems = loadItemsFromRoots(roots);
+  const result = resolveOverrides(rawItems, roots);
+
+  const lines: string[] = ["**Discovered Skills & Commands**\n"];
+
+  if (result.roots.length > 0) {
+    lines.push("Roots:");
+    for (const root of result.roots) {
+      lines.push(`  ${root.path}  (${root.source})`);
+    }
+    lines.push("");
+  }
+
+  const skills = result.active.filter((i) => i.type === "skill");
+  const commands = result.active.filter((i) => i.type === "command");
+
+  lines.push(`${skills.length} skills, ${commands.length} commands (${result.shadowed.length} shadowed)\n`);
+
+  for (const item of result.active) {
+    if (item.type === "builtin") continue;
+    lines.push(`  /${item.name}  [${item.type}]  ${item.source}  — ${item.description || "(no description)"}`);
+  }
+
+  if (result.shadowed.length > 0) {
+    lines.push("\nShadowed:");
+    for (const item of result.shadowed) {
+      lines.push(`  /${item.name}  [${item.type}]  ${item.source}  ← shadowed by ${item.shadowedBy.source}`);
+    }
+  }
+
+  return lines.join("\n");
+}
+
+/** Handle the /version built-in command */
+function handleVersion(): string {
+  return `PPM v${VERSION}`;
+}
+
+/**
+ * Execute a PPM-handled built-in command.
+ * Returns the response text, or null if not a PPM-handled command.
+ */
+export function executeBuiltin(name: string, projectPath: string): string | null {
+  const cmd = getBuiltinByName(name);
+  if (!cmd || cmd.handler !== "ppm") return null;
+
+  switch (cmd.name) {
+    case "skills": return handleSkills(projectPath);
+    case "version": return handleVersion();
+    default: return null;
+  }
+}

package/src/services/slash-discovery/definition-source.ts

@@ -0,0 +1,27 @@
+import type { DefinitionSource, SlashItemScope } from "./types.ts";
+
+/** Numeric priority — lower = higher priority */
+export const SOURCE_PRIORITY: Record<DefinitionSource, number> = {
+  "project-ppm": 0,
+  "project-claw": 1,
+  "project-codex": 2,
+  "project-claude": 3,
+  "env-var": 4,
+  "user-ppm": 5,
+  "user-claw": 6,
+  "user-codex": 7,
+  "user-claude": 8,
+  "bundled": 9,
+};
+
+/** Compare two sources by priority (for sorting highest-priority first) */
+export function compareSourcePriority(a: DefinitionSource, b: DefinitionSource): number {
+  return SOURCE_PRIORITY[a] - SOURCE_PRIORITY[b];
+}
+
+/** Map a DefinitionSource to the user-facing scope label */
+export function sourceToScope(source: DefinitionSource): SlashItemScope {
+  if (source === "bundled") return "bundled";
+  if (source.startsWith("project-") || source === "env-var") return "project";
+  return "user";
+}

package/src/services/slash-discovery/discover-skill-roots.ts

@@ -0,0 +1,128 @@
+import { resolve, dirname } from "node:path";
+import { existsSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { fileURLToPath } from "node:url";
+import type { SkillRoot, DefinitionSource, ItemOrigin } from "./types.ts";
+
+/** Tool ecosystem prefixes mapped to their DefinitionSource for project-level roots */
+const PROJECT_ECOSYSTEMS: Array<{ dir: string; source: DefinitionSource }> = [
+  { dir: ".ppm", source: "project-ppm" },
+  { dir: ".claw", source: "project-claw" },
+  { dir: ".codex", source: "project-codex" },
+  { dir: ".claude", source: "project-claude" },
+];
+
+/** User-global ecosystem roots (same prefixes, different source) */
+const USER_ECOSYSTEMS: Array<{ dir: string; source: DefinitionSource }> = [
+  { dir: ".ppm", source: "user-ppm" },
+  { dir: ".claw", source: "user-claw" },
+  { dir: ".codex", source: "user-codex" },
+  { dir: ".claude", source: "user-claude" },
+];
+
+const ORIGINS: ItemOrigin[] = ["skills", "commands"];
+
+/** Resolve PPM package root for bundled skills */
+const PKG_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "../../..");
+const BUNDLED_SKILLS_DIR = resolve(PKG_ROOT, "assets/skills");
+
+/** Check if a path is a readable directory */
+function isDir(p: string): boolean {
+  try { return statSync(p).isDirectory(); } catch { return false; }
+}
+
+/** Push root if the directory exists and hasn't been seen yet */
+function addRoot(
+  roots: SkillRoot[],
+  seen: Set<string>,
+  basePath: string,
+  origin: ItemOrigin,
+  source: DefinitionSource,
+): void {
+  const full = resolve(basePath, origin);
+  if (!isDir(full)) return;
+  const resolved = resolve(full);
+  if (seen.has(resolved)) return;
+  seen.add(resolved);
+  roots.push({ path: resolved, source, origin });
+}
+
+/**
+ * Walk ancestor directories from projectPath upward, stopping at git root.
+ * At each level, check for ecosystem skill/command directories.
+ */
+function walkAncestors(projectPath: string, roots: SkillRoot[], seen: Set<string>): void {
+  let current = resolve(projectPath);
+  const root = (current.startsWith("/") ? "/" : current.slice(0, 3)); // unix root or Windows drive
+
+  while (current !== root) {
+    for (const eco of PROJECT_ECOSYSTEMS) {
+      const base = resolve(current, eco.dir);
+      for (const origin of ORIGINS) {
+        addRoot(roots, seen, base, origin, eco.source);
+      }
+    }
+    // Stop at git root boundary
+    if (isDir(resolve(current, ".git"))) break;
+    const parent = dirname(current);
+    if (parent === current) break;
+    current = parent;
+  }
+}
+
+/** Check environment variable paths for additional roots */
+function checkEnvVars(roots: SkillRoot[], seen: Set<string>): void {
+  const ppmSkillsDir = process.env.PPM_SKILLS_DIR;
+  if (ppmSkillsDir && isDir(ppmSkillsDir)) {
+    const resolved = resolve(ppmSkillsDir);
+    if (!seen.has(resolved)) {
+      seen.add(resolved);
+      roots.push({ path: resolved, source: "env-var", origin: "skills" });
+    }
+  }
+
+  const claudeConfigDir = process.env.CLAUDE_CONFIG_DIR;
+  if (claudeConfigDir) {
+    for (const origin of ORIGINS) {
+      addRoot(roots, seen, claudeConfigDir, origin, "env-var");
+    }
+  }
+}
+
+/** Add user-global roots (~/.ppm, ~/.claw, ~/.codex, ~/.claude) */
+function addUserGlobalRoots(roots: SkillRoot[], seen: Set<string>): void {
+  const home = homedir();
+  for (const eco of USER_ECOSYSTEMS) {
+    const base = resolve(home, eco.dir);
+    for (const origin of ORIGINS) {
+      addRoot(roots, seen, base, origin, eco.source);
+    }
+  }
+}
+
+/** Add bundled skills root (shipped with PPM package) */
+function addBundledRoot(roots: SkillRoot[], seen: Set<string>): void {
+  if (isDir(BUNDLED_SKILLS_DIR)) {
+    const resolved = resolve(BUNDLED_SKILLS_DIR);
+    if (!seen.has(resolved)) {
+      seen.add(resolved);
+      roots.push({ path: resolved, source: "bundled", origin: "skills" });
+    }
+  }
+}
+
+/**
+ * Discover all skill/command roots for a project.
+ * Returns ordered array (highest priority first).
+ */
+export function discoverSkillRoots(projectPath: string): SkillRoot[] {
+  const roots: SkillRoot[] = [];
+  const seen = new Set<string>();
+
+  walkAncestors(projectPath, roots, seen);
+  checkEnvVars(roots, seen);
+  addUserGlobalRoots(roots, seen);
+  addBundledRoot(roots, seen);
+
+  return roots;
+}

package/src/services/slash-discovery/fuzzy-search.ts

@@ -0,0 +1,76 @@
+import type { SlashItem } from "./types.ts";
+
+/** Iterative Levenshtein distance (single-row DP) */
+export function levenshtein(a: string, b: string): number {
+  if (a === b) return 0;
+  if (a.length === 0) return b.length;
+  if (b.length === 0) return a.length;
+
+  let prev = Array.from({ length: b.length + 1 }, (_, i) => i);
+  let curr = new Array<number>(b.length + 1);
+
+  for (let i = 1; i <= a.length; i++) {
+    curr[0] = i;
+    for (let j = 1; j <= b.length; j++) {
+      const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+      curr[j] = Math.min(
+        curr[j - 1]! + 1,       // insertion
+        prev[j]! + 1,            // deletion
+        prev[j - 1]! + cost,     // substitution
+      );
+    }
+    [prev, curr] = [curr, prev];
+  }
+  return prev[b.length]!;
+}
+
+interface FuzzyScore { rank: number; distance: number }
+
+/**
+ * Score a query against a candidate string.
+ * Returns null if no reasonable match. Rank: 0=prefix, 1=contains, 2=fuzzy.
+ */
+export function scoreFuzzy(query: string, candidate: string): FuzzyScore | null {
+  const lq = query.toLowerCase();
+  const lc = candidate.toLowerCase();
+
+  if (lc.startsWith(lq)) return { rank: 0, distance: 0 };
+  if (lc.includes(lq)) return { rank: 1, distance: lc.indexOf(lq) };
+
+  const maxDist = Math.max(Math.floor(lq.length * 0.4), 2);
+  const dist = levenshtein(lq, lc.slice(0, lq.length + maxDist));
+  if (dist <= maxDist) return { rank: 2, distance: dist };
+
+  return null;
+}
+
+/**
+ * Search slash items by query with fuzzy matching.
+ * Returns ranked results (best match first), truncated to limit.
+ */
+export function searchSlashItems(
+  items: SlashItem[],
+  query: string,
+  limit = 20,
+): SlashItem[] {
+  if (!query) return items;
+  // Cap query length to prevent quadratic blowup in Levenshtein
+  query = query.slice(0, 50);
+
+  const scored: Array<{ item: SlashItem; rank: number; distance: number }> = [];
+
+  for (const item of items) {
+    // Score against name and description, keep best
+    const nameScore = scoreFuzzy(query, item.name);
+    const descScore = scoreFuzzy(query, item.description);
+    const best = [nameScore, descScore]
+      .filter((s): s is FuzzyScore => s !== null)
+      .sort((a, b) => a.rank - b.rank || a.distance - b.distance)[0];
+
+    if (best) scored.push({ item, rank: best.rank, distance: best.distance });
+  }
+
+  scored.sort((a, b) => a.rank - b.rank || a.distance - b.distance || a.item.name.localeCompare(b.item.name));
+
+  return scored.slice(0, limit).map((s) => s.item);
+}

package/src/services/slash-discovery/index.ts

@@ -0,0 +1,42 @@
+import { discoverSkillRoots } from "./discover-skill-roots.ts";
+import { loadItemsFromRoots } from "./skill-loader.ts";
+import { resolveOverrides } from "./resolve-overrides.ts";
+import { getBuiltinSlashItems } from "./builtin-commands.ts";
+import type { SlashItem, SlashItemWithSource, DiscoveryResult } from "./types.ts";
+
+export { searchSlashItems } from "./fuzzy-search.ts";
+export { isPpmHandled, getBuiltinByName } from "./builtin-commands.ts";
+export { executeBuiltin } from "./builtin-handlers.ts";
+export type { SlashItem, SlashItemWithSource, ShadowedItem, DiscoveryResult, SkillRoot, DefinitionSource } from "./types.ts";
+
+/**
+ * Full discovery pipeline: roots → load → resolve overrides → prepend builtins.
+ * Returns active items, shadowed items, and discovered roots.
+ */
+export function listSlashItemsDetailed(projectPath: string): DiscoveryResult {
+  const roots = discoverSkillRoots(projectPath);
+  const rawItems = loadItemsFromRoots(roots);
+  const result = resolveOverrides(rawItems, roots);
+
+  // Prepend builtins (not subject to shadowing — unique type namespace)
+  const builtinItems: SlashItemWithSource[] = getBuiltinSlashItems().map((item) => ({
+    ...item,
+    source: "bundled" as const,
+    rootPath: "",
+    filePath: "",
+  }));
+
+  return {
+    ...result,
+    active: [...builtinItems, ...result.active],
+  };
+}
+
+/**
+ * Backward-compatible: returns flat list of active items (no source metadata).
+ * Same signature as the original `listSlashItems()`.
+ */
+export function listSlashItems(projectPath: string): SlashItem[] {
+  const { active } = listSlashItemsDetailed(projectPath);
+  return active.map(({ source, rootPath, filePath, ...item }) => item);
+}

package/src/services/slash-discovery/resolve-overrides.ts

@@ -0,0 +1,41 @@
+import { compareSourcePriority } from "./definition-source.ts";
+import type { SlashItemWithSource, ShadowedItem, DiscoveryResult, SkillRoot } from "./types.ts";
+
+/**
+ * Resolve override/shadowing conflicts among discovered items.
+ * Groups by `type:name` key. Highest-priority source wins; others become shadowed.
+ */
+export function resolveOverrides(
+  items: SlashItemWithSource[],
+  roots: SkillRoot[],
+): DiscoveryResult {
+  const groups = new Map<string, SlashItemWithSource[]>();
+
+  for (const item of items) {
+    const key = `${item.type}:${item.name}`;
+    const group = groups.get(key);
+    if (group) group.push(item);
+    else groups.set(key, [item]);
+  }
+
+  const active: SlashItemWithSource[] = [];
+  const shadowed: ShadowedItem[] = [];
+
+  for (const group of groups.values()) {
+    // Sort by source priority (lowest numeric = highest priority)
+    group.sort((a, b) => compareSourcePriority(a.source, b.source));
+
+    const winner = group[0]!;
+    active.push(winner);
+
+    // Rest are shadowed
+    for (let i = 1; i < group.length; i++) {
+      shadowed.push({
+        ...group[i]!,
+        shadowedBy: { name: winner.name, source: winner.source },
+      });
+    }
+  }
+
+  return { active, shadowed, roots };
+}

package/src/services/slash-discovery/skill-loader.ts

@@ -0,0 +1,156 @@
+import { resolve, basename, relative, sep } from "node:path";
+import { readdirSync, readFileSync, existsSync, statSync } from "node:fs";
+import yaml from "js-yaml";
+import { sourceToScope } from "./definition-source.ts";
+import type { SkillRoot, SlashItemWithSource } from "./types.ts";
+
+/** Safely coerce a frontmatter value to string */
+function str(val: unknown): string | undefined {
+  if (typeof val === "string") return val;
+  if (typeof val === "number" || typeof val === "boolean") return String(val);
+  return undefined;
+}
+
+/** Parse YAML frontmatter from a Markdown file */
+function parseFrontmatter(content: string): { meta: Record<string, unknown>; body: string } {
+  const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  if (!match || !match[1]) return { meta: {}, body: content };
+  try {
+    // maxAliasCount prevents YAML bomb DoS (supported in js-yaml >=4.1, not in @types)
+    const meta = yaml.load(match[1], { maxAliasCount: 100 } as yaml.LoadOptions) as Record<string, unknown>;
+    return { meta: meta ?? {}, body: content.slice(match[0]!.length).trim() };
+  } catch {
+    return { meta: {}, body: content };
+  }
+}
+
+/** Recursively walk a directory, calling visitor for every file. Tracks visited paths to prevent symlink cycles and enforces root boundary. */
+function walkDir(dir: string, visitor: (filePath: string) => void, visited = new Set<string>(), rootBoundary?: string): void {
+  const resolved = resolve(dir);
+  if (visited.has(resolved)) return;
+  // Prevent symlink escape: resolved path must stay within root boundary
+  if (rootBoundary && resolved !== rootBoundary && !resolved.startsWith(rootBoundary + "/")) return;
+  visited.add(resolved);
+  let entries: string[];
+  try { entries = readdirSync(dir); } catch { return; }
+  for (const entry of entries) {
+    const full = resolve(dir, entry);
+    try {
+      const stat = statSync(full);
+      if (stat.isDirectory()) walkDir(full, visitor, visited, rootBoundary);
+      else if (stat.isFile()) visitor(full);
+    } catch { /* skip */ }
+  }
+}
+
+/** Collect commands from a root with origin "commands" */
+function loadCommands(root: SkillRoot): SlashItemWithSource[] {
+  const items: SlashItemWithSource[] = [];
+  if (!existsSync(root.path)) return items;
+  const scope = sourceToScope(root.source);
+  const boundary = resolve(root.path);
+
+  walkDir(root.path, (filePath) => {
+    if (!filePath.endsWith(".md")) return;
+    try {
+      const content = readFileSync(filePath, "utf-8");
+      const { meta } = parseFrontmatter(content);
+      const rel = relative(root.path, filePath);
+      const name = rel.replace(/\.md$/, "").split(sep).join("/");
+      items.push({
+        type: "command",
+        name: str(meta.name) ?? name,
+        description: str(meta.description) ?? "",
+        argumentHint: str(meta["argument-hint"]),
+        scope,
+        source: root.source,
+        rootPath: root.path,
+        filePath,
+      });
+    } catch { /* skip */ }
+  }, new Set(), boundary);
+  return items;
+}
+
+/**
+ * Collect skills from a root with origin "skills".
+ * User-global roots use strict mode (SKILL.md only).
+ * Project/env roots use relaxed mode (also loose .md files).
+ */
+function loadSkills(root: SkillRoot): SlashItemWithSource[] {
+  const items: SlashItemWithSource[] = [];
+  if (!existsSync(root.path)) return items;
+  const scope = sourceToScope(root.source);
+  const strictMode = scope === "user" || scope === "bundled";
+  const dirsWithSkillMd = new Set<string>();
+
+  const boundary = resolve(root.path);
+
+  // Pass 1: SKILL.md directory-based skills
+  walkDir(root.path, (filePath) => {
+    if (basename(filePath) !== "SKILL.md") return;
+    try {
+      const content = readFileSync(filePath, "utf-8");
+      const { meta } = parseFrontmatter(content);
+      const skillDir = resolve(filePath, "..");
+      dirsWithSkillMd.add(skillDir);
+      const rel = relative(root.path, skillDir);
+      const pathName = rel.split(sep).join("/");
+      const name = str(meta.name) ?? pathName;
+      if (!name) return;
+      items.push({
+        type: "skill",
+        name,
+        description: str(meta.description) ?? "",
+        argumentHint: str(meta["argument-hint"]),
+        scope,
+        source: root.source,
+        rootPath: root.path,
+        filePath,
+      });
+    } catch { /* skip */ }
+  }, new Set(), boundary);
+
+  // Pass 2 (relaxed mode only): loose .md files not inside a SKILL.md directory
+  if (!strictMode) {
+    walkDir(root.path, (filePath) => {
+      if (!filePath.endsWith(".md") || basename(filePath) === "SKILL.md") return;
+      const dir = resolve(filePath, "..");
+      let ancestor = dir;
+      while ((ancestor + "/").startsWith(boundary + "/") && ancestor !== boundary) {
+        if (dirsWithSkillMd.has(ancestor)) return;
+        ancestor = resolve(ancestor, "..");
+      }
+      try {
+        const content = readFileSync(filePath, "utf-8");
+        const { meta } = parseFrontmatter(content);
+        const rel = relative(root.path, filePath);
+        const pathName = rel.replace(/\.md$/, "").split(sep).join("/");
+        const name = str(meta.name) ?? pathName;
+        if (!name) return;
+        items.push({
+          type: "skill",
+          name,
+          description: str(meta.description) ?? "",
+          argumentHint: str(meta["argument-hint"]),
+          scope,
+          source: root.source,
+          rootPath: root.path,
+          filePath,
+        });
+      } catch { /* skip */ }
+    }, new Set(), boundary);
+  }
+
+  return items;
+}
+
+/** Load all slash items from a single root */
+export function loadItemsFromRoot(root: SkillRoot): SlashItemWithSource[] {
+  return root.origin === "commands" ? loadCommands(root) : loadSkills(root);
+}
+
+/** Load items from all roots */
+export function loadItemsFromRoots(roots: SkillRoot[]): SlashItemWithSource[] {
+  return roots.flatMap(loadItemsFromRoot);
+}

package/src/services/slash-discovery/types.ts

@@ -0,0 +1,51 @@
+/** Priority ranking — lower numeric value = higher priority */
+export type DefinitionSource =
+  | "project-ppm"      // 0 — .ppm/ in project tree
+  | "project-claw"     // 1 — .claw/ in project tree
+  | "project-codex"    // 2 — .codex/ in project tree
+  | "project-claude"   // 3 — .claude/ in project tree
+  | "env-var"          // 4 — $PPM_SKILLS_DIR or $CLAUDE_CONFIG_DIR
+  | "user-ppm"         // 5 — ~/.ppm/
+  | "user-claw"        // 6 — ~/.claw/
+  | "user-codex"       // 7 — ~/.codex/
+  | "user-claude"      // 8 — ~/.claude/
+  | "bundled";         // 9 — shipped with PPM package
+
+export type SlashItemType = "skill" | "command" | "builtin";
+export type SlashItemScope = "project" | "user" | "bundled";
+export type ItemOrigin = "skills" | "commands";
+
+export interface SlashItem {
+  type: SlashItemType;
+  /** Slash name, e.g. "review", "devops/deploy", "ck:research" */
+  name: string;
+  description: string;
+  argumentHint?: string;
+  /** Where the item comes from */
+  scope: SlashItemScope;
+  category?: string;
+  aliases?: string[];
+}
+
+export interface SkillRoot {
+  path: string;              // Resolved absolute path
+  source: DefinitionSource;
+  origin: ItemOrigin;
+}
+
+/** Extends SlashItem with source metadata */
+export interface SlashItemWithSource extends SlashItem {
+  source: DefinitionSource;
+  rootPath: string;
+  filePath: string;
+}
+
+export interface ShadowedItem extends SlashItemWithSource {
+  shadowedBy: { name: string; source: DefinitionSource };
+}
+
+export interface DiscoveryResult {
+  active: SlashItemWithSource[];
+  shadowed: ShadowedItem[];
+  roots: SkillRoot[];
+}