@phren/cli 0.0.1

package/mcp/dist/utils.js

@@ -0,0 +1,543 @@
+import * as fs from "fs";
+import * as path from "path";
+import { execFileSync, spawnSync } from "child_process";
+import * as yaml from "js-yaml";
+import { fileURLToPath } from "url";
+import { findPhrenPath } from "./phren-paths.js";
+import { bootstrapPhrenDotEnv } from "./phren-dotenv.js";
+const _moduleDir = path.dirname(fileURLToPath(import.meta.url));
+function loadSynonymsJson(fileName) {
+    const filePath = path.join(_moduleDir, fileName);
+    try {
+        return JSON.parse(fs.readFileSync(filePath, "utf8"));
+    }
+    catch (err) {
+        if ((process.env.PHREN_DEBUG || process.env.PHREN_DEBUG))
+            process.stderr.write(`[phren] ${fileName} load failed: ${err instanceof Error ? err.message : String(err)}\n`);
+        return {};
+    }
+}
+const _baseSynonymsJson = loadSynonymsJson("synonyms.json");
+// ── Shared Git helper ────────────────────────────────────────────────────────
+export function runGitOrThrow(cwd, args, timeoutMs) {
+    const result = spawnSync("git", args, {
+        cwd,
+        encoding: "utf8",
+        stdio: ["ignore", "pipe", "pipe"],
+        timeout: timeoutMs,
+    });
+    if (result.error)
+        throw result.error;
+    if (result.status !== 0) {
+        const stderr = (result.stderr ?? "").trim();
+        const suffix = stderr ? `: ${stderr}` : result.signal ? ` (signal: ${result.signal})` : "";
+        throw new Error(`git ${args.join(" ")} exited with status ${result.status ?? "unknown"}${suffix}`);
+    }
+    return result.stdout ?? "";
+}
+export function runGit(cwd, args, timeoutMs, debugLogFn) {
+    try {
+        return runGitOrThrow(cwd, args, timeoutMs).trim();
+    }
+    catch (err) {
+        const msg = errorMessage(err);
+        if (debugLogFn)
+            debugLogFn(`runGit: git ${args[0]} failed in ${cwd}: ${msg}`);
+        return null;
+    }
+}
+function needsCommandShell(cmd) {
+    return /\.(cmd|bat)$/i.test(path.basename(cmd));
+}
+export function normalizeExecCommand(cmd, platform = process.platform, whereOutput) {
+    if (platform !== "win32")
+        return { command: cmd, shell: false };
+    if (cmd.includes("\\") || cmd.includes("/") || /\.[A-Za-z0-9]+$/i.test(path.basename(cmd))) {
+        return { command: cmd, shell: needsCommandShell(cmd) };
+    }
+    const candidate = (whereOutput || "")
+        .split(/\r?\n/)
+        .map((line) => line.trim())
+        .find(Boolean);
+    const resolved = candidate || cmd;
+    return { command: resolved, shell: needsCommandShell(resolved) };
+}
+export function resolveExecCommand(cmd) {
+    if (process.platform !== "win32")
+        return { command: cmd, shell: false };
+    try {
+        const whereOutput = execFileSync("where.exe", [cmd], {
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "ignore"],
+            timeout: 5000,
+        });
+        return normalizeExecCommand(cmd, process.platform, whereOutput);
+    }
+    catch {
+        return normalizeExecCommand(cmd, process.platform, null);
+    }
+}
+// ── Error message extractor ─────────────────────────────────────────────────
+export function errorMessage(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+// ── Feature flag and clamping helpers ────────────────────────────────────────
+export function isFeatureEnabled(envName, defaultValue = true) {
+    bootstrapPhrenDotEnv();
+    const raw = process.env[envName];
+    if (!raw)
+        return defaultValue;
+    return !["0", "false", "off", "no"].includes(raw.trim().toLowerCase());
+}
+export function clampInt(raw, fallback, min, max) {
+    const parsed = Number.parseInt(raw || "", 10);
+    if (Number.isNaN(parsed))
+        return fallback;
+    return Math.min(max, Math.max(min, parsed));
+}
+// Base synonym map for fuzzy search expansion — source of truth is mcp/src/synonyms.json
+const BASE_SYNONYMS = _baseSynonymsJson;
+const LEARNED_SYNONYMS_FILE = "learned-synonyms.json";
+function normalizeSynonymTerm(term) {
+    return term.toLowerCase().replace(/"/g, "").trim();
+}
+function normalizeSynonymValues(items, baseTerm) {
+    const normalizedBase = baseTerm ? normalizeSynonymTerm(baseTerm) : "";
+    const seen = new Set();
+    const normalized = [];
+    for (const raw of items) {
+        const term = normalizeSynonymTerm(raw);
+        if (!term || term.length <= 1 || term === normalizedBase || seen.has(term))
+            continue;
+        seen.add(term);
+        normalized.push(term);
+    }
+    return normalized;
+}
+function mergeSynonymMaps(...maps) {
+    const merged = {};
+    for (const map of maps) {
+        for (const [rawKey, rawValues] of Object.entries(map)) {
+            const key = normalizeSynonymTerm(rawKey);
+            if (!key)
+                continue;
+            const existing = merged[key] ?? [];
+            const values = normalizeSynonymValues([...(existing || []), ...(Array.isArray(rawValues) ? rawValues : [])], key);
+            if (values.length > 0)
+                merged[key] = values;
+        }
+    }
+    return merged;
+}
+// Common English stop words to strip from prompts before searching
+export const STOP_WORDS = new Set([
+    "the", "is", "a", "an", "and", "or", "but", "in", "on", "at", "to", "for",
+    "of", "with", "by", "from", "it", "this", "that", "are", "was", "were",
+    "be", "been", "being", "have", "has", "had", "do", "does", "did", "will",
+    "would", "could", "should", "may", "might", "can", "shall", "not", "no",
+    "so", "if", "then", "than", "too", "very", "just", "about", "up", "out",
+    "my", "me", "i", "you", "your", "we", "our", "they", "them", "their",
+    "he", "she", "his", "her", "its", "what", "which", "who", "when", "where",
+    "how", "why", "all", "each", "every", "some", "any", "few", "more", "most",
+    "other", "into", "over", "such", "only", "own", "same", "also", "back",
+    "get", "got", "make", "made", "take", "like", "well", "here", "there",
+    "use", "using", "used", "need", "want", "look", "help", "please",
+]);
+// Extract meaningful keywords from a prompt, including bigrams (2-word noun phrases).
+// Bigrams capture intent better than isolated words (e.g., "rate limit" vs "rate" + "limit").
+export function extractKeywordEntries(text) {
+    const words = text
+        .toLowerCase()
+        .replace(/[^\w\s-]/g, " ")
+        .split(/\s+/)
+        .filter(w => w.length > 1 && !STOP_WORDS.has(w));
+    // Build bigrams from adjacent non-stop-words
+    const bigrams = [];
+    for (let i = 0; i < words.length - 1; i++) {
+        // Filter out bigrams where both tokens are stop words (words is already filtered,
+        // so this is defensive — the real stop-word bigram filter is in buildRobustFtsQuery)
+        bigrams.push(`${words[i]} ${words[i + 1]}`);
+    }
+    // Deduplicate and limit: prefer individual words first, then bigrams add extra signal
+    const seen = new Set();
+    const result = [];
+    for (const w of [...words, ...bigrams]) {
+        if (!seen.has(w)) {
+            seen.add(w);
+            result.push(w);
+        }
+        if (result.length >= 10)
+            break;
+    }
+    return result;
+}
+export function extractKeywords(text) {
+    return extractKeywordEntries(text).join(" ");
+}
+// Validate a project name: lowercase letters/numbers with optional hyphen/underscore separators.
+// Must not start with a hyphen (breaks CLI flags) or dot (hidden dirs). Max 100 chars.
+// Internal keys like "native:-home" bypass this — they never go through user-facing validation.
+// Explicitly rejects traversal sequences, null bytes, and path separators as defense-in-depth.
+export function isValidProjectName(name) {
+    if (!name || name.length === 0)
+        return false;
+    if (name.length > 100)
+        return false;
+    // Reject null bytes, path separators, and traversal patterns before the regex check
+    if (name.includes("\0") || name.includes("/") || name.includes("\\") || name.includes(".."))
+        return false;
+    return /^[a-z0-9][a-z0-9_-]*$/.test(name);
+}
+// Resolve a path inside the phren directory and reject anything that escapes it.
+// Checks both lexical resolution and (when the path exists) real path after symlink
+// resolution to prevent symlink-based traversal.
+export function safeProjectPath(base, ...segments) {
+    // Reject segments containing null bytes
+    for (const seg of segments) {
+        if (seg.includes("\0"))
+            return null;
+    }
+    const resolvedBase = path.resolve(base);
+    const resolved = path.resolve(base, ...segments);
+    if (resolved !== resolvedBase && !resolved.startsWith(resolvedBase + path.sep))
+        return null;
+    // Walk up from resolved path to find the deepest existing ancestor and verify
+    // it resolves inside base after symlink resolution. This catches symlink escapes
+    // even when the final leaf doesn't exist yet.
+    try {
+        let check = resolved;
+        while (!fs.existsSync(check) && check !== resolvedBase) {
+            check = path.dirname(check);
+        }
+        if (fs.existsSync(check)) {
+            const realBase = fs.realpathSync.native(resolvedBase);
+            const realCheck = fs.realpathSync.native(check);
+            if (realCheck !== realBase && !realCheck.startsWith(realBase + path.sep))
+                return null;
+        }
+    }
+    catch {
+        // If realpath fails (e.g. broken symlink), reject to be safe
+        return null;
+    }
+    return resolved;
+}
+const QUEUE_FILENAME = "MEMORY_QUEUE.md";
+export function queueFilePath(phrenPath, project) {
+    if (!isValidProjectName(project)) {
+        throw new Error(`Invalid project name: ${project}`);
+    }
+    const result = safeProjectPath(phrenPath, project, QUEUE_FILENAME);
+    if (!result) {
+        throw new Error(`Path traversal detected for project: ${project}`);
+    }
+    return result;
+}
+// Sanitize user input before passing it to an FTS5 MATCH expression.
+// Strips FTS5-specific syntax that could cause injection or parse errors.
+export function sanitizeFts5Query(raw) {
+    if (!raw)
+        return "";
+    if (raw.length > 500)
+        raw = raw.slice(0, 500);
+    // Whitelist approach: only allow alphanumeric, spaces, hyphens, apostrophes, double quotes, asterisks
+    let q = raw.replace(/[^a-zA-Z0-9 \-'"*]/g, " ");
+    q = q.replace(/\s+/g, " ");
+    q = q.trim();
+    // Q83: FTS5 only accepts * as a prefix operator directly attached to a token
+    // (e.g. "foo*").  A bare trailing asterisk (or lone "*") produces invalid
+    // FTS5 syntax.  Strip any asterisk that is not immediately preceded by a
+    // word character so the query remains valid.
+    q = q.replace(/(?<!\w)\*/g, "");
+    // Also strip a trailing asterisk that is preceded only by whitespace at word
+    // end of the whole query (handles "foo *" → "foo").
+    q = q.replace(/\s+\*$/g, "");
+    return q.trim();
+}
+function parseSynonymsYaml(filePath) {
+    if (!fs.existsSync(filePath))
+        return {};
+    try {
+        const parsed = yaml.load(fs.readFileSync(filePath, "utf8"), { schema: yaml.CORE_SCHEMA });
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+            return {};
+        const loaded = {};
+        for (const [rawKey, value] of Object.entries(parsed)) {
+            const key = String(rawKey).trim().toLowerCase();
+            if (!key || !Array.isArray(value))
+                continue;
+            const synonyms = value
+                .filter((item) => typeof item === "string")
+                .map((item) => item.replace(/"/g, "").trim())
+                .filter((item) => item.length > 1);
+            if (synonyms.length > 0)
+                loaded[key] = synonyms;
+        }
+        return loaded;
+    }
+    catch (err) {
+        if ((process.env.PHREN_DEBUG || process.env.PHREN_DEBUG))
+            process.stderr.write(`[phren] synonyms.yaml parse failed (${filePath}): ${err instanceof Error ? err.message : String(err)}\n`);
+        return {};
+    }
+}
+function loadUserSynonyms(project, phrenPath) {
+    const resolved = phrenPath ?? findPhrenPath();
+    if (!resolved)
+        return {};
+    const globalSynonyms = parseSynonymsYaml(path.join(resolved, "global", "synonyms.yaml"));
+    if (!project || !isValidProjectName(project))
+        return globalSynonyms;
+    const projectSynonyms = parseSynonymsYaml(path.join(resolved, project, "synonyms.yaml"));
+    return {
+        ...globalSynonyms,
+        ...projectSynonyms,
+    };
+}
+function parseLearnedSynonymsJson(filePath) {
+    if (!fs.existsSync(filePath))
+        return {};
+    try {
+        const parsed = JSON.parse(fs.readFileSync(filePath, "utf8"));
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+            return {};
+        const loaded = {};
+        for (const [rawKey, rawValue] of Object.entries(parsed)) {
+            if (!Array.isArray(rawValue))
+                continue;
+            const key = normalizeSynonymTerm(rawKey);
+            if (!key)
+                continue;
+            const synonyms = normalizeSynonymValues(rawValue.filter((v) => typeof v === "string"), key);
+            if (synonyms.length > 0)
+                loaded[key] = synonyms;
+        }
+        return loaded;
+    }
+    catch (err) {
+        if ((process.env.PHREN_DEBUG || process.env.PHREN_DEBUG))
+            process.stderr.write(`[phren] learned-synonyms parse failed (${filePath}): ${err instanceof Error ? err.message : String(err)}\n`);
+        return {};
+    }
+}
+export function learnedSynonymsPath(phrenPath, project) {
+    if (!isValidProjectName(project))
+        return null;
+    return safeProjectPath(phrenPath, project, LEARNED_SYNONYMS_FILE);
+}
+export function loadLearnedSynonyms(project, phrenPath) {
+    if (!project || !isValidProjectName(project))
+        return {};
+    const resolved = phrenPath ?? findPhrenPath();
+    if (!resolved)
+        return {};
+    const targetPath = learnedSynonymsPath(resolved, project);
+    if (!targetPath)
+        return {};
+    return parseLearnedSynonymsJson(targetPath);
+}
+export function loadSynonymMap(project, phrenPath) {
+    return mergeSynonymMaps(BASE_SYNONYMS, loadUserSynonyms(project, phrenPath), loadLearnedSynonyms(project, phrenPath));
+}
+export function learnSynonym(phrenPath, project, term, synonyms) {
+    if (!isValidProjectName(project))
+        throw new Error(`Invalid project name: ${project}`);
+    const targetPath = learnedSynonymsPath(phrenPath, project);
+    if (!targetPath)
+        throw new Error(`Path traversal detected for project: ${project}`);
+    const normalizedTerm = normalizeSynonymTerm(term);
+    if (!normalizedTerm || normalizedTerm.length <= 1) {
+        throw new Error("Invalid synonym term");
+    }
+    const normalizedSynonyms = normalizeSynonymValues(synonyms, normalizedTerm);
+    if (normalizedSynonyms.length === 0) {
+        return loadLearnedSynonyms(project, phrenPath);
+    }
+    fs.mkdirSync(path.dirname(targetPath), { recursive: true });
+    const existing = parseLearnedSynonymsJson(targetPath);
+    const next = mergeSynonymMaps(existing, { [normalizedTerm]: normalizedSynonyms });
+    const tmpPath = `${targetPath}.tmp-${Date.now()}`;
+    fs.writeFileSync(tmpPath, JSON.stringify(next, null, 2) + "\n", "utf8");
+    fs.renameSync(tmpPath, targetPath);
+    return next;
+}
+export function removeLearnedSynonym(phrenPath, project, term, synonyms) {
+    if (!isValidProjectName(project))
+        throw new Error(`Invalid project name: ${project}`);
+    const targetPath = learnedSynonymsPath(phrenPath, project);
+    if (!targetPath)
+        throw new Error(`Path traversal detected for project: ${project}`);
+    const normalizedTerm = normalizeSynonymTerm(term);
+    if (!normalizedTerm || normalizedTerm.length <= 1) {
+        throw new Error("Invalid synonym term");
+    }
+    const existing = parseLearnedSynonymsJson(targetPath);
+    if (!existing[normalizedTerm])
+        return existing;
+    if (!synonyms || synonyms.length === 0) {
+        delete existing[normalizedTerm];
+    }
+    else {
+        const drop = new Set(normalizeSynonymValues(synonyms));
+        existing[normalizedTerm] = (existing[normalizedTerm] || []).filter((item) => !drop.has(item));
+        if (existing[normalizedTerm].length === 0)
+            delete existing[normalizedTerm];
+    }
+    fs.mkdirSync(path.dirname(targetPath), { recursive: true });
+    if (Object.keys(existing).length === 0) {
+        try {
+            fs.unlinkSync(targetPath);
+        }
+        catch { }
+        return {};
+    }
+    const tmpPath = `${targetPath}.tmp-${Date.now()}`;
+    fs.writeFileSync(tmpPath, JSON.stringify(existing, null, 2) + "\n", "utf8");
+    fs.renameSync(tmpPath, targetPath);
+    return existing;
+}
+function buildFtsClauses(raw, project, phrenPath) {
+    const MAX_TOTAL_TERMS = 10;
+    const MAX_SYNONYM_GROUPS = 3;
+    // Step 1: Sanitize — strip FTS5 special chars, enforce length limits
+    const safe = sanitizeFts5Query(raw);
+    if (!safe)
+        return [];
+    // Step 2: Merge built-in and per-project synonym maps
+    const synonymsMap = loadSynonymMap(project, phrenPath);
+    // Step 3: Tokenize — split sanitized input into individual words (min length 2)
+    const baseWords = safe.split(/\s+/).filter((t) => t.length > 1);
+    if (baseWords.length === 0)
+        return [];
+    // Step 4: Filter stop words — remove common English words that add no search signal
+    const filteredTerms = baseWords.filter((t) => !STOP_WORDS.has(t.toLowerCase()));
+    // Step 5: Build bigrams — sliding window over adjacent filtered terms for phrase matching
+    const bigrams = [];
+    for (let i = 0; i < filteredTerms.length - 1; i++) {
+        bigrams.push(`${filteredTerms[i]} ${filteredTerms[i + 1]}`);
+    }
+    // Step 6: Match bigrams against synonym keys — bigram matches are promoted to quoted
+    // phrases and their constituent words are marked consumed (not repeated as singletons)
+    const consumedIndices = new Set();
+    const matchedBigrams = [];
+    for (let i = 0; i < bigrams.length; i++) {
+        const bg = bigrams[i].toLowerCase();
+        if (synonymsMap[bg]) {
+            consumedIndices.add(i);
+            consumedIndices.add(i + 1);
+            matchedBigrams.push(bigrams[i]);
+        }
+    }
+    // Step 7: Assemble and deduplicate core terms — matched bigrams (as quoted phrases)
+    // first, then unconsumed individual words; duplicates removed via seenTerms
+    const dedupedTerms = [];
+    const seenTerms = new Set();
+    for (const bg of matchedBigrams) {
+        const clean = bg.replace(/"/g, "").trim().toLowerCase();
+        if (!seenTerms.has(clean)) {
+            seenTerms.add(clean);
+            dedupedTerms.push(`"${bg.replace(/"/g, "").trim()}"`);
+        }
+    }
+    for (let i = 0; i < filteredTerms.length; i++) {
+        if (!consumedIndices.has(i)) {
+            const w = filteredTerms[i].replace(/"/g, "").trim();
+            const wLow = w.toLowerCase();
+            if (w.length > 1 && !seenTerms.has(wLow)) {
+                seenTerms.add(wLow);
+                dedupedTerms.push(`"${w}"`);
+            }
+        }
+    }
+    if (dedupedTerms.length === 0)
+        return [];
+    // Step 8: Expand synonyms — for up to MAX_SYNONYM_GROUPS core terms, add OR alternatives
+    // from the synonym map; total term count is capped at MAX_TOTAL_TERMS to keep queries sane
+    let totalTermCount = dedupedTerms.length;
+    let groupsExpanded = 0;
+    const expandedClauses = [];
+    for (const coreTerm of dedupedTerms) {
+        const termText = coreTerm.slice(1, -1).toLowerCase(); // strip surrounding quotes
+        const synonyms = [];
+        if (groupsExpanded < MAX_SYNONYM_GROUPS && synonymsMap[termText]) {
+            for (const syn of synonymsMap[termText]) {
+                if (totalTermCount >= MAX_TOTAL_TERMS)
+                    break;
+                const cleanSyn = syn.replace(/"/g, "").trim();
+                if (cleanSyn.length > 1) {
+                    synonyms.push(`"${cleanSyn}"`);
+                    totalTermCount++;
+                }
+            }
+            groupsExpanded++;
+        }
+        if (synonyms.length > 0) {
+            expandedClauses.push(`(${coreTerm} OR ${synonyms.join(" OR ")})`);
+        }
+        else {
+            expandedClauses.push(coreTerm);
+        }
+    }
+    // Step 9: Join all clauses with AND — every core term (with its OR synonyms) must match
+    return expandedClauses;
+}
+function clauseSignalScore(clause) {
+    const normalized = clause
+        .replace(/[()"]/g, " ")
+        .replace(/\bOR\b/gi, " ")
+        .replace(/\s+/g, " ")
+        .trim()
+        .toLowerCase();
+    if (!normalized)
+        return 0;
+    const tokens = normalized.split(" ").filter(Boolean);
+    const longestToken = tokens.reduce((max, token) => Math.max(max, token.length), 0);
+    const phraseBonus = tokens.length > 1 ? 1.5 : 0;
+    const synonymBonus = /\bOR\b/i.test(clause) ? 0.5 : 0;
+    return longestToken + phraseBonus + synonymBonus;
+}
+// Build a defensive FTS5 MATCH query:
+// - sanitizes user input
+// - extracts bigrams and treats them as quoted phrases
+// - expands known synonyms (capped at 10 total terms)
+// - applies AND between core terms, with synonyms as OR alternatives
+export function buildRobustFtsQuery(raw, project, phrenPath) {
+    const clauses = buildFtsClauses(raw, project, phrenPath);
+    if (clauses.length === 0)
+        return "";
+    return clauses.join(" AND ");
+}
+// Build a relaxed lexical rescue query that matches any 2 of the most informative
+// clauses. This is only intended as a fallback when the stricter AND query returns
+// nothing; it trades precision for recall while staying in the FTS index.
+export function buildRelaxedFtsQuery(raw, project, phrenPath) {
+    const clauses = buildFtsClauses(raw, project, phrenPath);
+    if (clauses.length < 3)
+        return "";
+    const salientClauses = clauses
+        .map((clause, index) => ({ clause, index, score: clauseSignalScore(clause) }))
+        .sort((a, b) => {
+        const scoreDelta = b.score - a.score;
+        if (Math.abs(scoreDelta) > 0.01)
+            return scoreDelta;
+        return a.index - b.index;
+    })
+        .slice(0, Math.min(4, clauses.length))
+        .sort((a, b) => a.index - b.index);
+    if (salientClauses.length < 2)
+        return "";
+    const combos = [];
+    for (let i = 0; i < salientClauses.length - 1; i++) {
+        for (let j = i + 1; j < salientClauses.length; j++) {
+            combos.push(`(${salientClauses[i].clause} AND ${salientClauses[j].clause})`);
+        }
+    }
+    return combos.join(" OR ");
+}
+export function buildFtsQueryVariants(raw, project, phrenPath) {
+    const variants = [
+        buildRobustFtsQuery(raw, project, phrenPath),
+        buildRelaxedFtsQuery(raw, project, phrenPath),
+    ].filter(Boolean);
+    return [...new Set(variants)];
+}

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "@phren/cli",
+  "version": "0.0.1",
+  "description": "Long-term memory for AI agents. Stored as markdown in a git repo you own.",
+  "type": "module",
+  "bin": {
+    "phren": "mcp/dist/index.js"
+  },
+  "files": [
+    "mcp/dist",
+    "starter",
+    "skills"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.27.1",
+    "chalk": "^5.6.2",
+    "glob": "^13.0.6",
+    "inquirer": "^12.10.0",
+    "js-yaml": "^4.1.1",
+    "sharp": "^0.34.5",
+    "sql.js-fts5": "^1.4.0",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@playwright/test": "^1.58.2",
+    "@types/js-yaml": "^4.0.9",
+    "@types/node": "^25.3.5",
+    "@typescript-eslint/eslint-plugin": "^8.56.1",
+    "@typescript-eslint/parser": "^8.56.1",
+    "@vitest/coverage-v8": "^4.0.18",
+    "eslint": "^10.0.3",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.18"
+  },
+  "scripts": {
+    "build": "rm -rf mcp/dist && tsc -p mcp/tsconfig.json && chmod +x mcp/dist/index.js && cp mcp/src/synonyms*.json mcp/dist/",
+    "dev": "tsx mcp/src/index.ts",
+    "lint": "eslint mcp/src/ --ignore-pattern '*.test.ts'",
+    "validate-docs": "bash scripts/validate-docs.sh",
+    "pretest": "npm run build",
+    "test": "vitest run",
+    "test:e2e": "npm run build && playwright test",
+    "test:e2e:install": "playwright install chromium",
+    "bench": "tsx mcp/bench/locomo-runner.ts --sessions 3",
+    "bench:retrieval": "tsx scripts/bench-retrieval-modes.ts",
+    "bench:retrieval:synthetic": "tsx scripts/bench-retrieval-synthetic.ts",
+    "prepublishOnly": "npm run build && npm test"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "keywords": [
+    "claude",
+    "claude-code",
+    "mcp",
+    "memory",
+    "knowledge"
+  ],
+  "author": "Ala Arab",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/alaarab/phren.git"
+  },
+  "homepage": "https://github.com/alaarab/phren#readme"
+}

package/skills/README.md

@@ -0,0 +1,7 @@
+# skills/
+
+Phren slash commands that users invoke with `phren-<name>` (e.g. `phren-init`, `phren-sync`).
+
+Each subdirectory contains a `SKILL.md` file with the full prompt that Claude executes when the skill is invoked. These are global skills shipped with the phren package -- they work across all projects.
+
+Users interact with this directory when adding custom global skills or reading what built-in skills do. For project-specific skills, use `~/.phren/<project>/skills/` instead.