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.
TypeScript agent-skillsagentic-aiai-agentsai-videobyokclaude-codecodexdeepseek-harnessdsh-plugingenerative-ailocal-firstmcpmotionmotion-graphicsmultimodalopenmotionreverse-engineeringvideo-editingvideo-generationworkbuddy
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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsxindex 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.tsindex 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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: boolet 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.tsindex 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}"],