skillex 0.2.5 → 0.3.1

package/CHANGELOG.md

@@ -7,6 +7,26 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.3.1] - 2026-04-08
+
+### Fixed
+- Web UI: translate all remaining Portuguese strings to English (`No sources.`, `Sync history`, `Error`/`Done` toasts, `Visible`, `Catalog`, `Skill detail`, `Version`, `Installed`/`Yes`/`No`, `Compatibility`, `Instructions`, `Instructions unavailable`)
+- Web UI dark theme: lift background and surface colors from near-black to a more comfortable dark grey; raise `--text-muted` and `--text-dim` contrast for better readability
+
+## [0.3.0] - 2026-04-08
+
+### Added
+- `skillex ui` now launches a local HTTP server serving the interactive Vue/Vite SPA instead of a terminal TUI
+- New Vue 3 + Vite single-page application under `ui/` with catalog browser, skill detail pages, and router-based navigation
+- `src/web-ui.ts`: self-contained HTTP server with `/api/skills` and `/api/catalog` JSON endpoints and graceful shutdown
+- `src/markdown.ts`: shared Markdown-to-HTML renderer used by the web API
+- Terminal browser detection: `skillex ui` opens the local server in the platform default browser or a detected terminal viewer
+
+### Changed
+- `src/cli.ts`: `ui` command now delegates to the local web-UI server
+- `src/ui.ts`: updated to detect and delegate to terminal browser when available
+- Build: `npm run build` now runs `build:ui` (Vite) followed by `tsc`
+
 ## [0.2.5] - 2026-04-08
 
 ### Added

package/README.md

@@ -71,6 +71,23 @@ npm install -D skillex
 npx skillex <command>
 ```
 
+### Local Web UI development
+
+When working on the repository itself, the browser UI is a standalone Vue 3 + Vite frontend under [`ui/`](/Users/lgili/Documents/01%20-%20Codes/01%20-%20Github/Skill/ui). The CLI serves the built assets from [`dist-ui/`](/Users/lgili/Documents/01%20-%20Codes/01%20-%20Github/Skill/dist-ui) and keeps all install/remove/update/sync logic in the local TypeScript backend.
+
+```bash
+npm install
+npm run build:ui
+npm run build
+node ./bin/skillex.js ui
+```
+
+For frontend-only iteration:
+
+```bash
+npm run dev:ui
+```
+
 ---
 
 ## Commands
@@ -259,12 +276,25 @@ skillex run git-master:cleanup --yes   # skip confirmation
 
 ---
 
+### Default terminal browser
+
+Running `skillex` with no subcommand now opens the interactive terminal browser by default.
+
+```bash
+skillex
+skillex browse
+skillex tui
+```
+
+---
+
 ### `ui`
 
-Open an interactive terminal UI to browse and install skills.
+Open the local Web UI in your browser.
 
 ```bash
 skillex ui
+skillex ui --global
 ```
 
 ---

package/dist/cli.d.ts

@@ -5,3 +5,4 @@
  * @throws {CliError} When the command or flag values are invalid.
  */
 export declare function main(argv: string[]): Promise<void>;
+export declare function resolveCommandRoute(command: string | undefined): string;

package/dist/cli.js

@@ -1,12 +1,13 @@
 import * as path from "node:path";
 import { listAdapters } from "./adapters.js";
-import { computeCatalogCacheKey, loadCatalog, readCatalogCache, searchCatalogSkills, } from "./catalog.js";
+import { computeCatalogCacheKey, readCatalogCache, searchCatalogSkills, } from "./catalog.js";
 import { DEFAULT_INSTALL_SCOPE, getScopedStatePaths } from "./config.js";
 import { addProjectSource, getInstalledSkills, initProject, installSkills, listProjectSources, loadProjectCatalogs, removeProjectSource, removeSkills, resolveProjectSource, syncInstalledSkills, updateInstalledSkills, } from "./install.js";
 import * as output from "./output.js";
 import { setVerbose } from "./output.js";
 import { parseSkillCommandReference, runSkillScript } from "./runner.js";
 import { runInteractiveUi } from "./ui.js";
+import { startWebUiServer } from "./web-ui.js";
 import { CliError } from "./types.js";
 import { VALID_CONFIG_KEYS, readUserConfig, writeUserConfig } from "./user-config.js";
 // ---------------------------------------------------------------------------
@@ -124,7 +125,9 @@ Options:
 
 Example:
   skillex run git-master:cleanup --yes`,
-    ui: `Usage: skillex ui [options]
+    browse: `Usage: skillex browse [options]
+         skillex tui [options]
+         skillex [options]
 
 Open the interactive terminal browser to browse and install skills.
 
@@ -133,7 +136,21 @@ Options:
   --no-cache            Bypass local catalog cache
 
 Example:
-  skillex ui`,
+  skillex
+  skillex browse`,
+    ui: `Usage: skillex ui [options]
+
+Open the local Web UI in your browser.
+
+Options:
+  --repo <owner/repo>   GitHub repository
+  --scope <scope>       local or global (default: local)
+  --global              Shortcut for --scope global
+  --no-cache            Bypass local catalog cache
+
+Example:
+  skillex ui
+  skillex ui --global`,
     status: `Usage: skillex status [options]
 
 Show the installation status of the selected scope.
@@ -206,9 +223,14 @@ export async function main(argv) {
     if (userConfig.githubToken && !process.env.GITHUB_TOKEN) {
         process.env.GITHUB_TOKEN = userConfig.githubToken;
     }
+    const resolvedCommand = resolveCommandRoute(command);
+    if (flags.help === true && !command) {
+        printHelp();
+        return;
+    }
     // Per-command --help
-    if (flags.help === true && command && command !== "help") {
-        const helpText = COMMAND_HELP[command];
+    if (flags.help === true && resolvedCommand && resolvedCommand !== "help") {
+        const helpText = COMMAND_HELP[resolvedCommand];
         if (helpText) {
             output.info(helpText);
         }
@@ -217,13 +239,13 @@ export async function main(argv) {
         }
         return;
     }
-    // Resolve command aliases
-    const resolvedCommand = resolveAlias(command);
     switch (resolvedCommand) {
         case "help":
-        case undefined:
             printHelp();
             return;
+        case "browse":
+            await handleBrowse(flags, userConfig);
+            return;
         case "init":
             await handleInit(flags, userConfig);
             return;
@@ -249,7 +271,7 @@ export async function main(argv) {
             await handleRun(positionals, flags, userConfig);
             return;
         case "ui":
-            await handleUi(flags, userConfig);
+            await handleWebUi(flags, userConfig);
             return;
         case "status":
             await handleStatus(flags, userConfig);
@@ -439,12 +461,11 @@ async function handleRun(positionals, flags, userConfig) {
         process.exitCode = exitCode;
     }
 }
-async function handleUi(flags, userConfig) {
+async function handleBrowse(flags, userConfig) {
     const options = commonOptions(flags, userConfig);
     const state = await getInstalledSkills(options);
-    const source = await resolveProjectSource(options);
     output.statusLine("Fetching catalog...");
-    const catalog = await loadCatalog({ ...source, ...cacheOptions(options) });
+    const catalog = await loadProjectCatalogs({ ...options, ...cacheOptions(options) });
     output.clearStatus();
     if (catalog.skills.length === 0) {
         output.info("No skills available in the catalog.");
@@ -477,6 +498,15 @@ async function handleUi(flags, userConfig) {
     }
     printAutoSyncResult(installResult?.autoSync ?? removeResult?.autoSync ?? null);
 }
+async function handleWebUi(flags, userConfig) {
+    const options = commonOptions(flags, userConfig);
+    const session = await startWebUiServer(options);
+    output.success(`Skillex Web UI running at ${session.url}`);
+    if (!session.opened) {
+        output.warn("Could not open the browser automatically. Open the URL above manually.");
+    }
+    output.info("Press Ctrl+C to stop the local server.");
+}
 async function handleStatus(flags, userConfig) {
     const options = commonOptions(flags, userConfig);
     const state = await getInstalledSkills(options);
@@ -737,13 +767,17 @@ async function handleConfig(positionals, flags) {
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
-function resolveAlias(command) {
+export function resolveCommandRoute(command) {
     const ALIASES = {
         ls: "list",
         rm: "remove",
         uninstall: "remove",
+        tui: "browse",
     };
-    return command !== undefined ? (ALIASES[command] ?? command) : undefined;
+    if (command === undefined) {
+        return "browse";
+    }
+    return ALIASES[command] ?? command;
 }
 function commonOptions(flags, userConfig = {}) {
     const options = {
@@ -861,6 +895,7 @@ function printHelp() {
     output.info(`skillex — AI agent skill manager
 
 Commands:
+  skillex                                open the terminal browser
   skillex init [--repo owner/repo] [--ref main]
   skillex list [--json]
   skillex search [query] [--compatibility claude] [--tag git]
@@ -868,10 +903,11 @@ Commands:
   skillex install --all
   skillex update [skill-id...]
   skillex remove <skill-id...>           aliases: rm, uninstall
+  skillex browse                         aliases: tui
   skillex source <add|remove|list> [...]
   skillex sync [--adapter id] [--dry-run] [--mode copy]
   skillex run <skill-id:command> [--yes] [--timeout 30]
-  skillex ui
+  skillex ui                             open local Web UI
   skillex status [--json]
   skillex doctor [--json]
   skillex config set <key> <value>

package/dist/markdown.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Renders a safe HTML representation for common Markdown constructs used by skills.
+ *
+ * @param markdown - Raw markdown source.
+ * @returns Sanitized HTML string.
+ */
+export declare function renderMarkdownToHtml(markdown: string): string;

package/dist/markdown.js

@@ -0,0 +1,193 @@
+function escapeHtml(value) {
+    return value
+        .replaceAll("&", "&")
+        .replaceAll("<", "&lt;")
+        .replaceAll(">", "&gt;")
+        .replaceAll('"', "&quot;")
+        .replaceAll("'", "&#39;");
+}
+function renderInlineMarkdown(value) {
+    let html = escapeHtml(value);
+    html = html.replace(/\[([^\]]+)\]\((https?:\/\/[^)\s]+)\)/g, (_match, label, url) => {
+        const safeLabel = escapeHtml(label);
+        const safeUrl = escapeHtml(url);
+        return `<a href="${safeUrl}" target="_blank" rel="noreferrer noopener">${safeLabel}</a>`;
+    });
+    html = html.replace(/`([^`]+)`/g, (_match, code) => `<code>${escapeHtml(code)}</code>`);
+    html = html.replace(/\*\*([^*]+)\*\*/g, "<strong>$1</strong>");
+    html = html.replace(/\*([^*]+)\*/g, "<em>$1</em>");
+    return html;
+}
+function flushParagraph(paragraph, html) {
+    if (paragraph.length === 0) {
+        return;
+    }
+    html.push(`<p>${paragraph.map((line) => renderInlineMarkdown(line)).join("<br>")}</p>`);
+    paragraph.length = 0;
+}
+function closeList(currentList, html) {
+    if (currentList.type) {
+        html.push(`</${currentList.type}>`);
+        currentList.type = null;
+    }
+}
+function isTableSeparator(line) {
+    const trimmed = line.trim();
+    if (!trimmed.startsWith("|") || !trimmed.endsWith("|")) {
+        return false;
+    }
+    return trimmed
+        .slice(1, -1)
+        .split("|")
+        .every((cell) => /^:?-{3,}:?$/.test(cell.trim()));
+}
+function splitTableRow(line) {
+    return line
+        .trim()
+        .slice(1, -1)
+        .split("|")
+        .map((cell) => renderInlineMarkdown(cell.trim()));
+}
+function consumeTable(lines, startIndex) {
+    const headerLine = lines[startIndex]?.trim();
+    const separatorLine = lines[startIndex + 1]?.trim();
+    if (!headerLine || !separatorLine || !headerLine.startsWith("|") || !headerLine.endsWith("|") || !isTableSeparator(separatorLine)) {
+        return null;
+    }
+    const headers = splitTableRow(headerLine);
+    const rows = [];
+    let index = startIndex + 2;
+    while (index < lines.length) {
+        const candidate = lines[index]?.trim();
+        if (!candidate || !candidate.startsWith("|") || !candidate.endsWith("|")) {
+            break;
+        }
+        rows.push(splitTableRow(candidate));
+        index += 1;
+    }
+    const html = [
+        "<div class=\"markdown-table-wrap\">",
+        "<table>",
+        "<thead>",
+        "<tr>",
+        ...headers.map((header) => `<th>${header}</th>`),
+        "</tr>",
+        "</thead>",
+        "<tbody>",
+        ...rows.map((row) => `<tr>${row.map((cell) => `<td>${cell}</td>`).join("")}</tr>`),
+        "</tbody>",
+        "</table>",
+        "</div>",
+    ].join("");
+    return {
+        html,
+        nextIndex: index - 1,
+    };
+}
+/**
+ * Renders a safe HTML representation for common Markdown constructs used by skills.
+ *
+ * @param markdown - Raw markdown source.
+ * @returns Sanitized HTML string.
+ */
+export function renderMarkdownToHtml(markdown) {
+    const lines = markdown.replace(/\r\n/g, "\n").split("\n");
+    const html = [];
+    const paragraph = [];
+    const currentList = { type: null };
+    let inCodeFence = false;
+    let codeFenceLanguage = "";
+    const codeFenceLines = [];
+    for (let index = 0; index < lines.length; index += 1) {
+        const line = lines[index] ?? "";
+        const trimmed = line.trim();
+        if (trimmed.startsWith("```")) {
+            flushParagraph(paragraph, html);
+            closeList(currentList, html);
+            if (inCodeFence) {
+                const languageClass = codeFenceLanguage ? ` class="language-${escapeHtml(codeFenceLanguage)}"` : "";
+                html.push(`<pre><code${languageClass}>${escapeHtml(codeFenceLines.join("\n"))}</code></pre>`);
+                codeFenceLines.length = 0;
+                codeFenceLanguage = "";
+                inCodeFence = false;
+            }
+            else {
+                inCodeFence = true;
+                codeFenceLanguage = trimmed.slice(3).trim();
+            }
+            continue;
+        }
+        if (inCodeFence) {
+            codeFenceLines.push(line);
+            continue;
+        }
+        const table = consumeTable(lines, index);
+        if (table) {
+            flushParagraph(paragraph, html);
+            closeList(currentList, html);
+            html.push(table.html);
+            index = table.nextIndex;
+            continue;
+        }
+        if (!trimmed) {
+            flushParagraph(paragraph, html);
+            closeList(currentList, html);
+            continue;
+        }
+        const headingMatch = trimmed.match(/^(#{1,6})\s+(.+)$/);
+        if (headingMatch) {
+            flushParagraph(paragraph, html);
+            closeList(currentList, html);
+            const level = headingMatch[1]?.length ?? 1;
+            html.push(`<h${level}>${renderInlineMarkdown(headingMatch[2] ?? "")}</h${level}>`);
+            continue;
+        }
+        const unorderedMatch = trimmed.match(/^[-*+]\s+(.+)$/);
+        if (unorderedMatch) {
+            flushParagraph(paragraph, html);
+            if (currentList.type !== "ul") {
+                closeList(currentList, html);
+                currentList.type = "ul";
+                html.push("<ul>");
+            }
+            html.push(`<li>${renderInlineMarkdown(unorderedMatch[1] ?? "")}</li>`);
+            continue;
+        }
+        const orderedMatch = trimmed.match(/^\d+\.\s+(.+)$/);
+        if (orderedMatch) {
+            flushParagraph(paragraph, html);
+            if (currentList.type !== "ol") {
+                closeList(currentList, html);
+                currentList.type = "ol";
+                html.push("<ol>");
+            }
+            html.push(`<li>${renderInlineMarkdown(orderedMatch[1] ?? "")}</li>`);
+            continue;
+        }
+        const quoteMatch = trimmed.match(/^>\s?(.*)$/);
+        if (quoteMatch) {
+            flushParagraph(paragraph, html);
+            closeList(currentList, html);
+            const quoteLines = [renderInlineMarkdown(quoteMatch[1] ?? "")];
+            while (index + 1 < lines.length) {
+                const next = lines[index + 1]?.trim() ?? "";
+                const nextQuote = next.match(/^>\s?(.*)$/);
+                if (!nextQuote) {
+                    break;
+                }
+                quoteLines.push(renderInlineMarkdown(nextQuote[1] ?? ""));
+                index += 1;
+            }
+            html.push(`<blockquote><p>${quoteLines.join("<br>")}</p></blockquote>`);
+            continue;
+        }
+        paragraph.push(trimmed);
+    }
+    if (inCodeFence) {
+        const languageClass = codeFenceLanguage ? ` class="language-${escapeHtml(codeFenceLanguage)}"` : "";
+        html.push(`<pre><code${languageClass}>${escapeHtml(codeFenceLines.join("\n"))}</code></pre>`);
+    }
+    flushParagraph(paragraph, html);
+    closeList(currentList, html);
+    return html.join("\n");
+}

package/dist/ui.d.ts

@@ -17,21 +17,26 @@ interface UiPrompts {
     }) => Promise<string[]>) | undefined;
 }
 /**
- * Filters catalog skills for the interactive UI using a case-insensitive text query.
+ * Filters catalog skills for the interactive terminal browser using a case-insensitive text query.
  *
  * @param skills - Catalog skills.
  * @param query - Search text.
  * @returns Filtered skills in their original order.
  */
-export declare function filterCatalogForUi(skills: SkillManifest[], query: string): SkillManifest[];
+export declare function filterCatalogForUi<T extends SkillManifest>(skills: T[], query: string): T[];
 /**
- * Runs the interactive terminal flow used by `skillex ui`.
+ * Runs the interactive terminal browser flow used by `skillex`, `skillex browse`, and `skillex tui`.
  *
  * @param options - UI state and optional prompt overrides.
  * @returns Selected, installable, and removable skill ids.
  */
-export declare function runInteractiveUi(options: {
-    skills: SkillManifest[];
+export declare function runInteractiveUi<T extends SkillManifest & {
+    source?: {
+        repo: string;
+        label?: string | undefined;
+    };
+}>(options: {
+    skills: T[];
     installedIds: string[];
     prompts?: UiPrompts | undefined;
 }): Promise<{

package/dist/ui.js

@@ -1,5 +1,5 @@
 /**
- * Filters catalog skills for the interactive UI using a case-insensitive text query.
+ * Filters catalog skills for the interactive terminal browser using a case-insensitive text query.
  *
  * @param skills - Catalog skills.
  * @param query - Search text.
@@ -16,7 +16,7 @@ export function filterCatalogForUi(skills, query) {
         .includes(normalized));
 }
 /**
- * Runs the interactive terminal flow used by `skillex ui`.
+ * Runs the interactive terminal browser flow used by `skillex`, `skillex browse`, and `skillex tui`.
  *
  * @param options - UI state and optional prompt overrides.
  * @returns Selected, installable, and removable skill ids.
@@ -39,9 +39,12 @@ export async function runInteractiveUi(options) {
             choices: filteredSkills.map((skill) => {
                 const tags = (skill.tags ?? []).slice(0, 4).join(", ");
                 const detail = tags || (skill.description ?? "").slice(0, 55);
+                const source = skill.source && (skill.source.label || skill.source.repo)
+                    ? `  ·  ${skill.source.label || skill.source.repo}`
+                    : "";
                 const label = detail
-                    ? `${skill.name}  (${skill.id})  ·  ${detail}`
-                    : `${skill.name}  (${skill.id})`;
+                    ? `${skill.name}  (${skill.id})  ·  ${detail}${source}`
+                    : `${skill.name}  (${skill.id})${source}`;
                 return {
                     name: label,
                     value: skill.id,

package/dist/web-ui.d.ts

@@ -0,0 +1,31 @@
+import { type IncomingMessage, type ServerResponse } from "node:http";
+import type { CatalogLoader, ProjectOptions, SkillDownloader, SourcedSkillManifest } from "./types.js";
+type BrowserOpener = (url: string) => Promise<void>;
+type SkillBodyLoader = (skill: SourcedSkillManifest, context: {
+    options: ProjectOptions;
+}) => Promise<string>;
+export interface WebUiServerOptions extends ProjectOptions {
+    host?: string | undefined;
+    port?: number | undefined;
+    autoOpen?: boolean | undefined;
+    openBrowser?: BrowserOpener | undefined;
+    catalogLoader?: CatalogLoader | undefined;
+    downloader?: SkillDownloader | undefined;
+    skillBodyLoader?: SkillBodyLoader | undefined;
+}
+export interface WebUiSession {
+    url: string;
+    opened: boolean;
+    close: () => Promise<void>;
+}
+/**
+ * Starts a loopback-only local Web UI server for Skillex and optionally opens the browser.
+ */
+export declare function startWebUiServer(options?: WebUiServerOptions): Promise<WebUiSession>;
+/**
+ * Creates the HTTP request handler used by the local Web UI server.
+ */
+export declare function createWebUiHandler(options: WebUiServerOptions & {
+    token: string;
+}): (request: IncomingMessage, response: ServerResponse) => Promise<void>;
+export {};