@phren/cli 0.0.28 → 0.0.33

package/mcp/dist/{link-doctor.js → link/doctor.js}

@@ -1,23 +1,24 @@
 import * as fs from "fs";
 import * as path from "path";
 import { execFileSync } from "child_process";
-import { debugLog, EXEC_TIMEOUT_QUICK_MS, getProjectDirs, isRecord, homeDir, homePath, hookConfigPath, runtimeHealthFile, } from "./shared.js";
-import { commandVersion, versionAtLeast, nearestWritableTarget } from "./init-shared.js";
-import { validateGovernanceJson } from "./shared-governance.js";
-import { errorMessage } from "./utils.js";
-import { buildIndex, queryRows } from "./shared-index.js";
-import { validateTaskFormat, validateFindingsFormat } from "./shared-content.js";
-import { detectInstalledTools } from "./hooks.js";
-import { validateSkillFrontmatter, validateSkillsDir } from "./link-skills.js";
-import { verifyFileChecksums, updateFileChecksums } from "./link-checksums.js";
-import { buildSkillManifest } from "./skill-registry.js";
-import { inspectTaskHygiene } from "./task-hygiene.js";
-import { resolveTaskFilePath, TASK_FILE_ALIASES } from "./data-tasks.js";
-import { repairPreexistingInstall } from "./init-setup.js";
+import { debugLog, EXEC_TIMEOUT_QUICK_MS, getProjectDirs, isRecord, homeDir, homePath, hookConfigPath, runtimeHealthFile, } from "../shared.js";
+import { commandVersion, versionAtLeast, nearestWritableTarget } from "../init/shared.js";
+import { validateGovernanceJson } from "../shared/governance.js";
+import { errorMessage } from "../utils.js";
+import { buildIndex, queryRows } from "../shared/index.js";
+import { validateTaskFormat, validateFindingsFormat } from "../shared/content.js";
+import { detectInstalledTools } from "../hooks.js";
+import { validateSkillFrontmatter, validateSkillsDir } from "./skills.js";
+import { verifyFileChecksums, updateFileChecksums } from "./checksums.js";
+import { buildSkillManifest } from "../skill/registry.js";
+import { inspectTaskHygiene } from "../task/hygiene.js";
+import { resolveTaskFilePath, TASK_FILE_ALIASES } from "../data/tasks.js";
+import { repairPreexistingInstall } from "../init/setup.js";
 import { getMachineName, lookupProfile, findProfileFile, getProfileProjects, findProjectDir, } from "./link.js";
-import { claudeProjectKey } from "./link-context.js";
-import { getProjectOwnershipMode, readProjectConfig } from "./project-config.js";
-import { readInstallPreferences } from "./init-preferences.js";
+import { claudeProjectKey } from "./context.js";
+import { getProjectOwnershipMode, readProjectConfig } from "../project-config.js";
+import { readInstallPreferences } from "../init/preferences.js";
+import { logger } from "../logger.js";
 // ── Doctor ──────────────────────────────────────────────────────────────────
 function isWrapperActive(tool) {
     const wrapperPath = homePath(".local", "bin", tool);
@@ -176,15 +177,13 @@ export async function runDoctor(phrenPath, fix = false, checkData = false) {
         fsMs = Date.now() - t0;
     }
     catch (err) {
-        if ((process.env.PHREN_DEBUG))
-            process.stderr.write(`[phren] doctor fsBenchmark: ${errorMessage(err)}\n`);
+        logger.debug("doctor", `doctor fsBenchmark: ${errorMessage(err)}`);
         fsMs = -1;
         try {
             fs.unlinkSync(fsBenchFile);
         }
         catch (e2) {
-            if ((process.env.PHREN_DEBUG))
-                process.stderr.write(`[phren] doctor fsBenchmarkCleanup: ${e2 instanceof Error ? e2.message : String(e2)}\n`);
+            logger.debug("doctor", `doctor fsBenchmarkCleanup: ${e2 instanceof Error ? e2.message : String(e2)}`);
         }
     }
     const fsSlow = fsMs > 500 || fsMs < 0;
@@ -306,8 +305,7 @@ export async function runDoctor(phrenPath, fix = false, checkData = false) {
             runtime = JSON.parse(fs.readFileSync(runtimeHealthPath, "utf8"));
         }
         catch (err) {
-            if ((process.env.PHREN_DEBUG))
-                process.stderr.write(`[phren] doctor runtimeHealth: ${errorMessage(err)}\n`);
+            logger.debug("doctor", `doctor runtimeHealth: ${errorMessage(err)}`);
             runtime = null;
         }
     }

package/mcp/dist/{link.js → link/link.js}

@@ -3,27 +3,28 @@ import * as path from "path";
 import * as readline from "readline";
 import * as yaml from "js-yaml";
 import { execFileSync } from "child_process";
-import { ROOT } from "./package-metadata.js";
-import { configureMcpTargets, ensureGovernanceFiles, getHooksEnabledPreference, getMcpEnabledPreference, isVersionNewer, patchJsonFile, setMcpEnabledPreference, } from "./init.js";
-import { configureAllHooks, detectInstalledTools } from "./hooks.js";
-import { getMachineName, persistMachineName } from "./machine-identity.js";
-import { debugLog, EXEC_TIMEOUT_MS, EXEC_TIMEOUT_QUICK_MS, isRecord, homePath, hookConfigPath, installPreferencesFile, atomicWriteText, } from "./shared.js";
-import { errorMessage } from "./utils.js";
-import { log } from "./init-shared.js";
-import { listMachines as listMachinesShared, listProfiles as listProfilesShared, setMachineProfile, } from "./profile-store.js";
-import { writeSkillMd, isManagedSymlink } from "./link-skills.js";
-import { syncScopeSkillsToDir } from "./skill-files.js";
-import { renderSkillInstructionsSection } from "./skill-registry.js";
-import { findProjectDir } from "./project-locator.js";
-import { getProjectOwnershipMode, readProjectConfig, } from "./project-config.js";
-import { writeContextDefault, writeContextDebugging, writeContextPlanning, writeContextClean, readBackNativeMemory, rebuildMemory, } from "./link-context.js";
+import { ROOT } from "../package-metadata.js";
+import { configureMcpTargets, ensureGovernanceFiles, getHooksEnabledPreference, getMcpEnabledPreference, isVersionNewer, patchJsonFile, setMcpEnabledPreference, } from "../init/init.js";
+import { configureAllHooks, detectInstalledTools } from "../hooks.js";
+import { getMachineName, persistMachineName } from "../machine-identity.js";
+import { debugLog, EXEC_TIMEOUT_MS, EXEC_TIMEOUT_QUICK_MS, isRecord, homePath, hookConfigPath, installPreferencesFile, atomicWriteText, } from "../shared.js";
+import { errorMessage } from "../utils.js";
+import { log } from "../init/shared.js";
+import { listMachines as listMachinesShared, listProfiles as listProfilesShared, setMachineProfile, } from "../profile-store.js";
+import { writeSkillMd, isManagedSymlink } from "./skills.js";
+import { syncScopeSkillsToDir } from "../skill/files.js";
+import { renderSkillInstructionsSection } from "../skill/registry.js";
+import { findProjectDir } from "../project-locator.js";
+import { getProjectOwnershipMode, readProjectConfig, } from "../project-config.js";
+import { writeContextDefault, writeContextDebugging, writeContextPlanning, writeContextClean, readBackNativeMemory, rebuildMemory, } from "./context.js";
+import { logger } from "../logger.js";
 // Re-export sub-modules so existing imports from "./link.js" continue to work
-export { runDoctor } from "./link-doctor.js";
-export { updateFileChecksums, verifyFileChecksums } from "./link-checksums.js";
-export { findProjectDir } from "./project-locator.js";
-export { parseSkillFrontmatter, validateSkillFrontmatter, validateSkillsDir, readSkillManifestHooks, } from "./link-skills.js";
+export { runDoctor } from "./doctor.js";
+export { updateFileChecksums, verifyFileChecksums } from "./checksums.js";
+export { findProjectDir } from "../project-locator.js";
+export { parseSkillFrontmatter, validateSkillFrontmatter, validateSkillsDir, readSkillManifestHooks, } from "./skills.js";
 // ── Helpers (exported for link-doctor) ──────────────────────────────────────
-export { getMachineName } from "./machine-identity.js";
+export { getMachineName } from "../machine-identity.js";
 export function lookupProfile(phrenPath, machine) {
     const listed = listMachinesShared(phrenPath);
     if (!listed.ok)
@@ -115,8 +116,7 @@ function setupSparseCheckout(phrenPath, projects) {
         execFileSync("git", ["rev-parse", "--git-dir"], { cwd: phrenPath, stdio: "ignore", timeout: EXEC_TIMEOUT_QUICK_MS });
     }
     catch (err) {
-        if ((process.env.PHREN_DEBUG))
-            process.stderr.write(`[phren] setupSparseCheckout notAGitRepo: ${errorMessage(err)}\n`);
+        logger.debug("link", `setupSparseCheckout notAGitRepo: ${errorMessage(err)}`);
         return;
     }
     const alwaysInclude = ["profiles", "machines.yaml", "global", "scripts", "link.sh", "README.md", ".gitignore"];
@@ -268,8 +268,7 @@ function linkGlobal(phrenPath, tools) {
                 symlinkFile(globalClaude, path.join(copilotInstrDir, "copilot-instructions.md"), phrenPath);
             }
             catch (err) {
-                if ((process.env.PHREN_DEBUG))
-                    process.stderr.write(`[phren] linkGlobal copilotInstructions: ${errorMessage(err)}\n`);
+                logger.debug("link", `linkGlobal copilotInstructions: ${errorMessage(err)}`);
             }
         }
     }
@@ -314,8 +313,7 @@ function linkProject(phrenPath, project, tools) {
                         symlinkFile(src, path.join(copilotDir, "copilot-instructions.md"), phrenPath);
                     }
                     catch (err) {
-                        if ((process.env.PHREN_DEBUG))
-                            process.stderr.write(`[phren] linkProject copilotInstructions: ${errorMessage(err)}\n`);
+                        logger.debug("link", `linkProject copilotInstructions: ${errorMessage(err)}`);
                     }
                 }
             }
@@ -338,8 +336,7 @@ function linkProject(phrenPath, project, tools) {
             addTokenAnnotation(claudeFile);
         }
         catch (err) {
-            if ((process.env.PHREN_DEBUG))
-                process.stderr.write(`[phren] linkProject tokenAnnotation: ${errorMessage(err)}\n`);
+            logger.debug("link", `linkProject tokenAnnotation: ${errorMessage(err)}`);
         }
     }
     // Project-level skills
@@ -355,8 +352,7 @@ function linkProject(phrenPath, project, tools) {
                 excludeEntries.push("AGENTS.md");
         }
         catch (err) {
-            if ((process.env.PHREN_DEBUG))
-                process.stderr.write(`[phren] linkProject agentsMd: ${errorMessage(err)}\n`);
+            logger.debug("link", `linkProject agentsMd: ${errorMessage(err)}`);
         }
     }
     // Auto-exclude phren-managed files from git status
@@ -507,8 +503,7 @@ export async function runLink(phrenPath, opts = {}) {
         log(`  phren.SKILL.md written (agentskills-compatible tools)`);
     }
     catch (err) {
-        if ((process.env.PHREN_DEBUG))
-            process.stderr.write(`[phren] link writeSkillMd: ${errorMessage(err)}\n`);
+        logger.debug("link", `link writeSkillMd: ${errorMessage(err)}`);
     }
     log("");
     // Step 7: Context file

package/mcp/dist/{link-skills.js → link/skills.js}

@@ -1,12 +1,13 @@
 import * as fs from "fs";
 import * as path from "path";
 import * as yaml from "js-yaml";
-import { debugLog } from "./shared.js";
-import { errorMessage } from "./utils.js";
-import { buildSharedLifecycleCommands } from "./hooks.js";
-import { VERSION } from "./package-metadata.js";
-import { getToolCount, renderToolCatalogMarkdown } from "./tool-registry.js";
-import { isSkillEnabled } from "./skill-state.js";
+import { debugLog } from "../shared.js";
+import { errorMessage } from "../utils.js";
+import { buildSharedLifecycleCommands } from "../hooks.js";
+import { VERSION } from "../package-metadata.js";
+import { getToolCount, renderToolCatalogMarkdown } from "../tool-registry.js";
+import { isSkillEnabled } from "../skill/state.js";
+import { logger } from "../logger.js";
 const REQUIRED_SKILL_FIELDS = ["name", "description"];
 export function parseSkillFrontmatter(rawContent) {
     // Normalize UTF-8 BOM and Windows-style CRLF line endings before matching frontmatter
@@ -190,8 +191,7 @@ function cleanupManagedSkillLinks(destDir, expectedNames, managedRoot) {
             fs.unlinkSync(destPath);
         }
         catch (err) {
-            if ((process.env.PHREN_DEBUG))
-                process.stderr.write(`[phren] cleanupManagedSkillLinks: ${errorMessage(err)}\n`);
+            logger.debug("link-skills", `cleanupManagedSkillLinks: ${errorMessage(err)}`);
         }
     }
 }
@@ -217,7 +217,7 @@ export function linkSkillsDir(srcDir, destDir, managedRoot, symlinkFile, opts) {
                     message: `Skipping skill '${skillName}' — user skill already exists at ${destPath}. To use phren's version, rename or remove your skill first.`,
                 };
                 collisions.push(collision);
-                process.stderr.write(`[phren] ${collision.message}\n`);
+                logger.warn("link-skills", collision.message);
                 continue;
             }
             expectedNames.add(entry);
@@ -234,7 +234,7 @@ export function linkSkillsDir(srcDir, destDir, managedRoot, symlinkFile, opts) {
                         message: `Skipping skill '${skillName}' — user skill already exists at ${destPath}. To use phren's version, rename or remove your skill first.`,
                     };
                     collisions.push(collision);
-                    process.stderr.write(`[phren] ${collision.message}\n`);
+                    logger.warn("link-skills", collision.message);
                     continue;
                 }
                 expectedNames.add(entry);

package/mcp/dist/logger.js

@@ -1,11 +1,13 @@
 import * as fs from "fs";
 import { runtimeFile, findPhrenPath } from "./shared.js";
+let _cachedPhrenPath;
 export function log(level, tool, message, extra) {
     try {
-        const phrenPath = findPhrenPath();
-        if (!phrenPath)
+        if (_cachedPhrenPath === undefined)
+            _cachedPhrenPath = findPhrenPath();
+        if (!_cachedPhrenPath)
             return;
-        const logPath = runtimeFile(phrenPath, "debug.log");
+        const logPath = runtimeFile(_cachedPhrenPath, "debug.log");
         const line = JSON.stringify({ ts: new Date().toISOString(), level, tool, message, ...extra });
         fs.appendFileSync(logPath, line + "\n");
     }
@@ -13,3 +15,9 @@ export function log(level, tool, message, extra) {
         // Logging must never throw
     }
 }
+export const logger = {
+    debug: (tool, message, extra) => log("debug", tool, message, extra),
+    info: (tool, message, extra) => log("info", tool, message, extra),
+    warn: (tool, message, extra) => log("warn", tool, message, extra),
+    error: (tool, message, extra) => log("error", tool, message, extra),
+};

package/mcp/dist/package-metadata.js

@@ -3,7 +3,7 @@ import * as path from "path";
 import { fileURLToPath } from "url";
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 export const ROOT = path.join(__dirname, "..", "..");
-export const PACKAGE_JSON_PATH = path.join(ROOT, "package.json");
+const PACKAGE_JSON_PATH = path.join(ROOT, "package.json");
 function readPackageJson() {
     return JSON.parse(fs.readFileSync(PACKAGE_JSON_PATH, "utf8"));
 }

package/mcp/dist/phren-art.js

@@ -1,24 +1,9 @@
 /**
- * Phren character ASCII/Unicode art, animation engine, and spinner for CLI presence.
+ * Phren character ASCII/Unicode art for CLI presence.
  *
  * Based on the pixel art: purple 8-bit brain with diamond eyes,
  * smile, little legs, and cyan sparkle.
- *
- * Animation system provides lifelike movement through composable effects:
- * bob, blink, sparkle, and lean — all driven by setTimeout with randomized
- * intervals for organic timing.
  */
-const ESC = "\x1b[";
-const RESET = `${ESC}0m`;
-const PURPLE = `${ESC}35m`; // magenta — body
-const BRIGHT_PURPLE = `${ESC}95m`; // bright magenta — highlights
-const CYAN = `${ESC}96m`; // bright cyan — sparkle
-const DIM = `${ESC}2m`;
-const DARK_PURPLE = `${ESC}38;5;57m`; // deep purple — shadow/outline
-const LIGHT_PURPLE = `${ESC}38;5;141m`; // lavender — brain highlights
-const MID_PURPLE = `${ESC}38;5;98m`; // mid tone
-const NAVY = `${ESC}38;5;18m`; // darkest outline
-// ── Art constants (24px wide, truecolor half-blocks) ─────────────────────────
 /**
  * Phren truecolor art (24px wide, generated from phren-transparent.png).
  * Uses half-block ▀ with RGB foreground+background for pixel-faithful rendering.
@@ -38,35 +23,19 @@ export const PHREN_ART = [
     "                        ",
     "                        ",
 ];
-/** The art width in visible columns */
-const ART_WIDTH = 24;
 // ── Sparkle row: the cyan pixels at row 2 ────────────────────────────────────
-// Sparkle uses ▄ half-blocks with cyan truecolor. For animation we cycle through
-// decorative unicode characters at different brightness levels.
 const SPARKLE_ROW = 2;
-const SPARKLE_CHARS = ["\u2726", "\u2727", "\u2736", " "]; // ✦ ✧ ✶ (dim/blank)
-// ── Eye detection: dark navy pixels in row 6 (fg R<30, G<45, B<120) ──────────
-// Row 6 has two eye pixels at segments 1 and 5 (visual positions 7 and 11).
-// When blinking, we replace their dark fg color with the surrounding body purple.
+const SPARKLE_CHARS = ["\u2726", "\u2727", "\u2736", " "];
+// ── Eye detection: dark navy pixels in row 6 ─────────────────────────────────
 const EYE_ROW = 6;
-// Dark-pixel fg threshold
 const EYE_R_MAX = 30;
 const EYE_G_MAX = 45;
 const EYE_B_MAX = 120;
-// Body-purple color to use when "closing" eyes (average of surrounding pixels)
 const BLINK_COLOR = "146;130;250";
-/**
- * Flip a single art line horizontally. Reverses the order of colored pixel
- * segments and swaps leading/trailing whitespace so the character faces right.
- * Half-block characters (▀ ▄) are horizontally symmetric so no char swap needed.
- */
 function flipLine(line) {
     const stripped = line.replace(/\x1b\[[^m]*m/g, "");
     const leadSpaces = stripped.match(/^( *)/)[1].length;
     const trailSpaces = stripped.match(/( *)$/)[1].length;
-    // Parse pixel segments: each is one or two ANSI color codes followed by a block char.
-    // We strip any leading reset (\x1b[0m) from captured codes — it's an artifact from
-    // the original per-pixel reset pattern and will be re-added during reassembly.
     const pixels = [];
     const pixelRegex = /((?:\x1b\[[^m]*m)+)([\u2580\u2584])/g;
     let match;
@@ -76,7 +45,7 @@ function flipLine(line) {
             pixels.push({ codes, char: match[2] });
     }
     if (pixels.length === 0)
-        return line; // blank or space-only line
+        return line;
     const reversed = [...pixels].reverse();
     const newLead = " ".repeat(trailSpaces);
     const newTrail = " ".repeat(leadSpaces);
@@ -87,26 +56,14 @@ function flipLine(line) {
     result += newTrail;
     return result;
 }
-/**
- * Generate horizontally flipped art (facing right).
- */
 function generateFlippedArt(art) {
     return art.map(flipLine);
 }
-/** Pre-computed right-facing art */
 export const PHREN_ART_RIGHT = generateFlippedArt(PHREN_ART);
-/** Random integer in [min, max] inclusive */
 function randInt(min, max) {
     return Math.floor(Math.random() * (max - min + 1)) + min;
 }
-/**
- * Replace eye pixels on a single line with the blink color.
- * Eye pixels are identified by their dark navy fg color (R<30, G<45, B<120).
- * We replace the fg color code while preserving the bg code and character.
- */
 function applyBlinkToLine(line) {
-    // Match ANSI color sequences: each pixel is \e[38;2;R;G;Bm (optionally with \e[48;2;...m) then a block char
-    // We scan for fg codes that match the eye threshold and replace them with the blink color
     return line.replace(/\x1b\[38;2;(\d+);(\d+);(\d+)m/g, (full, rStr, gStr, bStr) => {
         const r = Number(rStr);
         const g = Number(gStr);
@@ -117,44 +74,24 @@ function applyBlinkToLine(line) {
         return full;
     });
 }
-/**
- * Replace the sparkle pixels on the sparkle row with the current sparkle character.
- * The sparkle row has two cyan ▄ half-blocks. During sparkle animation we replace
- * them with decorative Unicode characters from SPARKLE_CHARS.
- */
 function applySparkleToLine(line, frame, active) {
     if (!active)
         return line;
     const sparkleChar = SPARKLE_CHARS[frame % SPARKLE_CHARS.length];
     if (sparkleChar === " ") {
-        // Dim: replace the cyan-colored segments with spaces (they disappear)
         return line.replace(/\x1b\[38;2;\d+;2\d\d;2\d\dm[\u2580\u2584]\x1b\[0m/g, " ");
     }
-    // Replace the half-block characters with the sparkle unicode char, keeping the cyan color
     return line.replace(/(\x1b\[38;2;\d+;2\d\d;2\d\dm)[\u2580\u2584](\x1b\[0m)/g, `$1${sparkleChar}$2`);
 }
-/**
- * Apply lean (horizontal shift) to a line.
- * Positive offset = shift right (prepend spaces, trim from end).
- * Negative offset = shift left (trim from start, append spaces).
- */
 function applyLean(line, offset) {
     if (offset === 0)
         return line;
     if (offset > 0) {
-        // Shift right: prepend spaces
         return " ".repeat(offset) + line;
     }
-    // Shift left: remove leading spaces (up to |offset|)
     const trimCount = Math.min(-offset, line.match(/^( *)/)[1].length);
     return line.slice(trimCount);
 }
-/**
- * Create an animated phren character controller.
- *
- * @param options.facing - 'left' (default, original) or 'right' (flipped)
- * @param options.size - art width; unused but reserved for future scaling (default 24)
- */
 export function createPhrenAnimator(options) {
     const facing = options?.facing ?? "left";
     const baseArt = facing === "right" ? PHREN_ART_RIGHT : PHREN_ART;
@@ -170,22 +107,18 @@ export function createPhrenAnimator(options) {
         const t = setTimeout(fn, ms);
         timers.push(t);
     }
-    // ── Bob animation: toggles bobUp every ~500ms ──────────────────────────
     function scheduleBob() {
         scheduleTimer(() => {
             state.bobUp = !state.bobUp;
             scheduleBob();
         }, 500);
     }
-    // ── Blink animation: eyes close for 150ms, random 2-8s intervals ──────
     function scheduleBlink() {
         const interval = randInt(2000, 8000);
         scheduleTimer(() => {
-            // Perform blink
             state.isBlinking = true;
             scheduleTimer(() => {
                 state.isBlinking = false;
-                // 30% chance of double-blink
                 if (Math.random() < 0.3) {
                     scheduleTimer(() => {
                         state.isBlinking = true;
@@ -201,9 +134,7 @@ export function createPhrenAnimator(options) {
             }, 150);
         }, interval);
     }
-    // ── Sparkle animation: fast cycle during bursts, long pauses between ───
     function scheduleSparkle() {
-        // Wait 1-5 seconds before next sparkle burst
         const pause = randInt(1000, 5000);
         scheduleTimer(() => {
             state.sparkleActive = true;
@@ -213,7 +144,6 @@ export function createPhrenAnimator(options) {
     }
     function sparkleStep(step) {
         if (step >= SPARKLE_CHARS.length) {
-            // Burst complete
             state.sparkleActive = false;
             scheduleSparkle();
             return;
@@ -223,7 +153,6 @@ export function createPhrenAnimator(options) {
             sparkleStep(step + 1);
         }, 200);
     }
-    // ── Lean animation: shift 1 col left or right every 4-10s, hold 1-2s ──
     function scheduleLean() {
         const interval = randInt(4000, 10000);
         scheduleTimer(() => {
@@ -240,19 +169,15 @@ export function createPhrenAnimator(options) {
         getFrame() {
             let lines = baseArt.map((line, i) => {
                 let result = line;
-                // Apply blink to the eye row
                 if (state.isBlinking && i === EYE_ROW) {
                     result = applyBlinkToLine(result);
                 }
-                // Apply sparkle to sparkle row
                 if (i === SPARKLE_ROW) {
                     result = applySparkleToLine(result, state.sparkleFrame, state.sparkleActive);
                 }
-                // Apply lean
                 result = applyLean(result, state.leanOffset);
                 return result;
             });
-            // Apply bob: when bobUp, prepend a blank line (shift everything down visually)
             if (state.bobUp) {
                 lines = ["", ...lines.slice(0, -1)];
             }
@@ -272,56 +197,9 @@ export function createPhrenAnimator(options) {
         },
     };
 }
-// ── Startup frames (pre-baked, no timers) ────────────────────────────────────
-/**
- * Returns 4 pre-baked animation frames for shell startup display.
- * No timers needed — the caller cycles through them manually.
- *
- * Frames: [neutral, bob-up, neutral, bob-down(sparkle)]
- *
- * @param facing - 'left' (default) or 'right'
- */
-export function getPhrenStartupFrames(facing) {
-    const art = facing === "right" ? PHREN_ART_RIGHT : PHREN_ART;
-    // Frame 0: neutral
-    const frame0 = [...art];
-    // Frame 1: bob up (prepend blank line, drop last line)
-    const frame1 = ["", ...art.slice(0, -1)];
-    // Frame 2: neutral (same as frame 0)
-    const frame2 = [...art];
-    // Frame 3: bob down with sparkle burst — shift down by removing first line, append blank
-    const frame3WithSparkle = art.map((line, i) => {
-        if (i === SPARKLE_ROW) {
-            return applySparkleToLine(line, 0, true); // ✦ sparkle
-        }
-        return line;
-    });
-    const frame3 = [...frame3WithSparkle.slice(1), ""];
-    return [frame0, frame1, frame2, frame3];
-}
-// ── Legacy exports (unchanged) ───────────────────────────────────────────────
-/** Single-line compact phren for inline use */
-export const PHREN_INLINE = `${PURPLE}◆${RESET}`;
-/** Phren spinner frames for search/sync operations — cycles through in purple */
-export const PHREN_SPINNER_FRAMES = [
-    `${BRIGHT_PURPLE}◆${RESET}`,
-    `${PURPLE}◇${RESET}`,
-    `${CYAN}✦${RESET}`,
-    `${PURPLE}✧${RESET}`,
-    `${BRIGHT_PURPLE}◆${RESET}`,
-    `${DARK_PURPLE}◇${RESET}`,
-];
-/** Default spinner interval in ms */
-export const PHREN_SPINNER_INTERVAL_MS = 120;
 /**
  * Return the phren art as a single string, optionally indented.
  */
 export function renderPhrenArt(indent = "") {
     return PHREN_ART.map(line => indent + line).join("\n");
 }
-/**
- * Get a spinner frame by index (wraps around automatically).
- */
-export function spinnerFrame(tick) {
-    return PHREN_SPINNER_FRAMES[tick % PHREN_SPINNER_FRAMES.length];
-}

package/mcp/dist/phren-paths.js

@@ -7,6 +7,10 @@ import { bootstrapPhrenDotEnv } from "./phren-dotenv.js";
 import { PhrenError, isRecord, RESERVED_PROJECT_DIR_NAMES } from "./phren-core.js";
 import { errorMessage, isValidProjectName, safeProjectPath } from "./utils.js";
 bootstrapPhrenDotEnv();
+function stderrLog(msg) { try {
+    process.stderr.write("[phren] " + msg + "\n");
+}
+catch { } }
 export const ROOT_MANIFEST_FILENAME = "phren.root.yaml";
 export function homeDir() {
     return process.env.HOME || process.env.USERPROFILE || os.homedir();
@@ -75,7 +79,7 @@ export function readRootManifest(phrenPath) {
     }
     catch (err) {
         if ((process.env.PHREN_DEBUG))
-            process.stderr.write(`[phren] readRootManifest: ${errorMessage(err)}\n`);
+            stderrLog(`readRootManifest: ${errorMessage(err)}`);
         return null;
     }
 }
@@ -263,6 +267,20 @@ export function debugLog(msg) {
         // debug log is best-effort; logging errors about logging would recurse
     }
 }
+/** Always-on structured error log (no PHREN_DEBUG gate). */
+export function errorLog(tool, msg) {
+    try {
+        const phrenPath = findPhrenPath();
+        if (!phrenPath)
+            return;
+        const logFile = runtimeFile(phrenPath, "debug.log");
+        const line = JSON.stringify({ ts: new Date().toISOString(), level: "error", tool, message: msg });
+        fs.appendFileSync(logFile, line + "\n");
+    }
+    catch {
+        // Logging must never throw
+    }
+}
 export function appendIndexEvent(phrenPath, event) {
     try {
         const file = runtimeFile(phrenPath, "index-events.jsonl");
@@ -270,7 +288,7 @@ export function appendIndexEvent(phrenPath, event) {
     }
     catch (err) {
         if ((process.env.PHREN_DEBUG))
-            process.stderr.write(`[phren] appendIndexEvent: ${errorMessage(err)}\n`);
+            stderrLog(`appendIndexEvent: ${errorMessage(err)}`);
     }
 }
 /** Resolve the canonical findings file for a project directory. */
@@ -301,7 +319,7 @@ export function findProjectNameCaseInsensitive(phrenPath, name) {
     }
     catch (err) {
         if ((process.env.PHREN_DEBUG))
-            process.stderr.write(`[phren] findProjectNameCaseInsensitive: ${errorMessage(err)}\n`);
+            stderrLog(`findProjectNameCaseInsensitive: ${errorMessage(err)}`);
     }
     return null;
 }
@@ -318,7 +336,7 @@ export function findArchivedProjectNameCaseInsensitive(phrenPath, name) {
     }
     catch (err) {
         if ((process.env.PHREN_DEBUG))
-            process.stderr.write(`[phren] findArchivedProjectNameCaseInsensitive: ${errorMessage(err)}\n`);
+            stderrLog(`findArchivedProjectNameCaseInsensitive: ${errorMessage(err)}`);
     }
     return null;
 }
@@ -342,26 +360,26 @@ export function getProjectDirs(phrenPath, profile) {
     }
     if (profile) {
         if (!isValidProjectName(profile)) {
-            console.error(`${PhrenError.VALIDATION_ERROR}: Invalid PHREN_PROFILE value: ${profile}`);
+            errorLog("getProjectDirs", `${PhrenError.VALIDATION_ERROR}: Invalid PHREN_PROFILE value: ${profile}`);
             return [];
         }
         const profilePath = path.join(phrenPath, "profiles", `${profile}.yaml`);
         if (!fs.existsSync(profilePath)) {
-            console.error(`${PhrenError.FILE_NOT_FOUND}: Profile file not found: ${profilePath}`);
+            errorLog("getProjectDirs", `${PhrenError.FILE_NOT_FOUND}: Profile file not found: ${profilePath}`);
             return [];
         }
         try {
             const data = yaml.load(fs.readFileSync(profilePath, "utf-8"), { schema: yaml.CORE_SCHEMA });
             const projects = isRecord(data) ? data.projects : undefined;
             if (!Array.isArray(projects)) {
-                console.error(`${PhrenError.MALFORMED_YAML}: Profile YAML missing valid "projects" array: ${profilePath}`);
+                errorLog("getProjectDirs", `${PhrenError.MALFORMED_YAML}: Profile YAML missing valid "projects" array: ${profilePath}`);
                 return [];
             }
             const listed = projects
                 .map((p) => {
                 const name = String(p);
                 if (!isValidProjectName(name)) {
-                    console.error(`${PhrenError.VALIDATION_ERROR}: Skipping invalid project name in profile: ${name}`);
+                    errorLog("getProjectDirs", `${PhrenError.VALIDATION_ERROR}: Skipping invalid project name in profile: ${name}`);
                     return null;
                 }
                 return safeProjectPath(phrenPath, name);
@@ -374,8 +392,8 @@ export function getProjectDirs(phrenPath, profile) {
         }
         catch (err) {
             if ((process.env.PHREN_DEBUG))
-                process.stderr.write(`[phren] getProjectDirs yamlParse: ${errorMessage(err)}\n`);
-            console.error(`${PhrenError.MALFORMED_YAML}: Malformed profile YAML: ${profilePath}`);
+                stderrLog(`getProjectDirs yamlParse: ${errorMessage(err)}`);
+            errorLog("getProjectDirs", `${PhrenError.MALFORMED_YAML}: Malformed profile YAML: ${profilePath}`);
             return [];
         }
     }
@@ -386,7 +404,7 @@ export function getProjectDirs(phrenPath, profile) {
     }
     catch (err) {
         if ((process.env.PHREN_DEBUG))
-            process.stderr.write(`[phren] getProjectDirs: ${errorMessage(err)}\n`);
+            stderrLog(`getProjectDirs: ${errorMessage(err)}`);
         return [];
     }
 }
@@ -413,7 +431,7 @@ export function collectNativeMemoryFiles() {
     }
     catch (err) {
         if ((process.env.PHREN_DEBUG))
-            process.stderr.write(`[phren] collectNativeMemoryFiles: ${errorMessage(err)}\n`);
+            stderrLog(`collectNativeMemoryFiles: ${errorMessage(err)}`);
     }
     return results;
 }