@sheepbun/yips 0.1.1

package/dist/app/update-check.js

@@ -0,0 +1,132 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getInstalledPackageVersion = getInstalledPackageVersion;
+exports.checkForUpdates = checkForUpdates;
+const promises_1 = require("node:fs/promises");
+const node_path_1 = require("node:path");
+const DEFAULT_PACKAGE_NAME = "@sheepbun/yips";
+const DEFAULT_REGISTRY_BASE_URL = "https://registry.npmjs.org";
+const FALLBACK_VERSION = "0.1.0";
+const PACKAGE_JSON_PATH = (0, node_path_1.resolve)(__dirname, "../..", "package.json");
+function normalizeSemverInput(version) {
+    return version.trim().replace(/^v/u, "");
+}
+function parseSemver(version) {
+    const normalized = normalizeSemverInput(version);
+    const match = normalized.match(/^(\d+)\.(\d+)\.(\d+)(?:[-+].*)?$/u);
+    if (!match) {
+        return null;
+    }
+    const major = Number(match[1]);
+    const minor = Number(match[2]);
+    const patch = Number(match[3]);
+    if (!Number.isInteger(major) || !Number.isInteger(minor) || !Number.isInteger(patch)) {
+        return null;
+    }
+    return [major, minor, patch];
+}
+function compareSemver(left, right) {
+    const leftParsed = parseSemver(left);
+    const rightParsed = parseSemver(right);
+    if (!leftParsed || !rightParsed) {
+        return null;
+    }
+    const [leftMajor, leftMinor, leftPatch] = leftParsed;
+    const [rightMajor, rightMinor, rightPatch] = rightParsed;
+    const components = [
+        [leftMajor, rightMajor],
+        [leftMinor, rightMinor],
+        [leftPatch, rightPatch]
+    ];
+    for (const [leftPart, rightPart] of components) {
+        if (leftPart > rightPart) {
+            return 1;
+        }
+        if (leftPart < rightPart) {
+            return -1;
+        }
+    }
+    return 0;
+}
+async function getInstalledPackageVersion() {
+    try {
+        const parsed = await readInstalledPackageMetadata();
+        if (typeof parsed.version === "string" && parsed.version.trim().length > 0) {
+            return parsed.version.trim();
+        }
+    }
+    catch {
+        // Fallback below.
+    }
+    return FALLBACK_VERSION;
+}
+async function getInstalledPackageName() {
+    try {
+        const parsed = await readInstalledPackageMetadata();
+        if (typeof parsed.name === "string" && parsed.name.trim().length > 0) {
+            return parsed.name.trim();
+        }
+    }
+    catch {
+        // Fallback below.
+    }
+    return DEFAULT_PACKAGE_NAME;
+}
+async function readInstalledPackageMetadata() {
+    const raw = await (0, promises_1.readFile)(PACKAGE_JSON_PATH, "utf8");
+    return JSON.parse(raw);
+}
+async function checkForUpdates(currentVersion, options = {}) {
+    const packageName = options.packageName ?? (await getInstalledPackageName());
+    const registryBaseUrl = (options.registryBaseUrl ?? DEFAULT_REGISTRY_BASE_URL).replace(/\/+$/u, "");
+    const fetchImpl = options.fetchImpl ?? globalThis.fetch;
+    if (!fetchImpl) {
+        return {
+            currentVersion,
+            latestVersion: null,
+            status: "unknown",
+            source: "npm-registry",
+            error: "Fetch API is unavailable in this runtime."
+        };
+    }
+    try {
+        const response = await fetchImpl(`${registryBaseUrl}/${encodeURIComponent(packageName)}/latest`);
+        if (!response.ok) {
+            return {
+                currentVersion,
+                latestVersion: null,
+                status: "unknown",
+                source: "npm-registry",
+                error: `Registry lookup failed (${response.status} ${response.statusText}).`
+            };
+        }
+        const payload = (await response.json());
+        if (typeof payload.version !== "string" || payload.version.trim().length === 0) {
+            return {
+                currentVersion,
+                latestVersion: null,
+                status: "unknown",
+                source: "npm-registry",
+                error: "Registry response did not include a valid version."
+            };
+        }
+        const latestVersion = payload.version.trim();
+        const comparison = compareSemver(currentVersion, latestVersion);
+        return {
+            currentVersion,
+            latestVersion,
+            status: comparison === -1 ? "update-available" : "up-to-date",
+            source: "npm-registry"
+        };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return {
+            currentVersion,
+            latestVersion: null,
+            status: "unknown",
+            source: "npm-registry",
+            error: message
+        };
+    }
+}

package/dist/app/version.js

@@ -0,0 +1,51 @@
+"use strict";
+/** Git-derived date-based versioning in the format vYYYY.M.D-SHORTHASH. */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getGitInfo = getGitInfo;
+exports.generateVersion = generateVersion;
+exports.getVersion = getVersion;
+const node_child_process_1 = require("node:child_process");
+const node_path_1 = require("node:path");
+const node_util_1 = require("node:util");
+const execFile = (0, node_util_1.promisify)(node_child_process_1.execFile);
+const EXEC_TIMEOUT_MS = 5000;
+const SHORT_SHA_LENGTH = 7;
+const FALLBACK_VERSION = "1.0.0";
+const REPO_ROOT = (0, node_path_1.resolve)(__dirname, "../..");
+async function getGitInfo() {
+    try {
+        const [timestampResult, shaResult] = await Promise.all([
+            execFile("git", ["-C", REPO_ROOT, "log", "-1", "--format=%ct"], {
+                timeout: EXEC_TIMEOUT_MS
+            }),
+            execFile("git", ["-C", REPO_ROOT, "rev-parse", `--short=${SHORT_SHA_LENGTH}`, "HEAD"], {
+                timeout: EXEC_TIMEOUT_MS
+            })
+        ]);
+        const timestamp = parseInt(timestampResult.stdout.trim(), 10);
+        if (Number.isNaN(timestamp)) {
+            return null;
+        }
+        const shortSha = shaResult.stdout.trim();
+        if (shortSha.length === 0) {
+            return null;
+        }
+        return { commitDate: new Date(timestamp * 1000), shortSha };
+    }
+    catch {
+        return null;
+    }
+}
+function generateVersion(commitDate, shortSha) {
+    const year = commitDate.getFullYear();
+    const month = commitDate.getMonth() + 1;
+    const day = commitDate.getDate();
+    return `v${year}.${month}.${day}-${shortSha}`;
+}
+async function getVersion() {
+    const info = await getGitInfo();
+    if (info === null) {
+        return FALLBACK_VERSION;
+    }
+    return generateVersion(info.commitDate, info.shortSha);
+}

package/dist/code-context.js

@@ -0,0 +1,68 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.findCodeMdCandidates = findCodeMdCandidates;
+exports.loadCodeContext = loadCodeContext;
+exports.toCodeContextSystemMessage = toCodeContextSystemMessage;
+const promises_1 = require("node:fs/promises");
+const node_path_1 = require("node:path");
+const CODE_MD_FILENAME = "CODE.md";
+const MAX_CODE_MD_CHARS = 24_000;
+function truncateContent(content, maxChars) {
+    if (content.length <= maxChars) {
+        return { content, truncated: false };
+    }
+    return {
+        content: `${content.slice(0, maxChars)}\n\n[CODE.md truncated to ${maxChars} characters]`,
+        truncated: true
+    };
+}
+async function isReadable(path) {
+    try {
+        await (0, promises_1.access)(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function findCodeMdCandidates(startDir) {
+    const candidates = [];
+    let current = (0, node_path_1.resolve)(startDir);
+    for (;;) {
+        candidates.push((0, node_path_1.join)(current, CODE_MD_FILENAME));
+        const parent = (0, node_path_1.dirname)(current);
+        if (parent === current) {
+            break;
+        }
+        current = parent;
+    }
+    return candidates;
+}
+async function loadCodeContext(startDir = process.cwd()) {
+    const candidates = findCodeMdCandidates(startDir);
+    for (const candidate of candidates) {
+        if (!(await isReadable(candidate))) {
+            continue;
+        }
+        try {
+            const raw = await (0, promises_1.readFile)(candidate, "utf8");
+            const trimmed = raw.trim();
+            if (trimmed.length === 0) {
+                continue;
+            }
+            const truncated = truncateContent(trimmed, MAX_CODE_MD_CHARS);
+            return {
+                path: candidate,
+                content: truncated.content,
+                truncated: truncated.truncated
+            };
+        }
+        catch {
+            // continue to parent candidate
+        }
+    }
+    return null;
+}
+function toCodeContextSystemMessage(context) {
+    return [`Project context from CODE.md (${context.path}):`, "", context.content].join("\n");
+}

package/dist/colors.js

@@ -0,0 +1,204 @@
+"use strict";
+/** Color palette and gradient utilities for ANSI truecolor output. */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DIM_GRAY = exports.SUCCESS_GREEN = exports.WARNING_YELLOW = exports.ERROR_RED = exports.VT_GREEN = exports.INPUT_PINK = exports.DARK_BLUE = exports.GRADIENT_BLUE = exports.GRADIENT_YELLOW = exports.GRADIENT_PINK = void 0;
+exports.parseHex = parseHex;
+exports.toHex = toHex;
+exports.interpolateColor = interpolateColor;
+exports.stripAnsi = stripAnsi;
+exports.colorChar = colorChar;
+exports.colorText = colorText;
+exports.bgColorText = bgColorText;
+exports.horizontalGradient = horizontalGradient;
+exports.horizontalGradientAtOffset = horizontalGradientAtOffset;
+exports.horizontalGradientBackground = horizontalGradientBackground;
+exports.diagonalGradient = diagonalGradient;
+exports.rowMajorGradient = rowMajorGradient;
+// --- Palette constants ---
+exports.GRADIENT_PINK = { r: 0xff, g: 0x14, b: 0x93 };
+exports.GRADIENT_YELLOW = { r: 0xff, g: 0xe1, b: 0x35 };
+exports.GRADIENT_BLUE = { r: 0x89, g: 0xcf, b: 0xf0 };
+exports.DARK_BLUE = { r: 0x00, g: 0x66, b: 0xcc };
+exports.INPUT_PINK = { r: 0xff, g: 0xcc, b: 0xff };
+exports.VT_GREEN = { r: 0x00, g: 0xff, b: 0x00 };
+exports.ERROR_RED = { r: 0xff, g: 0x44, b: 0x44 };
+exports.WARNING_YELLOW = { r: 0xff, g: 0xcc, b: 0x00 };
+exports.SUCCESS_GREEN = { r: 0x44, g: 0xff, b: 0x44 };
+exports.DIM_GRAY = { r: 0x88, g: 0x88, b: 0x88 };
+const ANSI_RESET_FOREGROUND = "\u001b[39m";
+const ANSI_RESET_ALL = "\u001b[0m";
+// --- Color utilities ---
+function parseHex(hex) {
+    const cleaned = hex.replace(/^#/, "");
+    return {
+        r: parseInt(cleaned.slice(0, 2), 16),
+        g: parseInt(cleaned.slice(2, 4), 16),
+        b: parseInt(cleaned.slice(4, 6), 16)
+    };
+}
+function toHex(color) {
+    const r = Math.round(Math.max(0, Math.min(255, color.r)));
+    const g = Math.round(Math.max(0, Math.min(255, color.g)));
+    const b = Math.round(Math.max(0, Math.min(255, color.b)));
+    return `#${r.toString(16).padStart(2, "0")}${g.toString(16).padStart(2, "0")}${b.toString(16).padStart(2, "0")}`;
+}
+function interpolateColor(start, end, t) {
+    const clamped = Math.max(0, Math.min(1, t));
+    return {
+        r: start.r + (end.r - start.r) * clamped,
+        g: start.g + (end.g - start.g) * clamped,
+        b: start.b + (end.b - start.b) * clamped
+    };
+}
+function toAnsiColor(color) {
+    const r = Math.round(Math.max(0, Math.min(255, color.r)));
+    const g = Math.round(Math.max(0, Math.min(255, color.g)));
+    const b = Math.round(Math.max(0, Math.min(255, color.b)));
+    return `\u001b[38;2;${r};${g};${b}m`;
+}
+function toAnsiBackground(color) {
+    const r = Math.round(Math.max(0, Math.min(255, color.r)));
+    const g = Math.round(Math.max(0, Math.min(255, color.g)));
+    const b = Math.round(Math.max(0, Math.min(255, color.b)));
+    return `\u001b[48;2;${r};${g};${b}m`;
+}
+function stripAnsi(text) {
+    let output = "";
+    for (let i = 0; i < text.length; i++) {
+        if (text[i] === "\u001b" && text[i + 1] === "[") {
+            i += 2;
+            while (i < text.length && text[i] !== "m") {
+                i += 1;
+            }
+            continue;
+        }
+        output += text[i] ?? "";
+    }
+    return output;
+}
+/** Wrap a single character with ANSI truecolor sequence. */
+function colorChar(char, color) {
+    return `${toAnsiColor(color)}${char}`;
+}
+/** Apply a solid color to an entire string using ANSI truecolor. */
+function colorText(text, color) {
+    if (text.length === 0)
+        return "";
+    return `${toAnsiColor(color)}${text}${ANSI_RESET_FOREGROUND}`;
+}
+/** Apply background (+ optional foreground) color to a string. */
+function bgColorText(text, bgColor, fgColor) {
+    if (text.length === 0)
+        return "";
+    const fg = fgColor ? toAnsiColor(fgColor) : "";
+    return `${toAnsiBackground(bgColor)}${fg}${text}${ANSI_RESET_ALL}`;
+}
+/**
+ * Apply a horizontal gradient across a string.
+ * Each visible character gets its own color interpolated between start and end.
+ */
+function horizontalGradient(text, startColor, endColor) {
+    const chars = Array.from(text);
+    if (chars.length === 0)
+        return "";
+    if (chars.length === 1) {
+        return `${colorChar(chars[0] ?? "", startColor)}${ANSI_RESET_FOREGROUND}`;
+    }
+    const gradientChars = [];
+    for (let i = 0; i < chars.length; i++) {
+        const t = i / (chars.length - 1);
+        const color = interpolateColor(startColor, endColor, t);
+        gradientChars.push(colorChar(chars[i] ?? "", color));
+    }
+    gradientChars.push(ANSI_RESET_FOREGROUND);
+    return gradientChars.join("");
+}
+/**
+ * Apply a horizontal gradient to a string using an absolute offset in a larger line.
+ * Useful when rendering segmented strings that should share one continuous gradient.
+ */
+function horizontalGradientAtOffset(text, startColor, endColor, offset, totalWidth) {
+    const chars = Array.from(text);
+    if (chars.length === 0)
+        return "";
+    const safeTotalWidth = Math.max(1, totalWidth);
+    const denominator = Math.max(1, safeTotalWidth - 1);
+    const baseOffset = Math.max(0, offset);
+    const gradientChars = [];
+    for (let i = 0; i < chars.length; i++) {
+        const t = Math.max(0, Math.min(1, (baseOffset + i) / denominator));
+        const color = interpolateColor(startColor, endColor, t);
+        gradientChars.push(colorChar(chars[i] ?? "", color));
+    }
+    gradientChars.push(ANSI_RESET_FOREGROUND);
+    return gradientChars.join("");
+}
+/** Apply a left-to-right background gradient across a string. */
+function horizontalGradientBackground(text, startColor, endColor, fgColor) {
+    const chars = Array.from(text);
+    if (chars.length === 0)
+        return "";
+    const fg = fgColor ? toAnsiColor(fgColor) : "";
+    if (chars.length === 1) {
+        return `${toAnsiBackground(startColor)}${fg}${chars[0] ?? ""}${ANSI_RESET_ALL}`;
+    }
+    const gradientChars = [];
+    for (let i = 0; i < chars.length; i++) {
+        const t = i / (chars.length - 1);
+        const color = interpolateColor(startColor, endColor, t);
+        gradientChars.push(`${toAnsiBackground(color)}${fg}${chars[i] ?? ""}`);
+    }
+    gradientChars.push(ANSI_RESET_ALL);
+    return gradientChars.join("");
+}
+/**
+ * Apply a diagonal gradient across multiple lines.
+ * Each character's color is based on (row + col) / (totalRows + totalCols).
+ */
+function diagonalGradient(lines, startColor, endColor) {
+    if (lines.length === 0)
+        return [];
+    const splitLines = lines.map((line) => Array.from(line));
+    const maxLen = Math.max(...splitLines.map((lineChars) => lineChars.length));
+    if (maxLen === 0)
+        return lines.map(() => "");
+    const totalSteps = lines.length - 1 + maxLen - 1;
+    return splitLines.map((lineChars, row) => {
+        if (lineChars.length === 0)
+            return "";
+        const gradientChars = [];
+        for (let col = 0; col < lineChars.length; col++) {
+            const t = totalSteps > 0 ? (row + col) / totalSteps : 0;
+            const color = interpolateColor(startColor, endColor, t);
+            gradientChars.push(colorChar(lineChars[col] ?? "", color));
+        }
+        gradientChars.push(ANSI_RESET_FOREGROUND);
+        return gradientChars.join("");
+    });
+}
+/**
+ * Apply a multiline gradient by scanning cells row-by-row.
+ * Progress advances left-to-right per row, then continues on the next row.
+ */
+function rowMajorGradient(lines, startColor, endColor) {
+    if (lines.length === 0)
+        return [];
+    const splitLines = lines.map((line) => Array.from(line));
+    const maxLen = Math.max(...splitLines.map((lineChars) => lineChars.length));
+    if (maxLen === 0)
+        return lines.map(() => "");
+    const totalCells = lines.length * maxLen;
+    return splitLines.map((lineChars, row) => {
+        if (lineChars.length === 0)
+            return "";
+        const gradientChars = [];
+        for (let col = 0; col < lineChars.length; col++) {
+            const cellIndex = row * maxLen + col;
+            const t = totalCells > 1 ? cellIndex / (totalCells - 1) : 0;
+            const color = interpolateColor(startColor, endColor, t);
+            gradientChars.push(colorChar(lineChars[col] ?? "", color));
+        }
+        gradientChars.push(ANSI_RESET_FOREGROUND);
+        return gradientChars.join("");
+    });
+}

package/dist/command-catalog.js

@@ -0,0 +1,242 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadCommandCatalog = loadCommandCatalog;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const GENERIC_DESCRIPTIONS = new Set(["Tool command", "Markdown skill", "Command"]);
+const RESTORED_COMMAND_DEFAULTS = [
+    { name: "backend", description: "Switch AI backends (llamacpp, claude)", kind: "builtin" },
+    { name: "clear", description: "Clear context and start a new session", kind: "builtin" },
+    { name: "dl", description: "Alias for /download", kind: "builtin" },
+    { name: "download", description: "Open the interactive model downloader", kind: "builtin" },
+    { name: "exit", description: "Exit Yips", kind: "builtin" },
+    { name: "fetch", description: "Retrieve and display content from a URL", kind: "tool" },
+    { name: "grab", description: "Read a file's content into context", kind: "tool" },
+    { name: "help", description: "Show available commands and tips", kind: "skill" },
+    { name: "memorize", description: "Save a fact to long-term memory", kind: "tool" },
+    { name: "model", description: "Open the Model Manager or switch to a specific model", kind: "builtin" },
+    { name: "new", description: "Start a new session", kind: "builtin" },
+    { name: "nick", description: "Set a custom nickname for a model", kind: "builtin" },
+    { name: "quit", description: "Exit Yips", kind: "builtin" },
+    { name: "search", description: "Search the web (DuckDuckGo)", kind: "tool" },
+    { name: "sessions", description: "Interactively select and load a session", kind: "builtin" },
+    { name: "stream", description: "Toggle streaming responses", kind: "builtin" },
+    { name: "tokens", description: "Show or set token counter mode and max", kind: "builtin" },
+    { name: "verbose", description: "Toggle verbose output", kind: "builtin" },
+    { name: "vt", description: "Toggle the Virtual Terminal", kind: "tool" }
+];
+function normalizeCommandName(name) {
+    return name.trim().replace(/^\/+/, "").toLowerCase();
+}
+function isGenericDescription(description) {
+    const trimmed = description.trim();
+    if (trimmed.length === 0) {
+        return true;
+    }
+    return GENERIC_DESCRIPTIONS.has(trimmed);
+}
+function normalizeDescription(description) {
+    const trimmed = description.trim();
+    return trimmed.length > 0 ? trimmed : "Command";
+}
+function sortedDirectoryEntries(path) {
+    return (0, node_fs_1.readdirSync)(path, { withFileTypes: true })
+        .filter((entry) => entry.isDirectory())
+        .map((entry) => entry.name)
+        .sort((left, right) => left.localeCompare(right));
+}
+function fileNames(path) {
+    return (0, node_fs_1.readdirSync)(path, { withFileTypes: true })
+        .filter((entry) => entry.isFile())
+        .map((entry) => entry.name)
+        .sort((left, right) => left.localeCompare(right));
+}
+function fileBasename(filename) {
+    const dotIndex = filename.lastIndexOf(".");
+    return dotIndex >= 0 ? filename.slice(0, dotIndex) : filename;
+}
+function pickCommandFile(commandDir, commandDirName, extension) {
+    if (!(0, node_fs_1.existsSync)(commandDir)) {
+        return null;
+    }
+    const names = fileNames(commandDir);
+    const extensionLower = extension.toLowerCase();
+    const targetBase = commandDirName.toLowerCase();
+    const exact = names.find((name) => {
+        if (!name.toLowerCase().endsWith(extensionLower)) {
+            return false;
+        }
+        return fileBasename(name).toLowerCase() === targetBase;
+    });
+    if (exact) {
+        return (0, node_path_1.join)(commandDir, exact);
+    }
+    const fallback = names.find((name) => name.toLowerCase().endsWith(extensionLower));
+    return fallback ? (0, node_path_1.join)(commandDir, fallback) : null;
+}
+function toNonEmptyTrimmedLines(text) {
+    return text
+        .split(/\r?\n/u)
+        .map((line) => line.trim())
+        .filter((line) => line.length > 0);
+}
+function descriptionFromLines(lines) {
+    for (const line of lines) {
+        if (/^description\s*:/iu.test(line)) {
+            const extracted = line.replace(/^description\s*:\s*/iu, "").trim();
+            if (extracted.length > 0) {
+                return extracted;
+            }
+        }
+    }
+    const first = lines[0];
+    if (!first) {
+        return null;
+    }
+    const split = first.split(" - ");
+    if (split.length > 1) {
+        const remainder = split.slice(1).join(" - ").trim();
+        if (remainder.length > 0) {
+            return remainder;
+        }
+    }
+    return first;
+}
+function extractPythonDescription(contents) {
+    const docstringMatch = contents.match(/^\s*(?:#.*\r?\n|\s)*(?:"""([\s\S]*?)"""|'''([\s\S]*?)''')/u);
+    const docstring = docstringMatch?.[1] ?? docstringMatch?.[2];
+    if (!docstring) {
+        return null;
+    }
+    return descriptionFromLines(toNonEmptyTrimmedLines(docstring));
+}
+function extractMarkdownDescription(contents) {
+    const lines = toNonEmptyTrimmedLines(contents);
+    if (lines.length === 0) {
+        return null;
+    }
+    const first = lines[0];
+    if (!first) {
+        return null;
+    }
+    if (!first.startsWith("#")) {
+        return first;
+    }
+    for (const line of lines.slice(1)) {
+        if (line.startsWith("#") || line.startsWith("!") || line.startsWith("```")) {
+            continue;
+        }
+        return line;
+    }
+    const heading = first.replace(/^#+\s*/u, "").trim();
+    return heading.length > 0 ? heading : null;
+}
+function readTextSafely(path) {
+    try {
+        return (0, node_fs_1.readFileSync)(path, "utf8");
+    }
+    catch {
+        return null;
+    }
+}
+function discoverCommands(parentDir, parentKind) {
+    if (!(0, node_fs_1.existsSync)(parentDir)) {
+        return [];
+    }
+    const discovered = [];
+    for (const commandDirName of sortedDirectoryEntries(parentDir)) {
+        const commandName = normalizeCommandName(commandDirName);
+        if (commandName.length === 0) {
+            continue;
+        }
+        const commandDir = (0, node_path_1.join)(parentDir, commandDirName);
+        const pythonPath = pickCommandFile(commandDir, commandDirName, ".py");
+        const markdownPath = pickCommandFile(commandDir, commandDirName, ".md");
+        let kind = parentKind;
+        let description = null;
+        let priority = 0;
+        if (pythonPath) {
+            const contents = readTextSafely(pythonPath);
+            if (contents) {
+                description = extractPythonDescription(contents);
+            }
+            kind = "tool";
+            priority = description ? 2 : 0;
+        }
+        else if (markdownPath) {
+            const contents = readTextSafely(markdownPath);
+            if (contents) {
+                description = extractMarkdownDescription(contents);
+            }
+            kind = "skill";
+            priority = description ? 2 : 0;
+        }
+        discovered.push({
+            name: commandName,
+            description: normalizeDescription(description ?? "Command"),
+            kind,
+            implemented: false,
+            priority
+        });
+    }
+    return discovered;
+}
+function upsertCatalogEntry(catalog, candidate) {
+    const normalizedName = normalizeCommandName(candidate.name);
+    if (normalizedName.length === 0) {
+        return;
+    }
+    const normalizedCandidate = {
+        ...candidate,
+        name: normalizedName,
+        description: normalizeDescription(candidate.description)
+    };
+    const existing = catalog.get(normalizedName);
+    if (!existing) {
+        catalog.set(normalizedName, normalizedCandidate);
+        return;
+    }
+    const candidateGeneric = isGenericDescription(normalizedCandidate.description);
+    const existingGeneric = isGenericDescription(existing.description);
+    const shouldReplace = normalizedCandidate.priority > existing.priority ||
+        (normalizedCandidate.priority === existing.priority && !candidateGeneric && existingGeneric);
+    if (shouldReplace) {
+        catalog.set(normalizedName, {
+            ...normalizedCandidate,
+            implemented: existing.implemented || normalizedCandidate.implemented
+        });
+        return;
+    }
+    catalog.set(normalizedName, {
+        ...existing,
+        implemented: existing.implemented || normalizedCandidate.implemented
+    });
+}
+function loadCommandCatalog(options = {}) {
+    const projectRoot = options.projectRoot ?? process.cwd();
+    const catalog = new Map();
+    for (const descriptor of RESTORED_COMMAND_DEFAULTS) {
+        upsertCatalogEntry(catalog, {
+            ...descriptor,
+            name: normalizeCommandName(descriptor.name),
+            implemented: false,
+            priority: 1
+        });
+    }
+    const toolsDir = (0, node_path_1.join)(projectRoot, "commands", "tools");
+    const skillsDir = (0, node_path_1.join)(projectRoot, "commands", "skills");
+    for (const descriptor of discoverCommands(toolsDir, "tool")) {
+        upsertCatalogEntry(catalog, descriptor);
+    }
+    for (const descriptor of discoverCommands(skillsDir, "skill")) {
+        upsertCatalogEntry(catalog, descriptor);
+    }
+    return [...catalog.values()]
+        .sort((left, right) => left.name.localeCompare(right.name))
+        .map((descriptor) => ({
+        name: descriptor.name,
+        description: descriptor.description,
+        kind: descriptor.kind,
+        implemented: descriptor.implemented
+    }));
+}