@hienlh/ppm 0.9.81 → 0.9.83

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[];
+}

package/src/services/slash-items.service.ts

@@ -1,184 +1,6 @@
-import { resolve, basename, relative, sep } from "node:path";
-import { homedir } from "node:os";
-import { readdirSync, readFileSync, existsSync, statSync } from "node:fs";
-import yaml from "js-yaml";
-
-export interface SlashItem {
-  type: "skill" | "command";
-  /** Slash name, e.g. "review", "devops/deploy", "ck:research" */
-  name: string;
-  description: string;
-  argumentHint?: string;
-  /** Where the item comes from */
-  scope: "project" | "user";
-}
-
-/** Safely coerce a frontmatter value to string, returns undefined if not a scalar. */
-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.
+ * Thin re-export wrapper — actual discovery logic lives in slash-discovery/.
+ * Kept for backward compatibility with existing imports.
  */
-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 {
-    const meta = yaml.load(match[1]) as Record<string, unknown>;
-    const body = content.slice(match[0]!.length).trim();
-    return { meta: meta ?? {}, body };
-  } catch {
-    return { meta: {}, body: content };
-  }
-}
-
-/**
- * Recursively walk a directory tree, calling `visitor` for every file.
- * Ignores unreadable dirs/files silently.
- */
-function walkDir(dir: string, visitor: (filePath: string) => void): void {
-  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);
-      } else if (stat.isFile()) {
-        visitor(full);
-      }
-    } catch { /* skip */ }
-  }
-}
-
-/**
- * Collect commands from a commands directory (recursive).
- * `commands/devops/deploy.md` → name `devops/deploy`
- */
-function collectCommands(commandsDir: string, scope: "project" | "user"): SlashItem[] {
-  const items: SlashItem[] = [];
-  if (!existsSync(commandsDir)) return items;
-  walkDir(commandsDir, (filePath) => {
-    if (!filePath.endsWith(".md")) return;
-    try {
-      const content = readFileSync(filePath, "utf-8");
-      const { meta } = parseFrontmatter(content);
-      const rel = relative(commandsDir, 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,
-      });
-    } catch { /* skip */ }
-  });
-  return items;
-}
-
-/**
- * Collect skills from a skills directory.
- *
- * @param skillsDir    Root skills directory to scan
- * @param scope        "project" or "user"
- * @param strictMode   When true, ONLY pick up SKILL.md files (used for user-global
- *                     which can have many supporting .md files per skill).
- *                     When false, also pick up loose .md files outside SKILL.md dirs
- *                     (used for project-local where flat layout is common).
- */
-function collectSkills(skillsDir: string, scope: "project" | "user", strictMode: boolean): SlashItem[] {
-  const items: SlashItem[] = [];
-  if (!existsSync(skillsDir)) return items;
-
-  const dirsWithSkillMd = new Set<string>();
-
-  // Pass 1: SKILL.md files (directory-based skills)
-  walkDir(skillsDir, (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(skillsDir, 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) ?? "",
-        scope,
-      });
-    } catch { /* skip */ }
-  });
-
-  // Pass 2 (only in relaxed mode): loose .md files not inside a SKILL.md directory
-  if (!strictMode) {
-    walkDir(skillsDir, (filePath) => {
-      if (!filePath.endsWith(".md")) return;
-      if (basename(filePath) === "SKILL.md") return;
-      const dir = resolve(filePath, "..");
-      // Skip supporting files inside a skill dir (or any ancestor)
-      let ancestor = dir;
-      while (ancestor.startsWith(skillsDir) && ancestor !== skillsDir) {
-        if (dirsWithSkillMd.has(ancestor)) return;
-        ancestor = resolve(ancestor, "..");
-      }
-      try {
-        const content = readFileSync(filePath, "utf-8");
-        const { meta } = parseFrontmatter(content);
-        const rel = relative(skillsDir, 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) ?? "",
-          scope,
-        });
-      } catch { /* skip */ }
-    });
-  }
-
-  return items;
-}
-
-/**
- * Scan for available slash commands and skills.
- *
- * Sources (merged, project overrides user if same name):
- *   1. User-global:   ~/.claude/commands/  and  ~/.claude/skills/   (strict: SKILL.md only)
- *   2. Project-local:  <projectPath>/.claude/commands/  and  .claude/skills/  (relaxed: also loose .md)
- */
-export function listSlashItems(projectPath: string): SlashItem[] {
-  const home = homedir();
-  const globalClaude = resolve(home, ".claude");
-
-  // Collect from both scopes (user-global uses strict mode)
-  const userCommands = collectCommands(resolve(globalClaude, "commands"), "user");
-  const userSkills = collectSkills(resolve(globalClaude, "skills"), "user", true);
-  const projectCommands = collectCommands(resolve(projectPath, ".claude", "commands"), "project");
-  const projectSkills = collectSkills(resolve(projectPath, ".claude", "skills"), "project", false);
-
-  // Merge: project items override user items with the same name
-  const map = new Map<string, SlashItem>();
-  for (const item of [...userCommands, ...userSkills]) {
-    map.set(`${item.type}:${item.name}`, item);
-  }
-  for (const item of [...projectCommands, ...projectSkills]) {
-    map.set(`${item.type}:${item.name}`, item);
-  }
-
-  return Array.from(map.values());
-}
+export { listSlashItems, searchSlashItems } from "./slash-discovery/index.ts";
+export type { SlashItem } from "./slash-discovery/types.ts";

package/src/services/supervisor-state.ts

@@ -3,17 +3,16 @@
  * Extracted from supervisor.ts to keep the orchestrator lean.
  */
 import { resolve } from "node:path";
-import { homedir } from "node:os";
 import {
   readFileSync, writeFileSync, existsSync, unlinkSync, renameSync, openSync, closeSync,
 } from "node:fs";
 import { constants } from "node:fs";
+import { getPpmDir } from "./ppm-dir.ts";
 
-const PPM_DIR = resolve(process.env.PPM_HOME || resolve(homedir(), ".ppm"));
-export const CMD_FILE = resolve(PPM_DIR, ".supervisor-cmd");
-export const STATUS_FILE = resolve(PPM_DIR, "status.json");
-export const PID_FILE = resolve(PPM_DIR, "ppm.pid");
-export const LOCK_FILE = resolve(PPM_DIR, ".start-lock");
+export const CMD_FILE = () => resolve(getPpmDir(), ".supervisor-cmd");
+export const STATUS_FILE = () => resolve(getPpmDir(), "status.json");
+export const PID_FILE = () => resolve(getPpmDir(), "ppm.pid");
+export const LOCK_FILE = () => resolve(getPpmDir(), ".start-lock");
 
 // ─── State ─────────────────────────────────────────────────────────────
 export type SupervisorState = "running" | "paused" | "stopped" | "upgrading";
@@ -47,7 +46,7 @@ function atomicWriteJson(filePath: string, data: unknown) {
 
 export function readStatus(): Record<string, unknown> {
   try {
-    if (existsSync(STATUS_FILE)) return JSON.parse(readFileSync(STATUS_FILE, "utf-8"));
+    if (existsSync(STATUS_FILE())) return JSON.parse(readFileSync(STATUS_FILE(), "utf-8"));
   } catch {}
   return {};
 }
@@ -55,7 +54,7 @@ export function readStatus(): Record<string, unknown> {
 export function updateStatus(patch: Record<string, unknown>) {
   try {
     const data = { ...readStatus(), ...patch };
-    atomicWriteJson(STATUS_FILE, data);
+    atomicWriteJson(STATUS_FILE(), data);
   } catch {}
 }
 
@@ -64,9 +63,9 @@ export type CmdAction = "soft_stop" | "resume";
 
 /** Atomically claim + read command file (rename to .claimed, read, delete) */
 export function readAndDeleteCmd(): { action: CmdAction } | null {
-  const claimed = CMD_FILE + ".claimed";
+  const claimed = CMD_FILE() + ".claimed";
   try {
-    renameSync(CMD_FILE, claimed); // atomic claim — second caller gets ENOENT
+    renameSync(CMD_FILE(), claimed); // atomic claim — second caller gets ENOENT
     const cmd = JSON.parse(readFileSync(claimed, "utf-8"));
     unlinkSync(claimed);
     return cmd;
@@ -78,31 +77,31 @@ export function readAndDeleteCmd(): { action: CmdAction } | null {
 }
 
 export function writeCmd(action: CmdAction) {
-  writeFileSync(CMD_FILE, JSON.stringify({ action }));
+  writeFileSync(CMD_FILE(), JSON.stringify({ action }));
 }
 
 // ─── Lockfile ──────────────────────────────────────────────────────────
 export function acquireLock(): boolean {
   try {
     // Try exclusive create — fails if file already exists (atomic)
-    const fd = openSync(LOCK_FILE, "wx");
+    const fd = openSync(LOCK_FILE(), "wx");
     writeFileSync(fd, String(process.pid));
     closeSync(fd);
     return true;
   } catch {
     // File exists — check if holding process is alive
     try {
-      const pid = parseInt(readFileSync(LOCK_FILE, "utf-8").trim(), 10);
+      const pid = parseInt(readFileSync(LOCK_FILE(), "utf-8").trim(), 10);
       if (!isNaN(pid)) {
         try { process.kill(pid, 0); return false; } catch {} // stale lock
       }
       // Stale lock — overwrite
-      writeFileSync(LOCK_FILE, String(process.pid));
+      writeFileSync(LOCK_FILE(), String(process.pid));
       return true;
     } catch { return false; }
   }
 }
 
 export function releaseLock() {
-  try { unlinkSync(LOCK_FILE); } catch {}
+  try { unlinkSync(LOCK_FILE()); } catch {}
 }

package/src/services/supervisor-stopped-page.ts

@@ -4,13 +4,11 @@
  */
 import { appendFileSync } from "node:fs";
 import { resolve } from "node:path";
-import { homedir } from "node:os";
-
-const LOG_FILE = resolve(process.env.PPM_HOME || resolve(homedir(), ".ppm"), "ppm.log");
+import { getPpmDir } from "./ppm-dir.ts";
 
 function log(level: string, msg: string) {
   const ts = new Date().toISOString();
-  try { appendFileSync(LOG_FILE, `[${ts}] [${level}] [stopped-page] ${msg}\n`); } catch {}
+  try { appendFileSync(resolve(getPpmDir(), "ppm.log"), `[${ts}] [${level}] [stopped-page] ${msg}\n`); } catch {}
 }
 
 const STOPPED_HTML = `<!DOCTYPE html>