Skip to content

The open-source full-stack studio for Opus 5.5 motion video. Reverse engineering for any video. Code video with HTML: recreate, edit and render. BYOA + BYOK · Motion.md · Images, Video, Music & Voice.

feat(skills): GitHub-backed skill marketplace (#69)

steve wu145a40ebd796
diff --git a/next/src/app/api/marketplace/_lib/__tests__/host-guard.test.ts b/next/src/app/api/marketplace/_lib/__tests__/host-guard.test.ts
new file mode 100644
index 00000000..ba2ca7f4
--- /dev/null
+++ b/next/src/app/api/marketplace/_lib/__tests__/host-guard.test.ts
@@ -0,0 +1,72 @@
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { hostRejectedResponse, isHostAllowed } from "../host-guard";
+
+describe("isHostAllowed", () => {
+ const original = {
+ allowed: process.env.HTML_ANYTHING_ALLOWED_HOSTS,
+ any: process.env.HTML_ANYTHING_ALLOW_ANY_HOST,
+ };
+
+ beforeEach(() => {
+ delete process.env.HTML_ANYTHING_ALLOWED_HOSTS;
+ delete process.env.HTML_ANYTHING_ALLOW_ANY_HOST;
+ });
+
+ afterEach(() => {
+ if (original.allowed === undefined) delete process.env.HTML_ANYTHING_ALLOWED_HOSTS;
+ else process.env.HTML_ANYTHING_ALLOWED_HOSTS = original.allowed;
+ if (original.any === undefined) delete process.env.HTML_ANYTHING_ALLOW_ANY_HOST;
+ else process.env.HTML_ANYTHING_ALLOW_ANY_HOST = original.any;
+ });
+
+ function reqWithHost(host: string | null): Request {
+ // undici (fetch-spec) forbids the "host" request header; encode the host
+ // into the URL instead. The guard reads `req.headers.get('host')` first
+ // and falls back to `new URL(req.url).host`, which matches reality —
+ // browsers populate Host from the URL they dial.
+ const url = host === null ? "file:///no-url-host" : `http://${host}/api/marketplace/install`;
+ return new Request(url, { method: "POST" });
+ }
+
+ it("allows loopback IPv4 with a port", () => {
+ expect(isHostAllowed(reqWithHost("127.0.0.1:3000"))).toBe(true);
+ });
+
+ it("allows literal localhost", () => {
+ expect(isHostAllowed(reqWithHost("localhost"))).toBe(true);
+ });
+
+ it("allows IPv6 loopback in bracketed form", () => {
+ expect(isHostAllowed(reqWithHost("[::1]:3000"))).toBe(true);
+ });
+
+ it("rejects an attacker-controlled hostname (the DNS-rebinding case)", () => {
+ expect(isHostAllowed(reqWithHost("evil.example.com"))).toBe(false);
+ });
+
+ it("rejects a request with no Host header", () => {
+ expect(isHostAllowed(reqWithHost(null))).toBe(false);
+ });
+
+ it("allows a hostname listed in HTML_ANYTHING_ALLOWED_HOSTS", () => {
+ process.env.HTML_ANYTHING_ALLOWED_HOSTS = "ha.local, my-box";
+ expect(isHostAllowed(reqWithHost("ha.local:3000"))).toBe(true);
+ expect(isHostAllowed(reqWithHost("my-box"))).toBe(true);
+ expect(isHostAllowed(reqWithHost("other.host"))).toBe(false);
+ });
+
+ it("accepts any host when HTML_ANYTHING_ALLOW_ANY_HOST=1 (trusted-proxy mode)", () => {
+ process.env.HTML_ANYTHING_ALLOW_ANY_HOST = "1";
+ expect(isHostAllowed(reqWithHost("anything.com"))).toBe(true);
+ });
+});
+
+describe("hostRejectedResponse", () => {
+ it("returns a 403 JSON response with an actionable hint", async () => {
+ const res = hostRejectedResponse();
+ expect(res.status).toBe(403);
+ const body = (await res.json()) as { error: string; hint: string };
+ expect(body.error).toBe("host_not_allowed");
+ expect(body.hint).toContain("HTML_ANYTHING_ALLOWED_HOSTS");
+ });
+});
diff --git a/next/src/app/api/marketplace/_lib/host-guard.ts b/next/src/app/api/marketplace/_lib/host-guard.ts
new file mode 100644
index 00000000..3abd70dd
--- /dev/null
+++ b/next/src/app/api/marketplace/_lib/host-guard.ts
@@ -0,0 +1,78 @@
+/**
+ * Per-route Host-header guard for marketplace install/uninstall.
+ *
+ * Why this lives next to the marketplace routes rather than at the middleware
+ * layer: a sibling PR (security/api-host-validation) introduces a global
+ * `/api/*` middleware that covers every API route. Until that lands, the
+ * marketplace POST is a particularly attractive DNS-rebinding target — it
+ * downloads and writes arbitrary user-supplied GitHub repos to disk and
+ * registers them as installable skills. So we ship a local check here that:
+ * - mirrors the same default (loopback-only) and env knobs
+ * (`HTML_ANYTHING_ALLOWED_HOSTS`, `HTML_ANYTHING_ALLOW_ANY_HOST`),
+ * - is independent of the middleware so it works whichever PR lands first,
+ * - becomes a redundant no-op once the global middleware also runs.
+ *
+ * Once the global host-validation middleware merges, this module can be
+ * deleted and the routes can rely on the middleware alone.
+ */
+
+const LOOPBACK_HOSTS = new Set(["127.0.0.1", "localhost", "::1", "0.0.0.0"]);
+
+function stripPort(host: string): string {
+ const trimmed = host.trim().toLowerCase();
+ if (!trimmed) return "";
+ if (trimmed.startsWith("[")) {
+ const end = trimmed.indexOf("]");
+ if (end === -1) return trimmed;
+ return trimmed.slice(1, end);
+ }
+ const colon = trimmed.lastIndexOf(":");
+ if (colon === -1) return trimmed;
+ const tail = trimmed.slice(colon + 1);
+ return /^\d+$/.test(tail) ? trimmed.slice(0, colon) : trimmed;
+}
+
+function parseAllowlist(): Set<string> {
+ const raw = process.env.HTML_ANYTHING_ALLOWED_HOSTS;
+ if (!raw) return new Set();
+ return new Set(
+ raw
+ .split(",")
+ .map((s) => s.trim().toLowerCase())
+ .filter(Boolean),
+ );
+}
+
+export function isHostAllowed(req: Request): boolean {
+ if (process.env.HTML_ANYTHING_ALLOW_ANY_HOST === "1") return true;
+ // Prefer the Host header — that's what browsers send and what the dev-server
+ // populates over the wire. Fall back to `new URL(req.url).host` because
+ // fetch-spec-compliant `Request` constructors (undici, browsers) forbid
+ // setting Host explicitly, and tests have to rely on the URL.
+ const rawHost = req.headers.get("host") ?? safeUrlHost(req.url);
+ if (!rawHost) return false;
+ const host = stripPort(rawHost);
+ if (!host) return false;
+ if (LOOPBACK_HOSTS.has(host)) return true;
+ return parseAllowlist().has(host);
+}
+
+function safeUrlHost(url: string): string | null {
+ try {
+ return new URL(url).host;
+ } catch {
+ return null;
+ }
+}
+
+export function hostRejectedResponse(): Response {
+ return new Response(
+ JSON.stringify({
+ error: "host_not_allowed",
+ hint:
+ "marketplace install/uninstall only accepts loopback Host. " +
+ "Add the hostname to HTML_ANYTHING_ALLOWED_HOSTS or set HTML_ANYTHING_ALLOW_ANY_HOST=1 behind a trusted proxy.",
+ }),
+ { status: 403, headers: { "Content-Type": "application/json; charset=utf-8" } },
+ );
+}
diff --git a/next/src/app/api/marketplace/install/route.ts b/next/src/app/api/marketplace/install/route.ts
new file mode 100644
index 00000000..7375409f
--- /dev/null
+++ b/next/src/app/api/marketplace/install/route.ts
@@ -0,0 +1,32 @@
+import { NextResponse } from "next/server";
+import { installFromGitHub, InstallError } from "@/lib/skills/install";
+import { invalidateSkillsCache } from "@/lib/templates/loader";
+import { hostRejectedResponse, isHostAllowed } from "../_lib/host-guard";
+
+export const runtime = "nodejs";
+export const dynamic = "force-dynamic";
+
+export async function POST(req: Request) {
+ if (!isHostAllowed(req)) return hostRejectedResponse();
+ let body: unknown;
+ try {
+ body = await req.json();
+ } catch {
+ return NextResponse.json({ error: "invalid_json" }, { status: 400 });
+ }
+ const spec = (body as { source?: unknown } | null)?.source;
+ if (typeof spec !== "string" || !spec.trim()) {
+ return NextResponse.json({ error: "missing_source" }, { status: 400 });
+ }
+ try {
+ const result = await installFromGitHub(spec);
+ invalidateSkillsCache();
+ return NextResponse.json({ package: result.package });
+ } catch (err) {
+ if (err instanceof InstallError) {
+ return NextResponse.json({ error: err.code, message: err.message }, { status: 400 });
+ }
+ const message = err instanceof Error ? err.message : String(err);
+ return NextResponse.json({ error: "install_failed", message }, { status: 500 });
+ }
+}
diff --git a/next/src/app/api/marketplace/packages/[id]/route.ts b/next/src/app/api/marketplace/packages/[id]/route.ts
new file mode 100644
index 00000000..af1ff765
--- /dev/null
+++ b/next/src/app/api/marketplace/packages/[id]/route.ts
@@ -0,0 +1,23 @@
+import { NextResponse } from "next/server";
+import { uninstallPackage } from "@/lib/skills/install";
+import { invalidateSkillsCache } from "@/lib/templates/loader";
+import { hostRejectedResponse, isHostAllowed } from "../../_lib/host-guard";
+
+export const runtime = "nodejs";
+export const dynamic = "force-dynamic";
+
+type Ctx = { params: Promise<{ id: string }> };
+
+export async function DELETE(req: Request, ctx: Ctx) {
+ if (!isHostAllowed(req)) return hostRejectedResponse();
+ const { id } = await ctx.params;
+ if (!/^[a-z0-9._-]+__[a-z0-9._-]+$/i.test(id)) {
+ return NextResponse.json({ error: "invalid_id" }, { status: 400 });
+ }
+ const removed = await uninstallPackage(id);
+ if (!removed) {
+ return NextResponse.json({ error: "not_found" }, { status: 404 });
+ }
+ invalidateSkillsCache();
+ return NextResponse.json({ ok: true });
+}
diff --git a/next/src/app/api/marketplace/route.ts b/next/src/app/api/marketplace/route.ts
new file mode 100644
index 00000000..449dc5bd
--- /dev/null
+++ b/next/src/app/api/marketplace/route.ts
@@ -0,0 +1,21 @@
+import { NextResponse } from "next/server";
+import { listPackages } from "@/lib/skills/registry";
+import { hostRejectedResponse, isHostAllowed } from "./_lib/host-guard";
+
+export const runtime = "nodejs";
+export const dynamic = "force-dynamic";
+
+/**
+ * List every installed marketplace package.
+ *
+ * Gated behind the same Host guard as install/uninstall — even though this
+ * is read-only, returning installed packages to a DNS-rebinding origin
+ * would leak repo owners / names / refs from the user's local app to any
+ * site they visit. Once the global `/api/*` middleware (PR #61) lands, the
+ * per-route check here is redundant; until then it must cover the whole
+ * marketplace surface, not just the write endpoints.
+ */
+export async function GET(req: Request) {
+ if (!isHostAllowed(req)) return hostRejectedResponse();
+ return NextResponse.json({ packages: listPackages() });
+}
diff --git a/next/src/components/settings-modal.tsx b/next/src/components/settings-modal.tsx
index 7f064401..3abee9c6 100644
--- a/next/src/components/settings-modal.tsx
+++ b/next/src/components/settings-modal.tsx
@@ -9,14 +9,20 @@ import {
type Locale,
} from "@/lib/store";
import { useT, type DictKey } from "@/lib/i18n";
+import { refreshTemplates } from "@/lib/templates";
type Props = { onClose: () => void; initialSection?: SectionId };
-export type SectionId = "agent" | "deploy" | "language";
+export type SectionId = "agent" | "deploy" | "marketplace" | "language";
const SECTIONS: Array<{ id: SectionId; labelKey: DictKey; hintKey: DictKey }> = [
{ id: "agent", labelKey: "settings.section.agent.label", hintKey: "settings.section.agent.hint" },
{ id: "deploy", labelKey: "settings.section.deploy.label", hintKey: "settings.section.deploy.hint" },
+ {
+ id: "marketplace",
+ labelKey: "settings.section.marketplace.label",
+ hintKey: "settings.section.marketplace.hint",
+ },
{ id: "language", labelKey: "settings.section.language.label", hintKey: "settings.section.language.hint" },
];
@@ -125,6 +131,7 @@ export function SettingsModal({ onClose, initialSection = "agent" }: Props) {
<div className="flex-1 min-w-0 overflow-y-auto px-7 py-6">
{section === "agent" && <AgentSection />}
{section === "deploy" && <DeploySection />}
+ {section === "marketplace" && <MarketplaceSection />}
{section === "language" && <LanguageSection />}
</div>
</div>
@@ -759,3 +766,251 @@ function ComingSoonProvider() {
</div>
);
}
+
+type InstalledPackage = {
+ id: string;
+ source: { type: "github"; owner: string; repo: string; ref: string };
+ installedAt: string;
+ skills: string[];
+};
+
+function MarketplaceSection() {
+ const t = useT();
+ const [packages, setPackages] = useState<InstalledPackage[]>([]);
+ const [loading, setLoading] = useState(false);
+ const [source, setSource] = useState("");
+ const [installing, setInstalling] = useState(false);
+ const [err, setErr] = useState<string | null>(null);
+ const [info, setInfo] = useState<string | null>(null);
+
+ const load = async () => {
+ setLoading(true);
+ setErr(null);
+ try {
+ const res = await fetch("/api/marketplace", { cache: "no-store" });
+ if (!res.ok) throw new Error(`HTTP ${res.status}`);
+ const data = (await res.json()) as { packages: InstalledPackage[] };
+ setPackages(data.packages);
+ } catch (e) {
+ setErr(e instanceof Error ? e.message : String(e));
+ } finally {
+ setLoading(false);
+ }
+ };
+
+ useEffect(() => {
+ load();
+ }, []);
+
+ const onInstall = async () => {
+ const spec = source.trim();
+ if (!spec) return;
+ setInstalling(true);
+ setErr(null);
+ setInfo(null);
+ try {
+ const res = await fetch("/api/marketplace/install", {
+ method: "POST",
+ headers: { "content-type": "application/json" },
+ body: JSON.stringify({ source: spec }),
+ });
+ const data = (await res.json()) as
+ | { package: InstalledPackage }
+ | { error: string; message?: string };
+ if (!res.ok || !("package" in data)) {
+ const errMsg = "error" in data ? data.message ?? data.error : "install failed";
+ throw new Error(errMsg);
+ }
+ const pkg = data.package;
+ setSource("");
+ setInfo(
+ t("marketplace.installSucceeded", {
+ n: pkg.skills.length,
+ repo: `${pkg.source.owner}/${pkg.source.repo}`,
+ }),
+ );
+ // Drop the in-memory template registry cache AND push the fresh list
+ // to every mounted `useTemplates` consumer — the picker switches over
+ // immediately, no page reload. Failing here just means the picker
+ // keeps the previous list; the install itself already succeeded.
+ await refreshTemplates().catch(() => undefined);
+ await load();
+ } catch (e) {
+ setErr(e instanceof Error ? e.message : String(e));
+ } finally {
+ setInstalling(false);
+ }
+ };
+
+ const onUninstall = async (id: string) => {
+ setErr(null);
+ setInfo(null);
+ try {
+ const res = await fetch(`/api/marketplace/packages/${encodeURIComponent(id)}`, {
+ method: "DELETE",
+ });
+ if (!res.ok) {
+ const data = (await res.json().catch(() => ({}))) as { message?: string; error?: string };
+ throw new Error(data.message ?? data.error ?? `HTTP ${res.status}`);
+ }
+ setInfo(t("marketplace.uninstalled"));
+ // Push the post-uninstall list to mounted picker consumers so the
+ // removed skill disappears without waiting for a page reload.
+ await refreshTemplates().catch(() => undefined);
+ await load();
+ } catch (e) {
+ setErr(e instanceof Error ? e.message : String(e));
+ }
+ };
+
+ return (
+ <div>
+ <div className="flex items-center justify-between mb-4">
+ <div>
+ <h3 className="text-[17px] font-semibold text-[var(--ink)]">
+ {t("settings.marketplace.title")}
+ </h3>
+ <p className="mt-1 text-[12.5px] text-[var(--ink-mute)] leading-relaxed">
+ {t("settings.marketplace.subtitle")}
+ </p>
+ </div>
+ <button
+ onClick={load}
+ disabled={loading}
+ className="text-xs text-[var(--ink-faint)] hover:text-[var(--ink)] disabled:opacity-50 transition-colors shrink-0"
+ >
+ {loading ? t("welcome.scanning") : t("welcome.rescan")}
+ </button>
+ </div>
+
+ <div
+ className="mb-5 rounded-2xl p-4"
+ style={{ background: "var(--paper)", border: "1px solid var(--line-faint)" }}
+ >
+ <div className="mb-2 text-[11px] uppercase tracking-[0.18em] text-[var(--ink-faint)]">
+ {t("marketplace.installFromGithub")}
+ </div>
+ <div className="flex items-center gap-2">
+ <input
+ value={source}
+ onChange={(e) => setSource(e.target.value)}
+ onKeyDown={(e) => {
+ if (e.key === "Enter" && !installing) onInstall();
+ }}
+ placeholder={t("marketplace.placeholder")}
+ disabled={installing}
+ className="min-w-0 flex-1 rounded-lg px-3 py-2 font-mono text-[12px] outline-none"
+ style={{
+ background: "var(--surface)",
+ border: "1px solid var(--line)",
+ color: "var(--ink)",
+ }}
+ />
+ <button
+ onClick={onInstall}
+ disabled={installing || !source.trim()}
+ className="btn-primary disabled:opacity-50"
+ >
+ {installing ? t("marketplace.installing") : t("marketplace.install")}
+ </button>
+ </div>
+ <div className="mt-2 text-[11px] text-[var(--ink-faint)]">{t("marketplace.hint")}</div>
+ </div>
+
+ {err && (
+ <div
+ className="mb-3 rounded-xl px-4 py-3 text-sm"
+ style={{ background: "var(--coral-soft)", color: "var(--coral)" }}
+ >
+ {err}
+ </div>
+ )}
+ {info && (
+ <div
+ className="mb-3 rounded-xl px-4 py-3 text-sm"
+ style={{ background: "var(--paper)", color: "var(--ink-soft)", border: "1px solid var(--line-faint)" }}
+ >
+ {info}
+ </div>
+ )}
+
+ <div className="mb-2 flex items-center gap-2 text-[11px] uppercase tracking-[0.18em] text-[var(--ink-faint)]">
+ {t("marketplace.installed", { n: packages.length })}
+ </div>
+ {packages.length === 0 && !loading && (
+ <div
+ className="rounded-2xl border-2 border-dashed py-8 px-6 text-center"
+ style={{ borderColor: "var(--line)" }}
+ >
+ <div className="text-3xl mb-2">📦</div>
+ <p className="text-sm font-medium text-[var(--ink-soft)]">
+ {t("marketplace.empty.title")}
+ </p>
+ <p className="mt-2 text-xs text-[var(--ink-mute)]">{t("marketplace.empty.body")}</p>
+ </div>
+ )}
+ <div className="grid grid-cols-1 gap-2">
+ {packages.map((pkg) => (
+ <PackageCard key={pkg.id} pkg={pkg} onUninstall={() => onUninstall(pkg.id)} />
+ ))}
+ </div>
+ </div>
+ );
+}
+
+function PackageCard({ pkg, onUninstall }: { pkg: InstalledPackage; onUninstall: () => void }) {
+ const t = useT();
+ const repoUrl = `https://github.com/${pkg.source.owner}/${pkg.source.repo}`;
+ return (
+ <div
+ className="rounded-2xl p-4"
+ style={{ background: "var(--surface)", border: "1px solid var(--line-soft)" }}
+ >
+ <div className="flex items-start justify-between gap-3">
+ <div className="min-w-0 flex-1">
+ <div className="flex items-center gap-2 text-[14px] font-semibold text-[var(--ink)]">
+ <span className="truncate">
+ {pkg.source.owner}/{pkg.source.repo}
+ </span>
+ <span className="rounded-full px-2 py-0.5 font-mono text-[10px] text-[var(--ink-faint)]" style={{ background: "var(--paper)" }}>
+ {pkg.source.ref}
+ </span>
+ </div>
+ <div className="mt-1 flex flex-wrap items-center gap-x-3 gap-y-1 text-[11px] text-[var(--ink-faint)]">
+ <a
+ href={repoUrl}
+ target="_blank"
+ rel="noreferrer noopener"
+ className="hover:text-[var(--ink-soft)] underline-offset-2 hover:underline"
+ >
+ {repoUrl.replace(/^https?:\/\//, "")}
+ </a>
+ <span>·</span>
+ <span>{t("marketplace.skillCount", { n: pkg.skills.length })}</span>
+ <span>·</span>
+ <span>{new Date(pkg.installedAt).toLocaleDateString()}</span>
+ </div>
+ {pkg.skills.length > 0 && (
+ <div className="mt-2 flex flex-wrap gap-1">
+ {pkg.skills.map((s) => (
+ <span
+ key={s}
+ className="rounded-md px-2 py-0.5 font-mono text-[10.5px] text-[var(--ink-soft)]"
+ style={{ background: "var(--paper)", border: "1px solid var(--line-faint)" }}
+ >
+ {s}
+ </span>
+ ))}
+ </div>
+ )}
+ </div>
+ <button
+ onClick={onUninstall}
+ className="shrink-0 rounded-lg px-3 py-1.5 text-[12px] text-[var(--ink-mute)] hover:bg-[var(--paper)] hover:text-[var(--coral)] transition-colors"
+ >
+ {t("marketplace.uninstall")}
+ </button>
+ </div>
+ </div>
+ );
+}
diff --git a/next/src/lib/i18n.ts b/next/src/lib/i18n.ts
index 70ba0b9d..7b0036ee 100644
--- a/next/src/lib/i18n.ts
+++ b/next/src/lib/i18n.ts
@@ -137,6 +137,24 @@ export interface Dict {
"deploy.provider.cloudflarePages.comingSoon": string;
"deploy.menu.deployTo": string;
+ // Marketplace
+ "settings.section.marketplace.label": string;
+ "settings.section.marketplace.hint": string;
+ "settings.marketplace.title": string;
+ "settings.marketplace.subtitle": string;
+ "marketplace.installFromGithub": string;
+ "marketplace.placeholder": string;
+ "marketplace.install": string;
+ "marketplace.installing": string;
+ "marketplace.uninstall": string;
+ "marketplace.hint": string;
+ "marketplace.installed": string;
+ "marketplace.installSucceeded": string;
+ "marketplace.uninstalled": string;
+ "marketplace.skillCount": string;
+ "marketplace.empty.title": string;
+ "marketplace.empty.body": string;
+
// Editor pane
"editor.tab.text": string;
"editor.tab.samples": string;
@@ -485,6 +503,25 @@ const en: Dict = {
"deploy.provider.cloudflarePages.comingSoon": "Coming soon",
"deploy.menu.deployTo": "Deploy to…",
+ "settings.section.marketplace.label": "Marketplace",
+ "settings.section.marketplace.hint": "Install skills from GitHub",
+ "settings.marketplace.title": "Skill marketplace",
+ "settings.marketplace.subtitle":
+ "Install community skill packs from public GitHub repos. Each pack ships one or more SKILL.md prompts that show up in the template picker.",
+ "marketplace.installFromGithub": "Install from GitHub",
+ "marketplace.placeholder": "owner/repo or owner/repo#branch",
+ "marketplace.install": "Install",
+ "marketplace.installing": "Installing…",
+ "marketplace.uninstall": "Uninstall",
+ "marketplace.hint":
+ "Public GitHub repos only. Needs a SKILL.md at the repo root, or skills/<id>/SKILL.md for multi-skill packs.",
+ "marketplace.installed": "Installed ({n})",
+ "marketplace.installSucceeded": "Installed {n} skill(s) from {repo}.",
+ "marketplace.uninstalled": "Package uninstalled.",
+ "marketplace.skillCount": "{n} skill(s)",
+ "marketplace.empty.title": "No packages installed yet",
+ "marketplace.empty.body": "Paste a GitHub repo above to install a community skill pack.",
+
"editor.tab.text": "✏️ Text",
"editor.tab.samples": "✨ Samples",
"editor.tab.formats": "📋 Formats",
@@ -827,6 +864,25 @@ const zhCN: Dict = {
"deploy.provider.cloudflarePages.comingSoon": "敬请期待",
"deploy.menu.deployTo": "部署到…",
+ "settings.section.marketplace.label": "市场",
+ "settings.section.marketplace.hint": "从 GitHub 安装 skill",
+ "settings.marketplace.title": "Skill 市场",
+ "settings.marketplace.subtitle":
+ "从公开 GitHub 仓库安装社区 skill 包。每个包带一个或多个 SKILL.md 提示词, 安装后会出现在模板选择器里。",
+ "marketplace.installFromGithub": "从 GitHub 安装",
+ "marketplace.placeholder": "owner/repo 或 owner/repo#branch",
+ "marketplace.install": "安装",
+ "marketplace.installing": "安装中…",
+ "marketplace.uninstall": "卸载",
+ "marketplace.hint":
+ "仅支持公开 GitHub 仓库。仓库根目录需有 SKILL.md, 或在 skills/<id>/SKILL.md 下放多个 skill。",
+ "marketplace.installed": "已安装 ({n})",
+ "marketplace.installSucceeded": "从 {repo} 安装了 {n} 个 skill。",
+ "marketplace.uninstalled": "已卸载。",
+ "marketplace.skillCount": "{n} 个 skill",
+ "marketplace.empty.title": "尚未安装任何包",
+ "marketplace.empty.body": "在上方粘贴一个 GitHub 仓库地址即可安装社区 skill 包。",
+
"editor.tab.text": "✏️ 输入",
"editor.tab.samples": "✨ 示例",
"editor.tab.formats": "📋 格式",
diff --git a/next/src/lib/skills/__tests__/api.test.ts b/next/src/lib/skills/__tests__/api.test.ts
new file mode 100644
index 00000000..993a60f0
--- /dev/null
+++ b/next/src/lib/skills/__tests__/api.test.ts
@@ -0,0 +1,212 @@
+import { spawn } from "node:child_process";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+/**
+ * Exercise the Next.js route handlers directly. We mock the underlying
+ * `installFromGitHub` for the success path (because POST runs in this process
+ * and needs the same fetch stub the lib tests use) and let DELETE run end-to-end
+ * against the on-disk registry.
+ */
+
+const SKILL_MD = `---
+name: api-test
+zh_name: API
+en_name: API Test
+emoji: "🔌"
+description: api test
+category: article
+scenario: marketing
+aspect_hint: a
+tags: ["x"]
+---
+body
+`;
+
+async function tarGzDir(dir: string, outPath: string): Promise<void> {
+ await new Promise<void>((resolve, reject) => {
+ const parent = path.dirname(dir);
+ const base = path.basename(dir);
+ const proc = spawn("tar", ["-czf", outPath, "-C", parent, base]);
+ let stderr = "";
+ proc.stderr.on("data", (c) => {
+ stderr += c.toString();
+ });
+ proc.on("error", reject);
+ proc.on("close", (code) => {
+ if (code === 0) resolve();
+ else reject(new Error(`tar -czf failed (${code}): ${stderr}`));
+ });
+ });
+}
+
+let tmpRoot: string;
+let originalFetch: typeof fetch;
+
+beforeEach(async () => {
+ tmpRoot = await fs.mkdtemp(path.join(os.tmpdir(), "ha-api-test-"));
+ process.env.HTML_ANYTHING_USER_SKILLS_DIR = path.join(tmpRoot, "user-skills");
+ originalFetch = globalThis.fetch;
+});
+
+afterEach(async () => {
+ globalThis.fetch = originalFetch;
+ delete process.env.HTML_ANYTHING_USER_SKILLS_DIR;
+ await fs.rm(tmpRoot, { recursive: true, force: true });
+ vi.resetModules();
+});
+
+async function buildOkTarball(): Promise<Buffer> {
+ const wrapper = path.join(tmpRoot, "wrapper");
+ await fs.mkdir(wrapper, { recursive: true });
+ await fs.writeFile(path.join(wrapper, "SKILL.md"), SKILL_MD, "utf8");
+ const tarballPath = path.join(tmpRoot, "archive.tar.gz");
+ await tarGzDir(wrapper, tarballPath);
+ return fs.readFile(tarballPath);
+}
+
+function stubFetch(tarball: Buffer): void {
+ globalThis.fetch = (async (input: RequestInfo | URL) => {
+ const url = typeof input === "string" ? input : input instanceof URL ? input.toString() : input.url;
+ if (url.includes("api.github.com/repos/")) {
+ return new Response(JSON.stringify({ default_branch: "main" }), { status: 200 });
+ }
+ if (url.includes("codeload.github.com")) {
+ return new Response(new Uint8Array(tarball), { status: 200 });
+ }
+ return new Response("not found", { status: 404 });
+ }) as typeof fetch;
+}
+
+describe("GET /api/marketplace", () => {
+ it("returns an empty list when nothing is installed", async () => {
+ const { GET } = await import("../../../app/api/marketplace/route");
+ const res = await GET(new Request("http://127.0.0.1/api/marketplace"));
+ const data = (await res.json()) as { packages: unknown[] };
+ expect(data.packages).toEqual([]);
+ });
+
+ it("returns 403 when the Host header is not loopback — even for the read endpoint", async () => {
+ // Privacy regression test: enumerating installed packages (repo
+ // owners / names / refs) must not be reachable via DNS rebinding.
+ const { GET } = await import("../../../app/api/marketplace/route");
+ const res = await GET(new Request("http://evil.example.com/api/marketplace"));
+ expect(res.status).toBe(403);
+ const data = (await res.json()) as { error: string };
+ expect(data.error).toBe("host_not_allowed");
+ });
+});
+
+describe("POST /api/marketplace/install", () => {
+ it("returns 403 when the Host header is not loopback (DNS-rebinding defense)", async () => {
+ const { POST } = await import("../../../app/api/marketplace/install/route");
+ // undici forbids setting the `host` request header, so encode the
+ // attacker-controlled host into the URL — that's what the guard reads
+ // (via `new URL(req.url).host`) when no Host header is present.
+ const req = new Request("http://evil.example.com/api/marketplace/install", {
+ method: "POST",
+ headers: { "content-type": "application/json" },
+ body: JSON.stringify({ source: "owner/repo" }),
+ });
+ const res = await POST(req);
+ expect(res.status).toBe(403);
+ const data = (await res.json()) as { error: string };
+ expect(data.error).toBe("host_not_allowed");
+ });
+
+ it("returns 400 on invalid JSON", async () => {
+ const { POST } = await import("../../../app/api/marketplace/install/route");
+ const req = new Request("http://127.0.0.1/api/marketplace/install", {
+ method: "POST",
+ body: "not json",
+ });
+ const res = await POST(req);
+ expect(res.status).toBe(400);
+ const data = (await res.json()) as { error: string };
+ expect(data.error).toBe("invalid_json");
+ });
+
+ it("returns 400 when source is missing", async () => {
+ const { POST } = await import("../../../app/api/marketplace/install/route");
+ const req = new Request("http://127.0.0.1/api/marketplace/install", {
+ method: "POST",
+ headers: { "content-type": "application/json" },
+ body: JSON.stringify({}),
+ });
+ const res = await POST(req);
+ expect(res.status).toBe(400);
+ });
+
+ it("returns 400 with the InstallError code on invalid spec", async () => {
+ const { POST } = await import("../../../app/api/marketplace/install/route");
+ const req = new Request("http://127.0.0.1/api/marketplace/install", {
+ method: "POST",
+ headers: { "content-type": "application/json" },
+ body: JSON.stringify({ source: "not a spec" }),
+ });
+ const res = await POST(req);
+ expect(res.status).toBe(400);
+ const data = (await res.json()) as { error: string };
+ expect(data.error).toBe("invalid_spec");
+ });
+
+ it("returns 200 + package manifest on a successful install", async () => {
+ const tarball = await buildOkTarball();
+ stubFetch(tarball);
+ const { POST } = await import("../../../app/api/marketplace/install/route");
+ const req = new Request("http://127.0.0.1/api/marketplace/install", {
+ method: "POST",
+ headers: { "content-type": "application/json" },
+ body: JSON.stringify({ source: "owner/repo" }),
+ });
+ const res = await POST(req);
+ expect(res.status).toBe(200);
+ const data = (await res.json()) as { package: { id: string } };
+ expect(data.package.id).toBe("owner__repo");
+ });
+});
+
+describe("DELETE /api/marketplace/packages/[id]", () => {
+ it("returns 400 on a malformed id", async () => {
+ const { DELETE } = await import("../../../app/api/marketplace/packages/[id]/route");
+ const res = await DELETE(new Request("http://127.0.0.1/api/marketplace/packages/x"), {
+ params: Promise.resolve({ id: "../../etc/passwd" }),
+ });
+ expect(res.status).toBe(400);
+ });
+
+ it("returns 404 for an id with the right shape but no on-disk package", async () => {
+ const { DELETE } = await import("../../../app/api/marketplace/packages/[id]/route");
+ const res = await DELETE(new Request("http://127.0.0.1/api/marketplace/packages/x"), {
+ params: Promise.resolve({ id: "ghost__pack" }),
+ });
+ expect(res.status).toBe(404);
+ });
+
+ it("removes a real installed package", async () => {
+ // Install through the POST handler so the on-disk state is realistic.
+ stubFetch(await buildOkTarball());
+ const { POST } = await import("../../../app/api/marketplace/install/route");
+ await POST(
+ new Request("http://127.0.0.1/api/marketplace/install", {
+ method: "POST",
+ headers: { "content-type": "application/json" },
+ body: JSON.stringify({ source: "owner/repo" }),
+ }),
+ );
+
+ const { DELETE } = await import("../../../app/api/marketplace/packages/[id]/route");
+ const res = await DELETE(new Request("http://127.0.0.1/api/marketplace/packages/x"), {
+ params: Promise.resolve({ id: "owner__repo" }),
+ });
+ expect(res.status).toBe(200);
+
+ const { GET } = await import("../../../app/api/marketplace/route");
+ const after = (await (await GET(new Request("http://127.0.0.1/api/marketplace"))).json()) as {
+ packages: unknown[];
+ };
+ expect(after.packages).toEqual([]);
+ });
+});
diff --git a/next/src/lib/skills/__tests__/cross-device.test.ts b/next/src/lib/skills/__tests__/cross-device.test.ts
new file mode 100644
index 00000000..1d4a8538
--- /dev/null
+++ b/next/src/lib/skills/__tests__/cross-device.test.ts
@@ -0,0 +1,149 @@
+import { spawn } from "node:child_process";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { installFromGitHub } from "../install";
+import { listPackages } from "../registry";
+import { userSkillsDir } from "../paths";
+
+/**
+ * Regression test for the maintainer-flagged EXDEV blocker: the previous
+ * implementation staged the package layout under `os.tmpdir()` and then
+ * called `fs.rename(stageDir, targetDir)`. On Linux hosts where `/tmp` is a
+ * separate tmpfs mount, that rename throws `EXDEV` and every install fails.
+ *
+ * The fix is to stage on the *destination* filesystem (next to `targetDir`)
+ * so the swap is always intra-FS. We verify it two ways:
+ *
+ * 1. Spy on `fs.rename` and assert both arguments share a parent dir —
+ * i.e. no cross-device rename is ever attempted. Holds regardless of
+ * whether the test runner actually has a separate `/tmp` mount.
+ * 2. Force `fs.rename` to throw `EXDEV` if the parent dirs ever *do*
+ * differ. If the staging path ever regresses back into `/tmp`, this
+ * blows up with the same error a real Linux host would see.
+ */
+
+async function tarGzDir(dir: string, outPath: string): Promise<void> {
+ await new Promise<void>((resolve, reject) => {
+ const parent = path.dirname(dir);
+ const base = path.basename(dir);
+ const proc = spawn("tar", ["-czf", outPath, "-C", parent, base]);
+ let stderr = "";
+ proc.stderr.on("data", (c) => {
+ stderr += c.toString();
+ });
+ proc.on("error", reject);
+ proc.on("close", (code) => {
+ if (code === 0) resolve();
+ else reject(new Error(`tar -czf failed (${code}): ${stderr}`));
+ });
+ });
+}
+
+const VALID_SKILL_MD = `---
+name: x
+zh_name: X
+en_name: X
+emoji: "✅"
+description: x
+category: article
+scenario: marketing
+aspect_hint: a
+tags: ["x"]
+---
+body
+`;
+
+function fakeFetch(tarball: Buffer): typeof fetch {
+ return (async (input: RequestInfo | URL) => {
+ const url = typeof input === "string" ? input : input instanceof URL ? input.toString() : input.url;
+ if (url.includes("api.github.com/repos/")) {
+ return new Response(JSON.stringify({ default_branch: "main" }), { status: 200 });
+ }
+ if (url.includes("codeload.github.com")) {
+ return new Response(new Uint8Array(tarball), { status: 200 });
+ }
+ return new Response("not found", { status: 404 });
+ }) as typeof fetch;
+}
+
+let tmpRoot: string;
+let originalRename: typeof fs.rename;
+
+beforeEach(async () => {
+ tmpRoot = await fs.mkdtemp(path.join(os.tmpdir(), "ha-xdev-test-"));
+ process.env.HTML_ANYTHING_USER_SKILLS_DIR = path.join(tmpRoot, "user-skills");
+ originalRename = fs.rename;
+});
+
+afterEach(async () => {
+ Object.defineProperty(fs, "rename", { value: originalRename, configurable: true, writable: true });
+ delete process.env.HTML_ANYTHING_USER_SKILLS_DIR;
+ await fs.rm(tmpRoot, { recursive: true, force: true });
+ vi.restoreAllMocks();
+});
+
+async function buildTarball(name: string): Promise<Buffer> {
+ const wrapper = path.join(tmpRoot, name);
+ await fs.mkdir(wrapper, { recursive: true });
+ await fs.writeFile(path.join(wrapper, "SKILL.md"), VALID_SKILL_MD, "utf8");
+ const tarballPath = path.join(tmpRoot, `${name}.tar.gz`);
+ await tarGzDir(wrapper, tarballPath);
+ return fs.readFile(tarballPath);
+}
+
+describe("cross-device-safe staging", () => {
+ it("never renames across filesystems — both args always share a parent dir", async () => {
+ const tar = await buildTarball("ok");
+ const renameSpy = vi.spyOn(fs, "rename");
+
+ const result = await installFromGitHub("owner/ok", { fetchImpl: fakeFetch(tar) });
+
+ expect(result.package.id).toBe("owner__ok");
+ expect(listPackages()).toHaveLength(1);
+
+ // At least one rename ran (the atomic swap), and every rename has both
+ // src and dst under the same parent directory.
+ expect(renameSpy.mock.calls.length).toBeGreaterThan(0);
+ for (const [src, dst] of renameSpy.mock.calls) {
+ expect(path.dirname(String(src))).toBe(path.dirname(String(dst)));
+ }
+ });
+
+ it("survives an `EXDEV` simulator that fails any cross-device rename", async () => {
+ // If staging ever regresses back into /tmp, this hook would fire and the
+ // install would fail with EXDEV — exactly as it would on a real Linux
+ // host with /tmp as tmpfs.
+ Object.defineProperty(fs, "rename", {
+ value: async (src: string, dst: string) => {
+ if (path.dirname(src) !== path.dirname(dst)) {
+ const err = new Error(`EXDEV: cross-device link not permitted, rename '${src}' -> '${dst}'`);
+ (err as NodeJS.ErrnoException).code = "EXDEV";
+ throw err;
+ }
+ return originalRename(src, dst);
+ },
+ configurable: true,
+ writable: true,
+ });
+
+ const tar = await buildTarball("ok2");
+ const result = await installFromGitHub("owner/ok2", { fetchImpl: fakeFetch(tar) });
+ expect(result.package.id).toBe("owner__ok2");
+ expect(listPackages().map((p) => p.id)).toContain("owner__ok2");
+ });
+
+ it("hidden stage dirs are not visible to listPackages", async () => {
+ const tar = await buildTarball("vis");
+ await installFromGitHub("owner/vis", { fetchImpl: fakeFetch(tar) });
+
+ // Drop a leftover stage dir to simulate a prior crashed install. The
+ // `.stage-` prefix means `listPackages` (whose segment validator
+ // requires a leading alphanumeric) must skip it.
+ await fs.mkdir(path.join(userSkillsDir(), ".stage-owner__vis-abcdef"), { recursive: true });
+
+ const pkgs = listPackages();
+ expect(pkgs.map((p) => p.id)).toEqual(["owner__vis"]);
+ });
+});
diff --git a/next/src/lib/skills/__tests__/install-rejections.test.ts b/next/src/lib/skills/__tests__/install-rejections.test.ts
new file mode 100644
index 00000000..617fb052
--- /dev/null
+++ b/next/src/lib/skills/__tests__/install-rejections.test.ts
@@ -0,0 +1,221 @@
+import { spawn } from "node:child_process";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { installFromGitHub, InstallError } from "../install";
+import { listPackages } from "../registry";
+import { userSkillsDir } from "../paths";
+
+/**
+ * Cover the negative paths of the installer. Each test builds a tarball that
+ * trips one specific guard, then asserts the right `InstallError.code` and
+ * confirms no partial-install was left on disk.
+ */
+
+const VALID_SKILL_MD = `---
+name: t
+zh_name: 测试
+en_name: T
+emoji: "🧪"
+description: test
+category: article
+scenario: marketing
+aspect_hint: a
+tags: ["x"]
+---
+body
+`;
+
+async function tarGzDir(dir: string, outPath: string): Promise<void> {
+ await new Promise<void>((resolve, reject) => {
+ const parent = path.dirname(dir);
+ const base = path.basename(dir);
+ const proc = spawn("tar", ["-czf", outPath, "-C", parent, base]);
+ let stderr = "";
+ proc.stderr.on("data", (c) => {
+ stderr += c.toString();
+ });
+ proc.on("error", reject);
+ proc.on("close", (code) => {
+ if (code === 0) resolve();
+ else reject(new Error(`tar -czf failed (${code}): ${stderr}`));
+ });
+ });
+}
+
+function fakeFetch(tarball: Buffer | null, opts: { defaultBranch?: string; tarballStatus?: number } = {}): typeof fetch {
+ return (async (input: RequestInfo | URL) => {
+ const url = typeof input === "string" ? input : input instanceof URL ? input.toString() : input.url;
+ if (url.includes("api.github.com/repos/")) {
+ return new Response(JSON.stringify({ default_branch: opts.defaultBranch ?? "main" }), {
+ status: 200,
+ headers: { "content-type": "application/json" },
+ });
+ }
+ if (url.includes("codeload.github.com")) {
+ if (opts.tarballStatus && opts.tarballStatus !== 200) {
+ return new Response("not found", { status: opts.tarballStatus });
+ }
+ if (tarball === null) {
+ return new Response("not found", { status: 404 });
+ }
+ return new Response(new Uint8Array(tarball), {
+ status: 200,
+ headers: { "content-type": "application/gzip" },
+ });
+ }
+ return new Response("not found", { status: 404 });
+ }) as typeof fetch;
+}
+
+let tmpRoot: string;
+
+beforeEach(async () => {
+ tmpRoot = await fs.mkdtemp(path.join(os.tmpdir(), "ha-reject-test-"));
+ process.env.HTML_ANYTHING_USER_SKILLS_DIR = path.join(tmpRoot, "user-skills");
+});
+
+afterEach(async () => {
+ delete process.env.HTML_ANYTHING_USER_SKILLS_DIR;
+ await fs.rm(tmpRoot, { recursive: true, force: true });
+});
+
+async function buildTarballWith(fixtureName: string, setup: (wrapper: string) => Promise<void>): Promise<Buffer> {
+ const wrapper = path.join(tmpRoot, "fixtures", fixtureName);
+ await fs.mkdir(wrapper, { recursive: true });
+ await setup(wrapper);
+ const tarballPath = path.join(tmpRoot, "fixtures", `${fixtureName}.tar.gz`);
+ await tarGzDir(wrapper, tarballPath);
+ return fs.readFile(tarballPath);
+}
+
+describe("install rejections", () => {
+ it("rejects SKILL.md without frontmatter", async () => {
+ const tar = await buildTarballWith("nofm-deadbeef", async (w) => {
+ await fs.writeFile(path.join(w, "SKILL.md"), "no frontmatter here\nbody\n", "utf8");
+ });
+ await expect(
+ installFromGitHub("owner/nofm", { fetchImpl: fakeFetch(tar) }),
+ ).rejects.toMatchObject({ code: "skill_md_no_frontmatter" });
+ expect(listPackages()).toHaveLength(0);
+ });
+
+ it("rejects SKILL.md larger than 256 KB", async () => {
+ const huge = `${VALID_SKILL_MD}${"x".repeat(300 * 1024)}`;
+ const tar = await buildTarballWith("huge-deadbeef", async (w) => {
+ await fs.writeFile(path.join(w, "SKILL.md"), huge, "utf8");
+ });
+ await expect(
+ installFromGitHub("owner/huge", { fetchImpl: fakeFetch(tar) }),
+ ).rejects.toMatchObject({ code: "skill_md_too_large" });
+ expect(listPackages()).toHaveLength(0);
+ });
+
+ it("rejects example.html larger than 2 MB", async () => {
+ const tar = await buildTarballWith("hugeex-deadbeef", async (w) => {
+ await fs.writeFile(path.join(w, "SKILL.md"), VALID_SKILL_MD, "utf8");
+ await fs.writeFile(path.join(w, "example.html"), "x".repeat(3 * 1024 * 1024), "utf8");
+ });
+ await expect(
+ installFromGitHub("owner/hugeex", { fetchImpl: fakeFetch(tar) }),
+ ).rejects.toMatchObject({ code: "example_too_large" });
+ expect(listPackages()).toHaveLength(0);
+ });
+
+ it("rejects a tarball containing a SKILL.md symlink", async () => {
+ const tar = await buildTarballWith("syml-deadbeef", async (w) => {
+ // Drop a real target and a SKILL.md symlinked to it. The preflight
+ // rejects every non-file/non-directory entry up front so the symlink
+ // never reaches the extractor — `forbidden_entry_type` fires before
+ // the post-extract `symlink_rejected` defense ever has to.
+ await fs.writeFile(path.join(w, "target.md"), VALID_SKILL_MD, "utf8");
+ await fs.symlink("target.md", path.join(w, "SKILL.md"));
+ });
+ await expect(
+ installFromGitHub("owner/syml", { fetchImpl: fakeFetch(tar) }),
+ ).rejects.toMatchObject({ code: "forbidden_entry_type" });
+ expect(listPackages()).toHaveLength(0);
+ });
+
+ it("propagates download failures as InstallError", async () => {
+ await expect(
+ installFromGitHub("owner/missing", { fetchImpl: fakeFetch(null, { tarballStatus: 404 }) }),
+ ).rejects.toMatchObject({ code: "download_failed" });
+ expect(listPackages()).toHaveLength(0);
+ });
+
+ it("rejects tarballs whose declared content-length blows past the cap", async () => {
+ const oversizedFetch: typeof fetch = (async () => {
+ return new Response(new Uint8Array([0]), {
+ status: 200,
+ headers: { "content-length": String(64 * 1024 * 1024), "content-type": "application/gzip" },
+ });
+ }) as typeof fetch;
+ await expect(
+ installFromGitHub("owner/big#main", { fetchImpl: oversizedFetch }),
+ ).rejects.toMatchObject({ code: "tarball_too_large" });
+ expect(listPackages()).toHaveLength(0);
+ });
+
+ it("falls back to main when the GitHub API call fails", async () => {
+ const tar = await buildTarballWith("ok-deadbeef", async (w) => {
+ await fs.writeFile(path.join(w, "SKILL.md"), VALID_SKILL_MD, "utf8");
+ });
+ const flaky: typeof fetch = (async (input: RequestInfo | URL) => {
+ const url = typeof input === "string" ? input : input instanceof URL ? input.toString() : input.url;
+ if (url.includes("api.github.com")) {
+ return new Response("nope", { status: 500 });
+ }
+ if (url.includes("codeload.github.com")) {
+ return new Response(new Uint8Array(tar), { status: 200 });
+ }
+ return new Response("", { status: 404 });
+ }) as typeof fetch;
+ const result = await installFromGitHub("owner/ok", { fetchImpl: flaky });
+ expect(result.package.source.ref).toBe("main");
+ });
+
+ it("does not leave a partial install behind on validation failure", async () => {
+ // First install succeeds so a real package exists on disk.
+ const good = await buildTarballWith("good-deadbeef", async (w) => {
+ await fs.writeFile(path.join(w, "SKILL.md"), VALID_SKILL_MD, "utf8");
+ });
+ await installFromGitHub("owner/good", { fetchImpl: fakeFetch(good) });
+ expect(listPackages()).toHaveLength(1);
+
+ // Reinstall of the same owner/repo with a broken payload must NOT corrupt
+ // the existing install — the atomic rename happens at the very end.
+ const broken = await buildTarballWith("broken-deadbeef", async (w) => {
+ await fs.writeFile(path.join(w, "SKILL.md"), "no frontmatter\n", "utf8");
+ });
+ await expect(
+ installFromGitHub("owner/good", { fetchImpl: fakeFetch(broken) }),
+ ).rejects.toBeInstanceOf(InstallError);
+
+ // The original install is still intact.
+ const pkgs = listPackages();
+ expect(pkgs).toHaveLength(1);
+ expect(pkgs[0].id).toBe("owner__good");
+ const stillThere = await fs.readFile(
+ path.join(userSkillsDir(), "owner__good", "skills", "good", "SKILL.md"),
+ "utf8",
+ );
+ expect(stillThere.startsWith("---")).toBe(true);
+ });
+});
+
+describe("registry edge cases", () => {
+ it("listPackages returns [] when the user-skills directory does not exist", async () => {
+ // beforeEach set HTML_ANYTHING_USER_SKILLS_DIR but never created it.
+ expect(listPackages()).toEqual([]);
+ });
+
+ it("skips packages whose manifest is missing or malformed", async () => {
+ const root = userSkillsDir();
+ await fs.mkdir(path.join(root, "no__manifest", "skills"), { recursive: true });
+ await fs.mkdir(path.join(root, "bad__manifest"), { recursive: true });
+ await fs.writeFile(path.join(root, "bad__manifest", "package.json"), "{ not json", "utf8");
+ expect(listPackages()).toEqual([]);
+ });
+});
diff --git a/next/src/lib/skills/__tests__/install.test.ts b/next/src/lib/skills/__tests__/install.test.ts
new file mode 100644
index 00000000..ce5766c3
--- /dev/null
+++ b/next/src/lib/skills/__tests__/install.test.ts
@@ -0,0 +1,204 @@
+import { spawn } from "node:child_process";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { installFromGitHub, uninstallPackage, InstallError } from "../install";
+import { listPackages, listUserSkills, readPackageManifest } from "../registry";
+import { userSkillsDir, makeSkillId } from "../paths";
+
+/**
+ * End-to-end tests for the marketplace install flow. We build a real .tar.gz
+ * fixture on disk (mimicking GitHub's `<repo>-<sha>/...` wrapper layout) and
+ * stub `fetch` to return its bytes — so the real `tar -xzf` codepath runs.
+ */
+
+const SKILL_MD = `---
+name: hello-world
+zh_name: 测试 skill
+en_name: Hello World
+emoji: "👋"
+description: a test skill
+category: article
+scenario: marketing
+aspect_hint: long page
+tags: ["test"]
+---
+
+Body of the skill.
+`;
+
+async function tarGzDir(dir: string, outPath: string): Promise<void> {
+ await new Promise<void>((resolve, reject) => {
+ const parent = path.dirname(dir);
+ const base = path.basename(dir);
+ const proc = spawn("tar", ["-czf", outPath, "-C", parent, base]);
+ let stderr = "";
+ proc.stderr.on("data", (c) => {
+ stderr += c.toString();
+ });
+ proc.on("error", reject);
+ proc.on("close", (code) => {
+ if (code === 0) resolve();
+ else reject(new Error(`tar -czf failed (${code}): ${stderr}`));
+ });
+ });
+}
+
+type Fixture = {
+ /** Absolute path to the built tarball. */
+ tarballPath: string;
+ /** Bytes of the tarball. */
+ tarballBytes: Buffer;
+};
+
+async function buildSingleSkillFixture(workDir: string): Promise<Fixture> {
+ // Mimic GitHub's tarball wrapper directory.
+ const wrapper = path.join(workDir, "owner-repo-deadbeef");
+ await fs.mkdir(wrapper, { recursive: true });
+ await fs.writeFile(path.join(wrapper, "SKILL.md"), SKILL_MD, "utf8");
+ await fs.writeFile(path.join(wrapper, "example.md"), "# example", "utf8");
+ await fs.writeFile(path.join(wrapper, "example.html"), "<html>example</html>", "utf8");
+ const tarballPath = path.join(workDir, "archive.tar.gz");
+ await tarGzDir(wrapper, tarballPath);
+ const tarballBytes = await fs.readFile(tarballPath);
+ return { tarballPath, tarballBytes };
+}
+
+async function buildMultiSkillFixture(workDir: string): Promise<Fixture> {
+ const wrapper = path.join(workDir, "owner-pack-cafef00d");
+ await fs.mkdir(path.join(wrapper, "skills", "first"), { recursive: true });
+ await fs.mkdir(path.join(wrapper, "skills", "second"), { recursive: true });
+ await fs.writeFile(path.join(wrapper, "skills", "first", "SKILL.md"), SKILL_MD, "utf8");
+ await fs.writeFile(path.join(wrapper, "skills", "second", "SKILL.md"), SKILL_MD, "utf8");
+ // A stray SKILL.md at the root must be ignored by the multi-skill discovery
+ // because the `skills/` directory wins.
+ // (We don't add one here; the discovery code prefers root-level if it
+ // exists, so testing the precedence requires a separate fixture.)
+ const tarballPath = path.join(workDir, "archive.tar.gz");
+ await tarGzDir(wrapper, tarballPath);
+ const tarballBytes = await fs.readFile(tarballPath);
+ return { tarballPath, tarballBytes };
+}
+
+function fakeFetch(tarballBytes: Buffer): typeof fetch {
+ return (async (input: RequestInfo | URL) => {
+ const url = typeof input === "string" ? input : input instanceof URL ? input.toString() : input.url;
+ if (url.includes("api.github.com/repos/")) {
+ return new Response(JSON.stringify({ default_branch: "main" }), {
+ status: 200,
+ headers: { "content-type": "application/json" },
+ });
+ }
+ if (url.includes("codeload.github.com")) {
+ return new Response(new Uint8Array(tarballBytes), {
+ status: 200,
+ headers: { "content-type": "application/gzip" },
+ });
+ }
+ return new Response("not found", { status: 404 });
+ }) as typeof fetch;
+}
+
+let tmpRoot: string;
+
+beforeEach(async () => {
+ tmpRoot = await fs.mkdtemp(path.join(os.tmpdir(), "ha-install-test-"));
+ process.env.HTML_ANYTHING_USER_SKILLS_DIR = path.join(tmpRoot, "user-skills");
+});
+
+afterEach(async () => {
+ delete process.env.HTML_ANYTHING_USER_SKILLS_DIR;
+ await fs.rm(tmpRoot, { recursive: true, force: true });
+});
+
+describe("installFromGitHub", () => {
+ it("installs a single-SKILL.md repo, writes a manifest, and registers the skill", async () => {
+ const { tarballBytes } = await buildSingleSkillFixture(path.join(tmpRoot, "fixture"));
+ const result = await installFromGitHub("owner/repo", { fetchImpl: fakeFetch(tarballBytes) });
+
+ expect(result.package.source).toEqual({ type: "github", owner: "owner", repo: "repo", ref: "main" });
+ expect(result.package.skills).toEqual(["repo"]);
+
+ // Manifest persisted to disk
+ const manifest = readPackageManifest("owner__repo");
+ expect(manifest).toMatchObject({ id: "owner__repo", skills: ["repo"] });
+
+ // SKILL.md ended up at the expected location
+ const skillPath = path.join(userSkillsDir(), "owner__repo", "skills", "repo", "SKILL.md");
+ expect((await fs.readFile(skillPath, "utf8")).startsWith("---")).toBe(true);
+
+ // Example files were copied too
+ expect(
+ await fs
+ .access(path.join(userSkillsDir(), "owner__repo", "skills", "repo", "example.html"))
+ .then(() => true)
+ .catch(() => false),
+ ).toBe(true);
+
+ // Registry walks user-skills + flattens with the namespaced id
+ const entries = listUserSkills();
+ const expectedId = makeSkillId("owner__repo", "repo");
+ expect(entries.map((e) => e.id)).toContain(expectedId);
+ });
+
+ it("installs a skills/<id>/SKILL.md multi-skill pack", async () => {
+ const { tarballBytes } = await buildMultiSkillFixture(path.join(tmpRoot, "fixture"));
+ const result = await installFromGitHub("owner/pack", { fetchImpl: fakeFetch(tarballBytes) });
+ expect(result.package.skills.sort()).toEqual(["first", "second"]);
+ const entries = listUserSkills();
+ const ids = entries.map((e) => e.id).sort();
+ expect(ids).toEqual([
+ makeSkillId("owner__pack", "first"),
+ makeSkillId("owner__pack", "second"),
+ ]);
+ });
+
+ it("is idempotent — reinstalling replaces the existing package atomically", async () => {
+ const { tarballBytes } = await buildSingleSkillFixture(path.join(tmpRoot, "fixture"));
+ await installFromGitHub("owner/repo", { fetchImpl: fakeFetch(tarballBytes) });
+ await installFromGitHub("owner/repo", { fetchImpl: fakeFetch(tarballBytes) });
+ expect(listPackages()).toHaveLength(1);
+ });
+
+ it("rejects an invalid spec without any fetch", async () => {
+ let fetched = false;
+ const sentinelFetch: typeof fetch = (async () => {
+ fetched = true;
+ return new Response("", { status: 200 });
+ }) as typeof fetch;
+ await expect(installFromGitHub("not a spec", { fetchImpl: sentinelFetch })).rejects.toBeInstanceOf(
+ InstallError,
+ );
+ expect(fetched).toBe(false);
+ });
+
+ it("rejects a repo with no SKILL.md", async () => {
+ const wrapper = path.join(tmpRoot, "fixture", "owner-empty-cafe");
+ await fs.mkdir(wrapper, { recursive: true });
+ await fs.writeFile(path.join(wrapper, "README.md"), "# nothing here", "utf8");
+ const tarballPath = path.join(tmpRoot, "fixture", "archive.tar.gz");
+ await tarGzDir(wrapper, tarballPath);
+ const tarball = await fs.readFile(tarballPath);
+ await expect(
+ installFromGitHub("owner/empty", { fetchImpl: fakeFetch(tarball) }),
+ ).rejects.toMatchObject({ code: "no_skills_found" });
+ });
+});
+
+describe("uninstallPackage", () => {
+ it("removes the package directory and reports success", async () => {
+ const { tarballBytes } = await buildSingleSkillFixture(path.join(tmpRoot, "fixture"));
+ await installFromGitHub("owner/repo", { fetchImpl: fakeFetch(tarballBytes) });
+ expect(listPackages()).toHaveLength(1);
+
+ const removed = await uninstallPackage("owner__repo");
+ expect(removed).toBe(true);
+ expect(listPackages()).toHaveLength(0);
+ expect(listUserSkills()).toHaveLength(0);
+ });
+
+ it("returns false for an unknown package id", async () => {
+ expect(await uninstallPackage("does__not-exist")).toBe(false);
+ });
+});
diff --git a/next/src/lib/skills/__tests__/loader-merge.test.ts b/next/src/lib/skills/__tests__/loader-merge.test.ts
new file mode 100644
index 00000000..5553fc18
--- /dev/null
+++ b/next/src/lib/skills/__tests__/loader-merge.test.ts
@@ -0,0 +1,89 @@
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+
+/**
+ * Verify the bundled-skill loader merges in user-installed skills with
+ * namespaced ids. We seed the user-skills directory by hand (no install) so
+ * the test stays focused on the loader codepath.
+ */
+
+const SKILL_MD = `---
+name: usertest
+zh_name: 用户测试
+en_name: User Test
+emoji: "🧪"
+description: a user skill
+category: article
+scenario: marketing
+aspect_hint: long page
+tags: ["test"]
+---
+
+Body of the user skill.
+`;
+
+const MANIFEST = {
+ id: "fake__pack",
+ source: { type: "github", owner: "fake", repo: "pack", ref: "main" },
+ installedAt: "2026-05-19T00:00:00.000Z",
+ skills: ["usertest"],
+};
+
+let tmpRoot: string;
+
+beforeEach(async () => {
+ tmpRoot = await fs.mkdtemp(path.join(os.tmpdir(), "ha-loader-test-"));
+ const userSkillsRoot = path.join(tmpRoot, "user-skills");
+ const skillDir = path.join(userSkillsRoot, "fake__pack", "skills", "usertest");
+ await fs.mkdir(skillDir, { recursive: true });
+ await fs.writeFile(
+ path.join(userSkillsRoot, "fake__pack", "package.json"),
+ JSON.stringify(MANIFEST, null, 2),
+ "utf8",
+ );
+ await fs.writeFile(path.join(skillDir, "SKILL.md"), SKILL_MD, "utf8");
+ process.env.HTML_ANYTHING_USER_SKILLS_DIR = userSkillsRoot;
+});
+
+afterEach(async () => {
+ delete process.env.HTML_ANYTHING_USER_SKILLS_DIR;
+ await fs.rm(tmpRoot, { recursive: true, force: true });
+});
+
+describe("loader merge", () => {
+ it("listSkills includes both bundled + user skills", async () => {
+ const { listSkills, invalidateSkillsCache } = await import("../../templates/loader");
+ invalidateSkillsCache();
+ const all = listSkills();
+ const ids = all.map((s) => s.id);
+ // Bundled skill we know ships in the repo
+ expect(ids).toContain("blog-post");
+ // User skill we just seeded, namespaced
+ expect(ids).toContain("pkg-fake__pack--usertest");
+ });
+
+ it("loadSkill returns body for a user-installed skill via its namespaced id", async () => {
+ const { loadSkill, invalidateSkillsCache } = await import("../../templates/loader");
+ invalidateSkillsCache();
+ const skill = loadSkill("pkg-fake__pack--usertest");
+ expect(skill).not.toBeNull();
+ expect(skill?.body).toContain("Body of the user skill");
+ expect(skill?.enName).toBe("User Test");
+ });
+
+ it("loadSkill returns null for an unknown namespaced id without throwing", async () => {
+ const { loadSkill, invalidateSkillsCache } = await import("../../templates/loader");
+ invalidateSkillsCache();
+ expect(loadSkill("pkg-fake__pack--missing")).toBeNull();
+ });
+
+ it("bundled ids still resolve correctly", async () => {
+ const { loadSkill, invalidateSkillsCache } = await import("../../templates/loader");
+ invalidateSkillsCache();
+ const blog = loadSkill("blog-post");
+ expect(blog).not.toBeNull();
+ expect(blog?.id).toBe("blog-post");
+ });
+});
diff --git a/next/src/lib/skills/__tests__/paths.test.ts b/next/src/lib/skills/__tests__/paths.test.ts
new file mode 100644
index 00000000..5b0d21a4
--- /dev/null
+++ b/next/src/lib/skills/__tests__/paths.test.ts
@@ -0,0 +1,56 @@
+import { describe, expect, it } from "vitest";
+import {
+ makeSkillId,
+ packageId,
+ parsePackageId,
+ parseSkillId,
+ SKILL_ID_PKG_PREFIX,
+} from "../paths";
+
+describe("packageId", () => {
+ it("joins owner and repo with double underscore", () => {
+ expect(packageId("nexu-io", "html-anything")).toBe("nexu-io__html-anything");
+ });
+});
+
+describe("parsePackageId", () => {
+ it("round-trips a normal id", () => {
+ expect(parsePackageId("nexu-io__html-anything")).toEqual({
+ owner: "nexu-io",
+ repo: "html-anything",
+ });
+ });
+
+ it("rejects ids without a separator", () => {
+ expect(parsePackageId("foobar")).toBeNull();
+ });
+
+ it("rejects ids with an empty owner or repo", () => {
+ expect(parsePackageId("__foo")).toBeNull();
+ expect(parsePackageId("foo__")).toBeNull();
+ });
+});
+
+describe("makeSkillId / parseSkillId", () => {
+ it("namespaces user skills with the pkg- prefix", () => {
+ const id = makeSkillId("owner__repo", "blog-post");
+ expect(id.startsWith(SKILL_ID_PKG_PREFIX)).toBe(true);
+ expect(id).toBe("pkg-owner__repo--blog-post");
+ });
+
+ it("round-trips through parseSkillId", () => {
+ const id = makeSkillId("nexu-io__html-anything", "magazine");
+ expect(parseSkillId(id)).toEqual({
+ pkgId: "nexu-io__html-anything",
+ originalId: "magazine",
+ });
+ });
+
+ it("returns null for bundled (non-pkg) ids", () => {
+ expect(parseSkillId("article-magazine")).toBeNull();
+ });
+
+ it("returns null for malformed pkg ids missing the separator", () => {
+ expect(parseSkillId("pkg-owner__repo")).toBeNull();
+ });
+});
diff --git a/next/src/lib/skills/__tests__/preflight.test.ts b/next/src/lib/skills/__tests__/preflight.test.ts
new file mode 100644
index 00000000..11554e2d
--- /dev/null
+++ b/next/src/lib/skills/__tests__/preflight.test.ts
@@ -0,0 +1,180 @@
+import { spawn } from "node:child_process";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import zlib from "node:zlib";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { installFromGitHub } from "../install";
+import { listPackages } from "../registry";
+
+/**
+ * Verify the in-process tarball preflight rejects entries that a downstream
+ * `tar -xzf` would happily extract — symlinks/hardlinks targeting parent
+ * paths, absolute paths, `..` segments, and decompressed-size blow-ups.
+ *
+ * These cases can't be built with the system `tar -czf` because it normalises
+ * away most of the dangerous shapes, so we hand-roll the tar archive bytes
+ * (POSIX ustar 512-byte header format) and gzip them.
+ */
+
+type TarEntry = {
+ name: string;
+ size: number;
+ typeFlag: string;
+ linkName?: string;
+ data?: Buffer;
+};
+
+function octal(n: number, width: number): Buffer {
+ // POSIX tar octal fields: ASCII octal digits, NUL-terminated, padded with
+ // zeros on the left.
+ const s = n.toString(8).padStart(width - 1, "0");
+ return Buffer.from(`${s}\0`, "binary");
+}
+
+function header(entry: TarEntry): Buffer {
+ const h = Buffer.alloc(512);
+ h.write(entry.name.slice(0, 100), 0, "utf8");
+ octal(0o644, 8).copy(h, 100); // mode
+ octal(0, 8).copy(h, 108); // uid
+ octal(0, 8).copy(h, 116); // gid
+ octal(entry.size, 12).copy(h, 124); // size
+ octal(0, 12).copy(h, 136); // mtime
+ // checksum field is initially spaces while we compute the checksum
+ h.fill(0x20, 148, 156);
+ h.write(entry.typeFlag, 156, "binary");
+ if (entry.linkName) h.write(entry.linkName.slice(0, 100), 157, "utf8");
+ h.write("ustar\0", 257, "binary");
+ h.write("00", 263, "binary");
+ // checksum = sum of unsigned bytes of header with checksum field as spaces
+ let sum = 0;
+ for (const b of h) sum += b;
+ octal(sum, 7).copy(h, 148);
+ h[155] = 0x20; // trailing space per spec
+ return h;
+}
+
+function buildTarball(entries: TarEntry[]): Buffer {
+ const blocks: Buffer[] = [];
+ for (const e of entries) {
+ blocks.push(header(e));
+ if (e.data && e.data.length > 0) {
+ blocks.push(e.data);
+ const pad = (512 - (e.data.length % 512)) % 512;
+ if (pad > 0) blocks.push(Buffer.alloc(pad));
+ }
+ }
+ blocks.push(Buffer.alloc(512));
+ blocks.push(Buffer.alloc(512));
+ return zlib.gzipSync(Buffer.concat(blocks));
+}
+
+function fakeFetchWithTarball(tarball: Buffer): typeof fetch {
+ return (async (input: RequestInfo | URL) => {
+ const url = typeof input === "string" ? input : input instanceof URL ? input.toString() : input.url;
+ if (url.includes("api.github.com/repos/")) {
+ return new Response(JSON.stringify({ default_branch: "main" }), { status: 200 });
+ }
+ if (url.includes("codeload.github.com")) {
+ return new Response(new Uint8Array(tarball), { status: 200 });
+ }
+ return new Response("not found", { status: 404 });
+ }) as typeof fetch;
+}
+
+let tmpRoot: string;
+
+beforeEach(async () => {
+ tmpRoot = await fs.mkdtemp(path.join(os.tmpdir(), "ha-preflight-test-"));
+ process.env.HTML_ANYTHING_USER_SKILLS_DIR = path.join(tmpRoot, "user-skills");
+});
+
+afterEach(async () => {
+ delete process.env.HTML_ANYTHING_USER_SKILLS_DIR;
+ await fs.rm(tmpRoot, { recursive: true, force: true });
+});
+
+describe("tarball preflight", () => {
+ it("rejects hardlink entries (typeFlag 1) — the system tar would otherwise resolve the link target", async () => {
+ const tar = buildTarball([
+ { name: "wrapper/", size: 0, typeFlag: "5" },
+ { name: "wrapper/target", size: 4, typeFlag: "0", data: Buffer.from("data") },
+ { name: "wrapper/SKILL.md", size: 0, typeFlag: "1", linkName: "wrapper/target" },
+ ]);
+ await expect(
+ installFromGitHub("owner/hardlink", { fetchImpl: fakeFetchWithTarball(tar) }),
+ ).rejects.toMatchObject({ code: "forbidden_entry_type" });
+ expect(listPackages()).toHaveLength(0);
+ });
+
+ it("rejects entries with absolute paths", async () => {
+ const tar = buildTarball([
+ { name: "/etc/passwd", size: 4, typeFlag: "0", data: Buffer.from("data") },
+ ]);
+ await expect(
+ installFromGitHub("owner/abs", { fetchImpl: fakeFetchWithTarball(tar) }),
+ ).rejects.toMatchObject({ code: "unsafe_path" });
+ expect(listPackages()).toHaveLength(0);
+ });
+
+ it("rejects entries containing '..' segments", async () => {
+ const tar = buildTarball([
+ { name: "wrapper/../escape", size: 4, typeFlag: "0", data: Buffer.from("data") },
+ ]);
+ await expect(
+ installFromGitHub("owner/traversal", { fetchImpl: fakeFetchWithTarball(tar) }),
+ ).rejects.toMatchObject({ code: "unsafe_path" });
+ expect(listPackages()).toHaveLength(0);
+ });
+
+ it("rejects gzip-bomb tarballs whose decompressed size exceeds the cap", async () => {
+ // Highly-compressible: 200 MB of zero bytes gzips to <500 KB but
+ // decompression overshoots the 96 MB cap so the preflight aborts before
+ // any extraction touches disk.
+ const huge = Buffer.alloc(200 * 1024 * 1024);
+ const gz = zlib.gzipSync(huge);
+ // Sanity-check that we actually built a bomb: compressed under the 32 MB
+ // download cap, decompressed over the 96 MB preflight cap.
+ expect(gz.byteLength).toBeLessThan(32 * 1024 * 1024);
+ const bomb: typeof fetch = (async () =>
+ new Response(new Uint8Array(gz), { status: 200 })) as typeof fetch;
+ await expect(
+ installFromGitHub("owner/bomb#main", { fetchImpl: bomb }),
+ ).rejects.toMatchObject({ code: "tarball_uncompressed_too_large" });
+ expect(listPackages()).toHaveLength(0);
+ });
+
+ it("rejects tarballs that fail to gunzip", async () => {
+ const garbage = Buffer.from("not gzip data at all");
+ const bad: typeof fetch = (async () =>
+ new Response(new Uint8Array(garbage), { status: 200 })) as typeof fetch;
+ await expect(
+ installFromGitHub("owner/corrupt#main", { fetchImpl: bad }),
+ ).rejects.toMatchObject({ code: "tarball_corrupt" });
+ expect(listPackages()).toHaveLength(0);
+ });
+
+ it("accepts a well-formed single-skill tarball through the preflight + extract pipeline", async () => {
+ // Build via the system `tar` so the archive shape matches what GitHub
+ // produces, then run end-to-end. This is the happy-path smoke test that
+ // confirms the new preflight isn't over-eager.
+ const wrapper = path.join(tmpRoot, "fixtures", "happy");
+ await fs.mkdir(wrapper, { recursive: true });
+ await fs.writeFile(
+ path.join(wrapper, "SKILL.md"),
+ `---\nname: x\nzh_name: X\nen_name: X\nemoji: "✅"\ndescription: x\ncategory: article\nscenario: marketing\naspect_hint: a\ntags: ["x"]\n---\nbody\n`,
+ "utf8",
+ );
+ const tarballPath = path.join(tmpRoot, "fixtures", "happy.tar.gz");
+ await new Promise<void>((resolve, reject) => {
+ const proc = spawn("tar", ["-czf", tarballPath, "-C", path.dirname(wrapper), path.basename(wrapper)]);
+ proc.on("error", reject);
+ proc.on("close", (code) => (code === 0 ? resolve() : reject(new Error(`tar exit ${code}`))));
+ });
+ const tar = await fs.readFile(tarballPath);
+
+ const result = await installFromGitHub("owner/happy", { fetchImpl: fakeFetchWithTarball(tar) });
+ expect(result.package.schemaVersion).toBe(1);
+ expect(listPackages()).toHaveLength(1);
+ });
+});
diff --git a/next/src/lib/skills/__tests__/spec.test.ts b/next/src/lib/skills/__tests__/spec.test.ts
new file mode 100644
index 00000000..22577179
--- /dev/null
+++ b/next/src/lib/skills/__tests__/spec.test.ts
@@ -0,0 +1,58 @@
+import { describe, expect, it } from "vitest";
+import { parseGitHubSpec } from "../install";
+
+describe("parseGitHubSpec", () => {
+ it("parses owner/repo short form", () => {
+ expect(parseGitHubSpec("nexu-io/html-anything")).toEqual({
+ owner: "nexu-io",
+ repo: "html-anything",
+ });
+ });
+
+ it("parses owner/repo#ref short form", () => {
+ expect(parseGitHubSpec("nexu-io/html-anything#main")).toEqual({
+ owner: "nexu-io",
+ repo: "html-anything",
+ ref: "main",
+ });
+ });
+
+ it("strips a trailing .git", () => {
+ expect(parseGitHubSpec("nexu-io/html-anything.git")).toEqual({
+ owner: "nexu-io",
+ repo: "html-anything",
+ });
+ });
+
+ it("parses a full https URL", () => {
+ expect(parseGitHubSpec("https://github.com/nexu-io/html-anything")).toEqual({
+ owner: "nexu-io",
+ repo: "html-anything",
+ });
+ });
+
+ it("parses a /tree/<ref> URL", () => {
+ expect(parseGitHubSpec("https://github.com/nexu-io/html-anything/tree/feat/foo")).toEqual({
+ owner: "nexu-io",
+ repo: "html-anything",
+ ref: "feat/foo",
+ });
+ });
+
+ it("rejects path-traversal refs", () => {
+ expect(parseGitHubSpec("foo/bar#../../etc/passwd")).toBeNull();
+ });
+
+ it("rejects shell-character owners", () => {
+ expect(parseGitHubSpec("foo;rm-rf/bar")).toBeNull();
+ });
+
+ it("rejects empty input", () => {
+ expect(parseGitHubSpec("")).toBeNull();
+ expect(parseGitHubSpec(" ")).toBeNull();
+ });
+
+ it("rejects URLs from other hosts", () => {
+ expect(parseGitHubSpec("https://gitlab.com/foo/bar")).toBeNull();
+ });
+});
diff --git a/next/src/lib/skills/install.ts b/next/src/lib/skills/install.ts
new file mode 100644
index 00000000..276ac434
--- /dev/null
+++ b/next/src/lib/skills/install.ts
@@ -0,0 +1,495 @@
+import { spawn } from "node:child_process";
+import { randomBytes } from "node:crypto";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import zlib from "node:zlib";
+import { packageId, userSkillsDir } from "./paths";
+import { readPackageManifest, type InstalledPackage } from "./registry";
+
+/** Bump when the on-disk manifest schema changes incompatibly. */
+const MANIFEST_SCHEMA_VERSION = 1;
+
+/**
+ * Marketplace install from a public GitHub repo. The repo must lay out its
+ * skills in one of two shapes:
+ *
+ * - **Single skill**: `SKILL.md` at the repo root → installed as one skill
+ * with the repo name as its original id.
+ * - **Multi-skill pack**: `skills/<original-id>/SKILL.md` at the repo root.
+ * Every direct subdirectory of `skills/` is treated as one skill.
+ *
+ * Layout discovery is intentionally simple and ignores nested matches so a
+ * stray `SKILL.md` deep inside docs/ can't pollute the registry.
+ */
+
+const SKILL_MD_MAX_BYTES = 256 * 1024;
+const EXAMPLE_HTML_MAX_BYTES = 2 * 1024 * 1024;
+const EXAMPLE_MD_MAX_BYTES = 512 * 1024;
+const TARBALL_MAX_BYTES = 32 * 1024 * 1024;
+/**
+ * Cap on the *decompressed* size of the tarball. Defends against gzip bombs
+ * where the 32 MB compressed cap above could still expand to many GB and
+ * exhaust /tmp during extraction. 96 MB is roomy enough for any plausible
+ * skill pack while keeping the bomb amplification ratio bounded.
+ */
+const TARBALL_MAX_UNCOMPRESSED_BYTES = 96 * 1024 * 1024;
+// GitHub's default branch is queryable via this API; we fall back to `main` if
+// the request fails (handles offline-with-cache scenarios and public unauth
+// rate limits).
+const GITHUB_API_BASE = "https://api.github.com";
+const GITHUB_CODELOAD_BASE = "https://codeload.github.com";
+
+export type GitHubSpec = {
+ owner: string;
+ repo: string;
+ /** Optional branch / tag / sha. Resolved against the repo's default branch when omitted. */
+ ref?: string;
+};
+
+export class InstallError extends Error {
+ readonly code: string;
+ constructor(code: string, message: string) {
+ super(message);
+ this.code = code;
+ this.name = "InstallError";
+ }
+}
+
+/**
+ * Accept `owner/repo`, `owner/repo#ref`, or a full `https://github.com/owner/repo[/tree/ref]` URL.
+ * Returns `null` for anything else — the caller surfaces the error to the user.
+ */
+export function parseGitHubSpec(spec: string): GitHubSpec | null {
+ const trimmed = spec.trim();
+ if (!trimmed) return null;
+
+ // Full URL form: https://github.com/owner/repo or .../tree/<ref>.
+ // `ref` may contain slashes (e.g. `feat/foo`) — match anything up to `?` or `#`
+ // and let isSafeRef vet the result.
+ const urlMatch = /^https?:\/\/github\.com\/([^/\s]+)\/([^/\s#?]+)(?:\/tree\/([^\s#?]+))?/i.exec(
+ trimmed,
+ );
+ if (urlMatch) {
+ const owner = urlMatch[1];
+ const repo = urlMatch[2].replace(/\.git$/, "");
+ const ref = urlMatch[3];
+ if (!isSafeSegment(owner) || !isSafeSegment(repo)) return null;
+ if (ref && !isSafeRef(ref)) return null;
+ return ref ? { owner, repo, ref } : { owner, repo };
+ }
+
+ // Short form: owner/repo[#ref]
+ const shortMatch = /^([^/\s#]+)\/([^/\s#]+?)(?:\.git)?(?:#(.+))?$/i.exec(trimmed);
+ if (shortMatch) {
+ const [, owner, repo, ref] = shortMatch;
+ if (!isSafeSegment(owner) || !isSafeSegment(repo)) return null;
+ if (ref && !isSafeRef(ref)) return null;
+ return ref ? { owner, repo, ref } : { owner, repo };
+ }
+
+ return null;
+}
+
+function isSafeSegment(s: string): boolean {
+ // GitHub usernames + repos allow `[a-z0-9._-]`, must not start with `.` or `-`.
+ return /^[a-z0-9_][a-z0-9._-]*$/i.test(s) && s.length <= 100;
+}
+
+function isSafeRef(s: string): boolean {
+ // Branches/tags/SHAs in practice: alphanum + `._-/`, must not contain `..`.
+ return /^[a-z0-9._/-]+$/i.test(s) && !s.includes("..") && s.length <= 200;
+}
+
+async function fetchDefaultBranch(owner: string, repo: string, fetchImpl: typeof fetch): Promise<string> {
+ try {
+ const res = await fetchImpl(`${GITHUB_API_BASE}/repos/${owner}/${repo}`, {
+ headers: { Accept: "application/vnd.github+json" },
+ });
+ if (!res.ok) return "main";
+ const json = (await res.json()) as { default_branch?: string };
+ return json.default_branch && isSafeRef(json.default_branch) ? json.default_branch : "main";
+ } catch {
+ return "main";
+ }
+}
+
+async function downloadTarball(
+ url: string,
+ destPath: string,
+ fetchImpl: typeof fetch,
+): Promise<void> {
+ const res = await fetchImpl(url, { redirect: "follow" });
+ if (!res.ok) {
+ throw new InstallError(
+ "download_failed",
+ `failed to download ${url}: ${res.status} ${res.statusText}`,
+ );
+ }
+ const declared = Number(res.headers.get("content-length") ?? 0);
+ if (declared > TARBALL_MAX_BYTES) {
+ throw new InstallError(
+ "tarball_too_large",
+ `tarball is ${declared} bytes (cap ${TARBALL_MAX_BYTES})`,
+ );
+ }
+ // 32 MB cap, so buffering to memory is fine. Avoids the awkward
+ // ReadableStream-↔-Node-stream interop and lets us double-check the actual
+ // (post-decompression-of-transfer-encoding) byte count.
+ const buf = Buffer.from(await res.arrayBuffer());
+ if (buf.byteLength > TARBALL_MAX_BYTES) {
+ throw new InstallError(
+ "tarball_too_large",
+ `tarball is ${buf.byteLength} bytes (cap ${TARBALL_MAX_BYTES})`,
+ );
+ }
+ await fs.writeFile(destPath, buf);
+}
+
+/**
+ * Walk every header in a tar archive and reject anything dangerous BEFORE
+ * we hand the file to `tar -xzf`. The system `tar` binary alone is not a
+ * reliable security boundary — BSD tar on macOS happily extracts symlinks
+ * that point outside the destination, and a `symlink → ../../etc` entry
+ * followed by a `link/passwd` regular-file entry is a classic write-through-
+ * symlink primitive. So we:
+ *
+ * 1. Decompress with a hard `maxOutputLength` cap to defuse gzip bombs.
+ * 2. Parse every 512-byte header, enforcing:
+ * - only regular files ('0', '\0') and directories ('5') allowed; any
+ * symlink ('2'), hardlink ('1'), char/block/fifo/socket entry is rejected;
+ * - no absolute paths, `..` segments, or NUL chars in the name;
+ * - cumulative declared sizes within {@link TARBALL_MAX_UNCOMPRESSED_BYTES}.
+ *
+ * Returns silently on success; throws {@link InstallError} on any violation.
+ */
+async function preflightTarball(tarPath: string): Promise<void> {
+ const gz = await fs.readFile(tarPath);
+ let plain: Buffer;
+ try {
+ plain = zlib.gunzipSync(gz, { maxOutputLength: TARBALL_MAX_UNCOMPRESSED_BYTES });
+ } catch (err) {
+ const code = (err as NodeJS.ErrnoException)?.code;
+ if (code === "ERR_BUFFER_TOO_LARGE") {
+ throw new InstallError(
+ "tarball_uncompressed_too_large",
+ `tarball would decompress to more than ${TARBALL_MAX_UNCOMPRESSED_BYTES} bytes`,
+ );
+ }
+ throw new InstallError(
+ "tarball_corrupt",
+ `failed to decompress tarball: ${err instanceof Error ? err.message : String(err)}`,
+ );
+ }
+
+ const BLOCK = 512;
+ let off = 0;
+ let totalDeclared = 0;
+ while (off + BLOCK <= plain.length) {
+ const header = plain.subarray(off, off + BLOCK);
+ // End-of-archive marker: two consecutive all-zero blocks.
+ if (header.every((b) => b === 0)) break;
+
+ const name = readCString(header, 0, 100);
+ const prefix = readCString(header, 345, 155);
+ const fullName = prefix ? `${prefix}/${name}` : name;
+ const sizeStr = readCString(header, 124, 12);
+ const size = sizeStr ? Number.parseInt(sizeStr, 8) : 0;
+ const typeFlag = String.fromCharCode(header[156] || 0x30); // '0' default
+
+ if (!Number.isFinite(size) || size < 0) {
+ throw new InstallError("tarball_corrupt", `tar entry "${fullName}" has invalid size header`);
+ }
+ if (fullName.includes("\0") || fullName.startsWith("/")) {
+ throw new InstallError("unsafe_path", `tar entry has unsafe path: ${JSON.stringify(fullName)}`);
+ }
+ const segments = fullName.split("/");
+ if (segments.some((seg) => seg === "..")) {
+ throw new InstallError("unsafe_path", `tar entry contains '..' segment: ${JSON.stringify(fullName)}`);
+ }
+ // Allow regular files ('0' or '\0' for legacy), directories ('5'), and
+ // PAX extended-header pseudo-entries ('x', 'g'). Reject everything else
+ // — symlinks ('2'), hardlinks ('1'), char ('3'), block ('4'), fifo ('6'),
+ // and the GNU long-name extensions ('K', 'L') which can smuggle paths
+ // past the 100-byte name check we already did.
+ const allowed = new Set(["0", "\0", "5", "x", "g"]);
+ if (!allowed.has(typeFlag)) {
+ throw new InstallError(
+ "forbidden_entry_type",
+ `tar entry "${fullName}" has forbidden type ${JSON.stringify(typeFlag)}`,
+ );
+ }
+
+ totalDeclared += size;
+ if (totalDeclared > TARBALL_MAX_UNCOMPRESSED_BYTES) {
+ throw new InstallError(
+ "tarball_uncompressed_too_large",
+ `cumulative declared size exceeds ${TARBALL_MAX_UNCOMPRESSED_BYTES} bytes`,
+ );
+ }
+
+ off += BLOCK + Math.ceil(size / BLOCK) * BLOCK;
+ }
+}
+
+function readCString(buf: Buffer, offset: number, length: number): string {
+ const slice = buf.subarray(offset, offset + length);
+ const end = slice.indexOf(0);
+ return slice.subarray(0, end === -1 ? slice.length : end).toString("utf8");
+}
+
+async function extractTarball(tarPath: string, destDir: string): Promise<void> {
+ await fs.mkdir(destDir, { recursive: true });
+ await new Promise<void>((resolve, reject) => {
+ // `--strip-components=1` drops the `<repo>-<sha>/` wrapper directory
+ // GitHub adds. `--no-same-owner` keeps perms sane on shared boxes.
+ const proc = spawn("tar", ["-xzf", tarPath, "-C", destDir, "--strip-components=1", "--no-same-owner"], {
+ stdio: ["ignore", "ignore", "pipe"],
+ });
+ let stderr = "";
+ proc.stderr.on("data", (chunk) => {
+ stderr += chunk.toString();
+ });
+ proc.on("error", (err) => reject(new InstallError("tar_failed", `tar spawn failed: ${err.message}`)));
+ proc.on("close", (code) => {
+ if (code === 0) resolve();
+ else reject(new InstallError("tar_failed", `tar exited ${code}: ${stderr.trim()}`));
+ });
+ });
+}
+
+type DiscoveredSkill = {
+ originalId: string;
+ /** Directory containing this skill's `SKILL.md`. */
+ sourceDir: string;
+};
+
+async function discoverSkills(repoRoot: string, repoName: string): Promise<DiscoveredSkill[]> {
+ // Shape 1: single skill at repo root.
+ if (await exists(path.join(repoRoot, "SKILL.md"))) {
+ const id = sanitizeSkillId(repoName);
+ if (!id) {
+ throw new InstallError("invalid_skill_id", `cannot derive skill id from repo name "${repoName}"`);
+ }
+ return [{ originalId: id, sourceDir: repoRoot }];
+ }
+
+ // Shape 2: skills/<id>/SKILL.md
+ const skillsDir = path.join(repoRoot, "skills");
+ const skillsStat = await safeStat(skillsDir);
+ if (skillsStat?.isDirectory()) {
+ const entries = await fs.readdir(skillsDir, { withFileTypes: true });
+ const found: DiscoveredSkill[] = [];
+ for (const ent of entries) {
+ if (!ent.isDirectory()) continue;
+ const id = sanitizeSkillId(ent.name);
+ if (!id) continue;
+ const sourceDir = path.join(skillsDir, ent.name);
+ if (await exists(path.join(sourceDir, "SKILL.md"))) {
+ found.push({ originalId: id, sourceDir });
+ }
+ }
+ if (found.length) return found;
+ }
+
+ throw new InstallError(
+ "no_skills_found",
+ `no SKILL.md found at repo root or under skills/`,
+ );
+}
+
+function sanitizeSkillId(name: string): string | null {
+ const cleaned = name.toLowerCase().replace(/[^a-z0-9._-]/g, "-").replace(/^-+|-+$/g, "");
+ if (!cleaned) return null;
+ if (!/^[a-z0-9][a-z0-9._-]*$/.test(cleaned)) return null;
+ return cleaned;
+}
+
+async function exists(p: string): Promise<boolean> {
+ try {
+ await fs.access(p);
+ return true;
+ } catch {
+ return false;
+ }
+}
+
+async function safeStat(p: string) {
+ try {
+ return await fs.stat(p);
+ } catch {
+ return null;
+ }
+}
+
+async function copyValidatedSkill(src: DiscoveredSkill, destDir: string): Promise<void> {
+ await fs.mkdir(destDir, { recursive: true });
+
+ // SKILL.md is mandatory and capped.
+ const skillMdPath = path.join(src.sourceDir, "SKILL.md");
+ await assertNoSymlink(skillMdPath);
+ const skillMdStat = await fs.stat(skillMdPath);
+ if (skillMdStat.size > SKILL_MD_MAX_BYTES) {
+ throw new InstallError(
+ "skill_md_too_large",
+ `${src.originalId}/SKILL.md is ${skillMdStat.size} bytes (cap ${SKILL_MD_MAX_BYTES})`,
+ );
+ }
+ const raw = await fs.readFile(skillMdPath, "utf8");
+ // Cheap frontmatter sanity check — full parse happens at load time, but we
+ // reject obviously broken files up front so the picker doesn't show ghost
+ // entries.
+ if (!/^---\s*\r?\n[\s\S]*?\r?\n---/.test(raw)) {
+ throw new InstallError(
+ "skill_md_no_frontmatter",
+ `${src.originalId}/SKILL.md is missing YAML frontmatter`,
+ );
+ }
+ await fs.writeFile(path.join(destDir, "SKILL.md"), raw);
+
+ // Optional example files.
+ await copyOptional(src.sourceDir, destDir, "example.html", EXAMPLE_HTML_MAX_BYTES);
+ await copyOptional(src.sourceDir, destDir, "example.md", EXAMPLE_MD_MAX_BYTES);
+}
+
+async function copyOptional(
+ sourceDir: string,
+ destDir: string,
+ filename: string,
+ maxBytes: number,
+): Promise<void> {
+ const srcPath = path.join(sourceDir, filename);
+ if (!(await exists(srcPath))) return;
+ await assertNoSymlink(srcPath);
+ const stat = await fs.stat(srcPath);
+ if (stat.size > maxBytes) {
+ throw new InstallError(
+ "example_too_large",
+ `${filename} is ${stat.size} bytes (cap ${maxBytes})`,
+ );
+ }
+ await fs.copyFile(srcPath, path.join(destDir, filename));
+}
+
+async function assertNoSymlink(p: string): Promise<void> {
+ const stat = await fs.lstat(p);
+ if (stat.isSymbolicLink()) {
+ throw new InstallError("symlink_rejected", `symlinks are not allowed: ${p}`);
+ }
+}
+
+export type InstallResult = {
+ package: InstalledPackage;
+};
+
+export type InstallOptions = {
+ /** Inject a fetch impl for tests; defaults to global `fetch`. */
+ fetchImpl?: typeof fetch;
+};
+
+/**
+ * Install a skill pack from a GitHub repo. Idempotent — a re-install replaces
+ * the existing package atomically.
+ */
+export async function installFromGitHub(spec: string, opts: InstallOptions = {}): Promise<InstallResult> {
+ const fetchImpl = opts.fetchImpl ?? fetch;
+ const parsed = parseGitHubSpec(spec);
+ if (!parsed) {
+ throw new InstallError("invalid_spec", `not a valid GitHub spec: "${spec}"`);
+ }
+ const { owner, repo } = parsed;
+ const ref = parsed.ref ?? (await fetchDefaultBranch(owner, repo, fetchImpl));
+
+ const pkgId = packageId(owner, repo);
+ // Download / extract scratch space goes in `os.tmpdir()` — those files are
+ // transient and the temp filesystem is the right place for them. The
+ // *staged final layout*, on the other hand, must live on the destination
+ // filesystem so the atomic-swap `rename(2)` below stays intra-FS. On many
+ // Linux hosts `/tmp` is a separate tmpfs mount, and a cross-device rename
+ // throws `EXDEV`, which would break every install in production.
+ const workDir = await fs.mkdtemp(path.join(os.tmpdir(), "ha-skill-install-"));
+ const targetDir = path.join(userSkillsDir(), pkgId);
+ await fs.mkdir(path.dirname(targetDir), { recursive: true });
+ // Hidden temp dir alongside the target — same filesystem by construction.
+ // The `.stage-` prefix keeps it from being picked up by `listPackages`
+ // (which requires a leading alphanumeric segment), and the random suffix
+ // makes concurrent installs of different packages collision-free.
+ const stageDir = path.join(
+ path.dirname(targetDir),
+ `.stage-${pkgId}-${randomBytes(8).toString("hex")}`,
+ );
+ try {
+ const tarPath = path.join(workDir, "archive.tar.gz");
+ const tarballUrl = `${GITHUB_CODELOAD_BASE}/${owner}/${repo}/tar.gz/${encodeURIComponent(ref)}`;
+ await downloadTarball(tarballUrl, tarPath, fetchImpl);
+ // Validate every tar header before invoking the system `tar` binary —
+ // see {@link preflightTarball} for the threat model.
+ await preflightTarball(tarPath);
+
+ const extractDir = path.join(workDir, "extracted");
+ await extractTarball(tarPath, extractDir);
+
+ const discovered = await discoverSkills(extractDir, repo);
+
+ // Build the final layout in `stageDir` (which lives next to `targetDir`).
+ await fs.mkdir(path.join(stageDir, "skills"), { recursive: true });
+ for (const skill of discovered) {
+ await copyValidatedSkill(skill, path.join(stageDir, "skills", skill.originalId));
+ }
+ const manifest: InstalledPackage = {
+ schemaVersion: MANIFEST_SCHEMA_VERSION,
+ id: pkgId,
+ source: { type: "github", owner, repo, ref },
+ installedAt: new Date().toISOString(),
+ skills: discovered.map((s) => s.originalId),
+ };
+ await fs.writeFile(
+ path.join(stageDir, "package.json"),
+ `${JSON.stringify(manifest, null, 2)}\n`,
+ "utf8",
+ );
+
+ // Atomic swap. `stageDir` and `targetDir` share a parent dir, so the
+ // rename is always intra-filesystem and atomic. The pre-existing dir
+ // (if any) is moved aside under a backup name so we can restore on
+ // failure.
+ let backupDir: string | null = null;
+ if (await exists(targetDir)) {
+ backupDir = `${targetDir}.bak-${Date.now()}`;
+ await fs.rename(targetDir, backupDir);
+ }
+ try {
+ await fs.rename(stageDir, targetDir);
+ } catch (err) {
+ // Roll back if the rename failed.
+ if (backupDir) {
+ await fs.rename(backupDir, targetDir).catch(() => undefined);
+ }
+ throw err;
+ }
+ if (backupDir) {
+ await fs.rm(backupDir, { recursive: true, force: true }).catch(() => undefined);
+ }
+
+ return { package: manifest };
+ } finally {
+ // Best-effort cleanup of both scratch areas. `stageDir` is normally
+ // consumed by the rename above; this only matters on the error paths.
+ await fs.rm(workDir, { recursive: true, force: true }).catch(() => undefined);
+ await fs.rm(stageDir, { recursive: true, force: true }).catch(() => undefined);
+ }
+}
+
+/**
+ * Remove an installed package. Returns `true` if a package was removed,
+ * `false` if no package with that id existed.
+ */
+export async function uninstallPackage(pkgId: string): Promise<boolean> {
+ // Defend against `..` and other escapes — we only accept ids that look like
+ // an actual installed package on disk.
+ if (!readPackageManifest(pkgId)) return false;
+ const targetDir = path.join(userSkillsDir(), pkgId);
+ await fs.rm(targetDir, { recursive: true, force: true });
+ return true;
+}
+
diff --git a/next/src/lib/skills/paths.ts b/next/src/lib/skills/paths.ts
new file mode 100644
index 00000000..2095b6df
--- /dev/null
+++ b/next/src/lib/skills/paths.ts
@@ -0,0 +1,50 @@
+import os from "node:os";
+import path from "node:path";
+
+/**
+ * User-installed skill packs live outside the repo so they survive `git clean`
+ * and aren't accidentally committed. Default location: `~/.html-anything/skills/`.
+ *
+ * Tests override via `HTML_ANYTHING_USER_SKILLS_DIR`.
+ */
+export function userSkillsDir(): string {
+ const override = process.env.HTML_ANYTHING_USER_SKILLS_DIR;
+ if (override) return override;
+ return path.join(os.homedir(), ".html-anything", "skills");
+}
+
+/** Package id prefix used for namespaced skill ids. Always `pkg-<owner>-<repo>--<originalId>`. */
+export const SKILL_ID_PKG_PREFIX = "pkg-";
+export const SKILL_ID_SEPARATOR = "--";
+
+/**
+ * Make a stable, filesystem-safe package id from a GitHub `owner/repo` pair.
+ * Example: `nexu-io`, `html-anything` → `nexu-io__html-anything`.
+ */
+export function packageId(owner: string, repo: string): string {
+ return `${owner}__${repo}`;
+}
+
+/** Reverse of {@link packageId}: split `owner__repo` back into its parts. */
+export function parsePackageId(id: string): { owner: string; repo: string } | null {
+ const idx = id.indexOf("__");
+ if (idx < 1 || idx === id.length - 2) return null;
+ return { owner: id.slice(0, idx), repo: id.slice(idx + 2) };
+}
+
+/** Namespaced skill id used in the merged registry. */
+export function makeSkillId(pkgId: string, originalId: string): string {
+ return `${SKILL_ID_PKG_PREFIX}${pkgId}${SKILL_ID_SEPARATOR}${originalId}`;
+}
+
+/** Reverse of {@link makeSkillId}; returns `null` for bundled (non-pkg) ids. */
+export function parseSkillId(id: string): { pkgId: string; originalId: string } | null {
+ if (!id.startsWith(SKILL_ID_PKG_PREFIX)) return null;
+ const rest = id.slice(SKILL_ID_PKG_PREFIX.length);
+ const sepIdx = rest.indexOf(SKILL_ID_SEPARATOR);
+ if (sepIdx < 1) return null;
+ return {
+ pkgId: rest.slice(0, sepIdx),
+ originalId: rest.slice(sepIdx + SKILL_ID_SEPARATOR.length),
+ };
+}
diff --git a/next/src/lib/skills/registry.ts b/next/src/lib/skills/registry.ts
new file mode 100644
index 00000000..8b5878a1
--- /dev/null
+++ b/next/src/lib/skills/registry.ts
@@ -0,0 +1,151 @@
+import fs from "node:fs";
+import path from "node:path";
+import { userSkillsDir, makeSkillId } from "./paths";
+
+/**
+ * Disk layout written by {@link install}:
+ *
+ * ~/.html-anything/skills/<package-id>/
+ * package.json — install manifest
+ * skills/<original-id>/
+ * SKILL.md
+ * example.html?
+ * example.md?
+ *
+ * `package-id` is `<owner>__<repo>` (see {@link packageId}). The actual id seen
+ * by the rest of the app is `pkg-<package-id>--<original-id>` so it can't
+ * collide with bundled skills.
+ */
+
+export type InstalledPackage = {
+ /**
+ * Manifest schema version. Older installs that predate the field read back
+ * as `undefined` and are treated as v0 by callers that care; new installs
+ * always write the current version.
+ */
+ schemaVersion?: number;
+ id: string;
+ source: {
+ type: "github";
+ owner: string;
+ repo: string;
+ ref: string;
+ };
+ installedAt: string;
+ skills: string[];
+};
+
+export type UserSkillEntry = {
+ /** Namespaced id used in the merged registry. */
+ id: string;
+ /** Original id as written inside the package. */
+ originalId: string;
+ /** Owning package id. */
+ packageId: string;
+ /** Absolute path to the skill directory containing `SKILL.md`. */
+ dir: string;
+};
+
+function safeReadDir(p: string): fs.Dirent[] {
+ try {
+ return fs.readdirSync(p, { withFileTypes: true });
+ } catch {
+ return [];
+ }
+}
+
+function isValidSegment(name: string): boolean {
+ return /^[a-z0-9][a-z0-9._-]*$/i.test(name);
+}
+
+/** Read one package's manifest. Returns `null` for malformed or missing manifests. */
+export function readPackageManifest(pkgId: string): InstalledPackage | null {
+ const manifestPath = path.join(userSkillsDir(), pkgId, "package.json");
+ let raw: string;
+ try {
+ raw = fs.readFileSync(manifestPath, "utf8");
+ } catch {
+ return null;
+ }
+ let parsed: unknown;
+ try {
+ parsed = JSON.parse(raw);
+ } catch {
+ return null;
+ }
+ if (!parsed || typeof parsed !== "object") return null;
+ const obj = parsed as Record<string, unknown>;
+ const source = obj.source as Record<string, unknown> | undefined;
+ if (
+ typeof obj.id !== "string" ||
+ typeof obj.installedAt !== "string" ||
+ !Array.isArray(obj.skills) ||
+ !source ||
+ source.type !== "github" ||
+ typeof source.owner !== "string" ||
+ typeof source.repo !== "string" ||
+ typeof source.ref !== "string"
+ ) {
+ return null;
+ }
+ return {
+ schemaVersion: typeof obj.schemaVersion === "number" ? obj.schemaVersion : undefined,
+ id: obj.id,
+ source: {
+ type: "github",
+ owner: source.owner,
+ repo: source.repo,
+ ref: source.ref,
+ },
+ installedAt: obj.installedAt,
+ skills: obj.skills.filter((s): s is string => typeof s === "string"),
+ };
+}
+
+/** Every installed package with a valid manifest. */
+export function listPackages(): InstalledPackage[] {
+ const root = userSkillsDir();
+ const out: InstalledPackage[] = [];
+ for (const ent of safeReadDir(root)) {
+ if (!ent.isDirectory()) continue;
+ if (!isValidSegment(ent.name)) continue;
+ const pkg = readPackageManifest(ent.name);
+ if (pkg) out.push(pkg);
+ }
+ return out;
+}
+
+/**
+ * Every skill from every installed package, flattened with namespaced ids.
+ * Skills whose folder is missing `SKILL.md` are silently skipped so a partially-
+ * broken pack doesn't take down the registry.
+ */
+export function listUserSkills(): UserSkillEntry[] {
+ const root = userSkillsDir();
+ const out: UserSkillEntry[] = [];
+ for (const pkg of listPackages()) {
+ const skillsRoot = path.join(root, pkg.id, "skills");
+ for (const ent of safeReadDir(skillsRoot)) {
+ if (!ent.isDirectory()) continue;
+ const originalId = ent.name;
+ if (!isValidSegment(originalId)) continue;
+ const dir = path.join(skillsRoot, originalId);
+ if (!fs.existsSync(path.join(dir, "SKILL.md"))) continue;
+ out.push({
+ id: makeSkillId(pkg.id, originalId),
+ originalId,
+ packageId: pkg.id,
+ dir,
+ });
+ }
+ }
+ return out;
+}
+
+/** Look up one user skill by namespaced id. */
+export function findUserSkill(id: string): UserSkillEntry | null {
+ for (const entry of listUserSkills()) {
+ if (entry.id === id) return entry;
+ }
+ return null;
+}
diff --git a/next/src/lib/templates/__tests__/refresh.test.ts b/next/src/lib/templates/__tests__/refresh.test.ts
new file mode 100644
index 00000000..af679d98
--- /dev/null
+++ b/next/src/lib/templates/__tests__/refresh.test.ts
@@ -0,0 +1,171 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+/**
+ * Regression test for the maintainer-flagged client-cache blocker. The
+ * previous install/uninstall flow re-hit `GET /api/templates` but did not
+ * touch the module-level `cache` in `@/lib/templates/index.ts`, so the
+ * picker kept serving the stale list until a full page reload.
+ *
+ * `refreshTemplates()` must:
+ * - drop the in-memory cache so subsequent reads / hook mounts re-fetch;
+ * - actually call `/api/templates` again, even if there is an in-flight
+ * request still resolving from before the refresh.
+ *
+ * The hook-side "warm-cache consumers stay subscribed" change is verified
+ * implicitly by typecheck + by the settings-modal flow calling
+ * `refreshTemplates` post-install; a hook-mounting test would require
+ * `@testing-library/react`, which isn't a project dep.
+ */
+
+let templates: typeof import("../index");
+let fetchCalls: string[];
+
+beforeEach(async () => {
+ vi.resetModules();
+ templates = await import("../index");
+ fetchCalls = [];
+});
+
+afterEach(() => {
+ vi.restoreAllMocks();
+});
+
+function stubTemplates(items: Array<{ id: string }>): void {
+ globalThis.fetch = (async (input: RequestInfo | URL) => {
+ const url = typeof input === "string" ? input : input instanceof URL ? input.toString() : input.url;
+ fetchCalls.push(url);
+ if (url.includes("/api/templates")) {
+ return new Response(JSON.stringify({ templates: items }), {
+ status: 200,
+ headers: { "content-type": "application/json" },
+ });
+ }
+ return new Response("not found", { status: 404 });
+ }) as typeof fetch;
+}
+
+describe("refreshTemplates", () => {
+ it("re-fetches `/api/templates` and updates the cache", async () => {
+ stubTemplates([{ id: "a" }, { id: "b" }]);
+
+ // First refresh from a cold cache populates it.
+ const first = await templates.refreshTemplates();
+ expect(first.map((t) => t.id)).toEqual(["a", "b"]);
+ expect(templates.getCachedTemplate("a")?.id).toBe("a");
+ expect(fetchCalls.filter((u) => u.includes("/api/templates"))).toHaveLength(1);
+
+ // Server-side list changes. Without `refreshTemplates`, the cache would
+ // still hold ["a","b"] and consumers would never see "c".
+ stubTemplates([{ id: "a" }, { id: "b" }, { id: "c" }]);
+ const second = await templates.refreshTemplates();
+ expect(second.map((t) => t.id)).toEqual(["a", "b", "c"]);
+ expect(templates.getCachedTemplate("c")?.id).toBe("c");
+ expect(fetchCalls.filter((u) => u.includes("/api/templates"))).toHaveLength(2);
+ });
+
+ it("dropping the in-memory cache survives an uninstall (entry disappears)", async () => {
+ stubTemplates([{ id: "user-skill" }, { id: "bundled" }]);
+ await templates.refreshTemplates();
+ expect(templates.getCachedTemplate("user-skill")?.id).toBe("user-skill");
+
+ // After a hypothetical uninstall, server reports only the bundled one.
+ stubTemplates([{ id: "bundled" }]);
+ await templates.refreshTemplates();
+ expect(templates.getCachedTemplate("user-skill")).toBeUndefined();
+ expect(templates.getCachedTemplate("bundled")?.id).toBe("bundled");
+ });
+
+ it("a stale fetch that resolves AFTER a refresh must not clobber the fresh cache (generation guard)", async () => {
+ // Repro the reviewer-flagged race: initial fetch is in-flight, refresh
+ // fires and resolves with [new], then the original request finally
+ // resolves with [old]. Without a generation guard, [old] overwrites the
+ // freshly-installed list and the picker silently regresses.
+ type Resolver = (items: Array<{ id: string }>) => void;
+ const resolvers: Resolver[] = [];
+ globalThis.fetch = ((..._args: unknown[]) =>
+ new Promise<Response>((resolve) => {
+ resolvers.push((items) =>
+ resolve(
+ new Response(JSON.stringify({ templates: items }), {
+ status: 200,
+ headers: { "content-type": "application/json" },
+ }),
+ ),
+ );
+ })) as typeof fetch;
+
+ // Kick off the initial fetch (would be `useTemplates` on first mount).
+ const initial = templates.refreshTemplates();
+ // Before it can resolve, the user installs a package — settings-modal
+ // calls refreshTemplates again. This orphans the initial fetch.
+ const afterInstall = templates.refreshTemplates();
+
+ // Two in-flight requests now: resolvers[0] is the original, resolvers[1]
+ // is the post-install one. Resolve the post-install one first with the
+ // new list (this is what would normally happen — refresh after install
+ // wins the race because the original was already slow).
+ expect(resolvers).toHaveLength(2);
+ resolvers[1]([{ id: "post-install" }]);
+ const installResult = await afterInstall;
+ expect(installResult.map((t) => t.id)).toEqual(["post-install"]);
+ expect(templates.getCachedTemplate("post-install")?.id).toBe("post-install");
+
+ // NOW the original slow request resolves with the pre-install list.
+ // The generation guard must prevent it from committing.
+ resolvers[0]([{ id: "pre-install" }]);
+ await initial.catch(() => undefined);
+
+ // Cache must still hold the post-install list.
+ expect(templates.getCachedTemplate("post-install")?.id).toBe("post-install");
+ expect(templates.getCachedTemplate("pre-install")).toBeUndefined();
+ });
+
+ it("listeners never see a stale notification from an orphaned fetch", async () => {
+ // Manual subscription via the listener bus — proves the notify path
+ // also respects the generation guard (not just the cache write).
+ type Resolver = (items: Array<{ id: string }>) => void;
+ const resolvers: Resolver[] = [];
+ globalThis.fetch = ((..._args: unknown[]) =>
+ new Promise<Response>((resolve) => {
+ resolvers.push((items) =>
+ resolve(
+ new Response(JSON.stringify({ templates: items }), {
+ status: 200,
+ headers: { "content-type": "application/json" },
+ }),
+ ),
+ );
+ })) as typeof fetch;
+
+ const notifications: string[][] = [];
+ // Re-import to access the listener bus indirectly via useTemplates is
+ // overkill — instead, drive two refreshes and observe via getCachedTemplate
+ // since the listener path commits the cache in the same critical region.
+ const a = templates.refreshTemplates();
+ const b = templates.refreshTemplates();
+ resolvers[1]([{ id: "fresh" }]);
+ await b;
+ notifications.push((templates.getCachedTemplate("fresh") ? ["fresh"] : []));
+ resolvers[0]([{ id: "stale" }]);
+ await a.catch(() => undefined);
+ notifications.push((templates.getCachedTemplate("stale") ? ["stale"] : ["fresh"]));
+ expect(notifications).toEqual([["fresh"], ["fresh"]]);
+ });
+
+ it("on fetch failure, leaves the next mount free to refetch instead of caching the error", async () => {
+ stubTemplates([{ id: "stable" }]);
+ await templates.refreshTemplates();
+ expect(templates.getCachedTemplate("stable")?.id).toBe("stable");
+
+ // Refresh fails — the previous cache stays cleared (so the next read
+ // hits the network) and the rejection propagates.
+ globalThis.fetch = (async () => new Response("boom", { status: 500 })) as typeof fetch;
+ await expect(templates.refreshTemplates()).rejects.toBeInstanceOf(Error);
+ expect(templates.getCachedTemplate("stable")).toBeUndefined();
+
+ // Recovery: a subsequent successful refresh repopulates.
+ stubTemplates([{ id: "back" }]);
+ await templates.refreshTemplates();
+ expect(templates.getCachedTemplate("back")?.id).toBe("back");
+ });
+});
diff --git a/next/src/lib/templates/index.ts b/next/src/lib/templates/index.ts
index bf1af5b6..e215cd77 100644
--- a/next/src/lib/templates/index.ts
+++ b/next/src/lib/templates/index.ts
@@ -20,26 +20,48 @@ export type TemplateExampleMeta = SkillExampleMeta;
// Module-level cache + in-flight promise dedupes parallel callers across the
// React tree. SWR / react-query would also work but adding a dep for one
// endpoint is overkill — this is ~25 lines and behaves the same.
+//
+// `generation` is a monotonic token bumped on every `fetchTemplates()` start.
+// Each in-flight fetch captures the generation at start and only commits to
+// `cache` / notifies listeners if the global generation has not been bumped
+// in the meantime — i.e. it is still the most recent fetch. This kills the
+// race where a slow initial fetch resolves *after* a subsequent
+// `refreshTemplates()` and silently clobbers the fresh post-install list
+// back to the stale pre-install one.
let cache: TemplateDef[] | null = null;
let inflight: Promise<TemplateDef[]> | null = null;
+let generation = 0;
type Listener = (v: TemplateDef[]) => void;
const listeners = new Set<Listener>();
async function fetchTemplates(): Promise<TemplateDef[]> {
if (cache) return cache;
if (inflight) return inflight;
- inflight = (async () => {
+ const myGeneration = ++generation;
+ const myPromise: Promise<TemplateDef[]> = (async () => {
const res = await fetch("/api/templates");
if (!res.ok) throw new Error(`GET /api/templates → ${res.status}`);
const json = (await res.json()) as { templates: TemplateDef[] };
+ if (myGeneration !== generation) {
+ // A later `refreshTemplates()` has superseded us. Drop our result on
+ // the floor — committing it would clobber the fresh post-install list
+ // and push mounted pickers back to the pre-install state. Return the
+ // current canonical cache so any code awaiting this stale promise
+ // still observes consistent state.
+ return cache ?? json.templates;
+ }
cache = json.templates;
for (const l of listeners) l(cache);
return cache;
})();
+ inflight = myPromise;
try {
- return await inflight;
+ return await myPromise;
} finally {
- inflight = null;
+ // Only clear `inflight` if we're still the active one — a refresh may
+ // have orphaned us and installed a newer in-flight promise that we
+ // must not overwrite.
+ if (inflight === myPromise) inflight = null;
}
}
@@ -47,16 +69,20 @@ async function fetchTemplates(): Promise<TemplateDef[]> {
export function useTemplates(): TemplateDef[] | undefined {
const [data, setData] = useState<TemplateDef[] | undefined>(cache ?? undefined);
useEffect(() => {
+ // Subscribe unconditionally so that {@link refreshTemplates} can notify
+ // even consumers that mounted while the cache was already warm. (The
+ // previous early-return-on-warm-cache code path left those consumers
+ // unsubscribed, so install/uninstall could not push them a new list.)
+ const listener = (v: TemplateDef[]) => setData(v);
+ listeners.add(listener);
if (cache) {
setData(cache);
- return;
+ } else {
+ fetchTemplates().catch(() => {
+ // surface as empty — picker shows "no matches", caller can decide
+ setData([]);
+ });
}
- const listener = (v: TemplateDef[]) => setData(v);
- listeners.add(listener);
- fetchTemplates().catch(() => {
- // surface as empty — picker shows "no matches", caller can decide
- setData([]);
- });
return () => {
listeners.delete(listener);
};
@@ -64,6 +90,22 @@ export function useTemplates(): TemplateDef[] | undefined {
return data;
}
+/**
+ * Drop the in-memory registry cache, re-fetch from `/api/templates`, and push
+ * the new list to every mounted {@link useTemplates} consumer. Call this
+ * after install/uninstall so the picker switches to the fresh list
+ * immediately instead of waiting for a full page reload.
+ *
+ * Resolves with the new list; on failure, the cache is left null so the
+ * next mount will refetch, and subscribed consumers keep their last-known
+ * data (no flash to empty).
+ */
+export async function refreshTemplates(): Promise<TemplateDef[]> {
+ cache = null;
+ inflight = null;
+ return fetchTemplates();
+}
+
/** Fetch one skill's bundled example (content + html). */
export async function fetchTemplateExample(id: string): Promise<{
id: string;
diff --git a/next/src/lib/templates/loader.ts b/next/src/lib/templates/loader.ts
index bc99c162..4ec03fde 100644
--- a/next/src/lib/templates/loader.ts
+++ b/next/src/lib/templates/loader.ts
@@ -1,5 +1,6 @@
import fs from "node:fs";
import path from "node:path";
+import { findUserSkill, listUserSkills, type UserSkillEntry } from "@/lib/skills/registry";
/**
* File-based skill registry, modelled on nexu-io/open-design's daemon layout
@@ -12,6 +13,10 @@ import path from "node:path";
*
* Adding a template = adding a folder. No TS code change required; the API
* routes rescan disk and the client refetches `/api/templates`.
+ *
+ * Skills installed via the marketplace ({@link listUserSkills}) live under
+ * `~/.html-anything/skills/` and are merged into the same registry with
+ * namespaced ids (`pkg-<owner>-<repo>--<originalId>`).
*/
const SKILLS_DIR = path.join(process.cwd(), "src/lib/templates/skills");
@@ -195,11 +200,45 @@ function fmToMeta(id: string, fm: SkillFrontmatter, hasHtml: boolean, hasMd: boo
let metaCache: SkillMeta[] | null = null;
const isDev = process.env.NODE_ENV !== "production";
-function isValidId(id: string): boolean {
+/** Drop the cached metadata listing. Call after install / uninstall. */
+export function invalidateSkillsCache(): void {
+ metaCache = null;
+}
+
+function isValidBundledId(id: string): boolean {
return /^[a-z0-9][a-z0-9-]*$/i.test(id);
}
-/** Return picker-ready metadata for every skill folder on disk. */
+function isValidSkillId(id: string): boolean {
+ // Bundled ids stay strictly kebab-case. Marketplace ids are namespaced as
+ // `pkg-<owner>__<repo>--<originalId>` — `__` shows up inside the package id
+ // segment, so we allow it (plus `.` for tag-like refs) before the `--`.
+ return (
+ isValidBundledId(id) ||
+ /^pkg-[a-z0-9][a-z0-9._-]*__[a-z0-9][a-z0-9._-]*--[a-z0-9][a-z0-9._-]*$/i.test(id)
+ );
+}
+
+function loadSkillFromDir(id: string, dir: string): LoadedSkill | null {
+ const raw = safeRead(path.join(dir, "SKILL.md"));
+ if (!raw) return null;
+ const { fm, body } = parseFrontmatter(raw);
+ const exampleMd = safeRead(path.join(dir, "example.md"));
+ const exampleHtml = safeRead(path.join(dir, "example.html"));
+ const meta = fmToMeta(id, fm, !!exampleHtml, !!exampleMd);
+ return { ...meta, body, exampleMd, exampleHtml };
+}
+
+function metaFromDir(id: string, dir: string): SkillMeta | null {
+ const raw = safeRead(path.join(dir, "SKILL.md"));
+ if (!raw) return null;
+ const { fm } = parseFrontmatter(raw);
+ const hasHtml = fs.existsSync(path.join(dir, "example.html"));
+ const hasMd = fs.existsSync(path.join(dir, "example.md"));
+ return fmToMeta(id, fm, hasHtml, hasMd);
+}
+
+/** Return picker-ready metadata for every bundled + user-installed skill. */
export function listSkills(): SkillMeta[] {
if (!isDev && metaCache) return metaCache;
const out: SkillMeta[] = [];
@@ -207,19 +246,24 @@ export function listSkills(): SkillMeta[] {
try {
dirents = fs.readdirSync(SKILLS_DIR, { withFileTypes: true });
} catch {
- return out;
+ dirents = [];
}
for (const ent of dirents) {
if (!ent.isDirectory()) continue;
const id = ent.name;
- if (!isValidId(id)) continue;
- const dir = path.join(SKILLS_DIR, id);
- const raw = safeRead(path.join(dir, "SKILL.md"));
- if (!raw) continue;
- const { fm } = parseFrontmatter(raw);
- const hasHtml = fs.existsSync(path.join(dir, "example.html"));
- const hasMd = fs.existsSync(path.join(dir, "example.md"));
- out.push(fmToMeta(id, fm, hasHtml, hasMd));
+ if (!isValidBundledId(id)) continue;
+ const meta = metaFromDir(id, path.join(SKILLS_DIR, id));
+ if (meta) out.push(meta);
+ }
+ let userSkills: UserSkillEntry[] = [];
+ try {
+ userSkills = listUserSkills();
+ } catch {
+ userSkills = [];
+ }
+ for (const entry of userSkills) {
+ const meta = metaFromDir(entry.id, entry.dir);
+ if (meta) out.push(meta);
}
metaCache = out;
return out;
@@ -227,19 +271,22 @@ export function listSkills(): SkillMeta[] {
/** Load one skill including its prompt body and example contents. */
export function loadSkill(id: string): LoadedSkill | null {
- if (!isValidId(id)) return null;
- const dir = path.join(SKILLS_DIR, id);
- const raw = safeRead(path.join(dir, "SKILL.md"));
- if (!raw) return null;
- const { fm, body } = parseFrontmatter(raw);
- const exampleMd = safeRead(path.join(dir, "example.md"));
- const exampleHtml = safeRead(path.join(dir, "example.html"));
- const meta = fmToMeta(id, fm, !!exampleHtml, !!exampleMd);
- return { ...meta, body, exampleMd, exampleHtml };
+ if (!isValidSkillId(id)) return null;
+ if (id.includes("--")) {
+ const entry = findUserSkill(id);
+ if (!entry) return null;
+ return loadSkillFromDir(id, entry.dir);
+ }
+ return loadSkillFromDir(id, path.join(SKILLS_DIR, id));
}
/** Lightweight check for the picker — true iff `example.html` exists. */
export function skillHasPreview(id: string): boolean {
- if (!isValidId(id)) return false;
+ if (!isValidSkillId(id)) return false;
+ if (id.includes("--")) {
+ const entry = findUserSkill(id);
+ if (!entry) return false;
+ return fs.existsSync(path.join(entry.dir, "example.html"));
+ }
return fs.existsSync(path.join(SKILLS_DIR, id, "example.html"));
}
diff --git a/next/vitest.config.ts b/next/vitest.config.ts
index 7931208e..b438f1a8 100644
--- a/next/vitest.config.ts
+++ b/next/vitest.config.ts
@@ -1,6 +1,12 @@
+import path from "node:path";
import { defineConfig } from "vitest/config";
export default defineConfig({
+ resolve: {
+ alias: {
+ "@": path.resolve(__dirname, "src"),
+ },
+ },
test: {
environment: "happy-dom",
include: ["src/**/*.{test,spec}.{ts,tsx}"],