@intent-systems/nexus 2026.1.5-3

package/dist/cli/skills-hub-cli.js

@@ -0,0 +1,1093 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import os from "node:os";
+import crypto from "node:crypto";
+import { Readable } from "node:stream";
+import { pipeline } from "node:stream/promises";
+import { fileTypeFromFile } from "file-type";
+import { buildWorkspaceSkillStatus } from "../agents/skills-status.js";
+import { getSkillMetadata, hasBinary, loadWorkspaceSkillEntries, } from "../agents/skills.js";
+import { DEFAULT_AGENT_WORKSPACE_DIR } from "../agents/workspace.js";
+import { generateSkillManifest, writeSkillManifest } from "../commands/skills-manifest.js";
+import { loadConfig } from "../config/config.js";
+import { runCommandWithTimeout } from "../process/exec.js";
+import { listCredentialEntries, resolveCredentialValue, } from "../credentials/store.js";
+import { MANAGED_SKILLS_DIR, resolveUserPath } from "../utils.js";
+function getHubBaseUrl() {
+    return (process.env.NEXUS_HUB_URL ||
+        process.env.NEXUS_WEBSITE_URL ||
+        "https://getnexus.sh");
+}
+function normalizeSkillKey(value) {
+    return value.trim().toLowerCase();
+}
+function normalizeQuery(query) {
+    return query
+        .toLowerCase()
+        .split(/\s+/)
+        .map((token) => token.trim())
+        .filter(Boolean);
+}
+function normalizeStringList(value) {
+    if (Array.isArray(value)) {
+        return value.map((entry) => String(entry).trim()).filter(Boolean);
+    }
+    if (typeof value === "string") {
+        return value
+            .split(",")
+            .map((entry) => entry.trim())
+            .filter(Boolean);
+    }
+    return [];
+}
+function normalizeHubDependencies(value) {
+    const raw = value && typeof value === "object" ? value : {};
+    return {
+        dependencies: normalizeStringList(raw.dependencies),
+        tools: normalizeStringList(raw.tools),
+        connectors: normalizeStringList(raw.connectors),
+    };
+}
+function parseFrontmatter(content) {
+    const trimmed = content.trimStart();
+    if (!trimmed.startsWith("---")) {
+        return { frontmatter: {}, body: content };
+    }
+    const lines = trimmed.split("\n");
+    let endIndex = -1;
+    for (let i = 1; i < lines.length; i += 1) {
+        if (lines[i].trim() === "---") {
+            endIndex = i;
+            break;
+        }
+    }
+    if (endIndex === -1) {
+        return { frontmatter: {}, body: content };
+    }
+    const frontLines = lines.slice(1, endIndex);
+    const body = lines.slice(endIndex + 1).join("\n");
+    const frontmatter = {};
+    let currentListKey = null;
+    for (const line of frontLines) {
+        const trimmedLine = line.trim();
+        if (!trimmedLine || trimmedLine.startsWith("#")) {
+            continue;
+        }
+        const listMatch = line.match(/^\s*-\s+(.+)$/);
+        if (listMatch && currentListKey) {
+            const existing = frontmatter[currentListKey];
+            if (!Array.isArray(existing)) {
+                frontmatter[currentListKey] = [];
+            }
+            frontmatter[currentListKey].push(stripQuotes(listMatch[1].trim()));
+            continue;
+        }
+        const match = line.match(/^([A-Za-z0-9_-]+):\s*(.*)$/);
+        if (!match) {
+            currentListKey = null;
+            continue;
+        }
+        const key = match[1];
+        const rawValue = match[2].trim();
+        if (!rawValue) {
+            frontmatter[key] = [];
+            currentListKey = key;
+            continue;
+        }
+        currentListKey = null;
+        frontmatter[key] = parseScalarValue(rawValue);
+    }
+    return { frontmatter, body };
+}
+function stripQuotes(value) {
+    if ((value.startsWith('"') && value.endsWith('"')) ||
+        (value.startsWith("'") && value.endsWith("'"))) {
+        return value.slice(1, -1);
+    }
+    return value;
+}
+function parseScalarValue(value) {
+    const cleaned = stripQuotes(value);
+    if (cleaned === "true")
+        return true;
+    if (cleaned === "false")
+        return false;
+    if (cleaned.startsWith("{") || cleaned.startsWith("[")) {
+        try {
+            return JSON.parse(cleaned);
+        }
+        catch {
+            return cleaned;
+        }
+    }
+    return cleaned;
+}
+function normalizeMetadata(value) {
+    if (!value)
+        return {};
+    if (typeof value === "object") {
+        return value;
+    }
+    if (typeof value === "string") {
+        try {
+            const parsed = JSON.parse(value);
+            if (parsed && typeof parsed === "object") {
+                return parsed;
+            }
+        }
+        catch {
+            return {};
+        }
+    }
+    return {};
+}
+function resolveCapabilities(entry) {
+    const candidates = [
+        entry.capabilities,
+        entry.provides,
+        entry.metadata?.nexus
+            ? entry.metadata.nexus.provides
+            : undefined,
+        entry.metadata?.nexus
+            ? entry.metadata.nexus.capabilities
+            : undefined,
+        entry.metadata?.capabilities,
+    ];
+    for (const candidate of candidates) {
+        const parsed = normalizeStringList(candidate);
+        if (parsed.length > 0) {
+            return parsed;
+        }
+    }
+    return [];
+}
+function extractExcerpt(body, max = 700) {
+    const trimmed = body.trim();
+    if (!trimmed)
+        return "";
+    if (trimmed.length <= max)
+        return trimmed;
+    return `${trimmed.slice(0, max)}…`;
+}
+function scoreTextMatch(query, name, description) {
+    if (!query)
+        return 1;
+    const q = query.toLowerCase().trim();
+    const nameLower = name.toLowerCase();
+    const descLower = description.toLowerCase();
+    if (nameLower.includes(q))
+        return 100;
+    if (descLower.includes(q))
+        return 40;
+    const tokens = normalizeQuery(query);
+    let score = 0;
+    for (const token of tokens) {
+        if (nameLower.includes(token))
+            score += 20;
+        if (descLower.includes(token))
+            score += 8;
+    }
+    return score;
+}
+function extractDependencies(metadata) {
+    const requires = metadata?.requires ?? {};
+    return {
+        bins: requires.bins ?? [],
+        anyBins: requires.anyBins ?? [],
+        env: requires.env ?? [],
+        config: requires.config ?? [],
+        credentials: requires.credentials ?? [],
+        install: metadata?.install ?? [],
+    };
+}
+function manifestToMetadata(manifest) {
+    if (!manifest || typeof manifest !== "object")
+        return null;
+    const raw = manifest;
+    if (raw.nexus && typeof raw.nexus === "object")
+        return raw.nexus;
+    if (raw.metadata && typeof raw.metadata === "object") {
+        const nested = raw.metadata;
+        if (nested.nexus && typeof nested.nexus === "object")
+            return nested.nexus;
+        if (typeof nested.nexus === "string") {
+            try {
+                return JSON.parse(nested.nexus);
+            }
+            catch {
+                return null;
+            }
+        }
+    }
+    return null;
+}
+function summarizeInstallOptions(install) {
+    return install.map((entry) => ({
+        kind: entry.kind,
+        label: entry.label ?? "",
+    }));
+}
+async function fetchHubSkills(query, opts) {
+    const baseUrl = getHubBaseUrl();
+    const url = new URL("/api/skills/search", baseUrl);
+    url.searchParams.set("q", query);
+    url.searchParams.set("limit", String(opts.limit));
+    url.searchParams.set("includeManifest", "true");
+    if (opts.type)
+        url.searchParams.set("type", opts.type);
+    if (opts.capability)
+        url.searchParams.set("capability", opts.capability);
+    const res = await fetch(url);
+    if (!res.ok) {
+        const body = await res.text().catch(() => "");
+        throw new Error(`Hub search failed (${res.status}): ${body}`);
+    }
+    const data = (await res.json());
+    return data.skills ?? [];
+}
+async function fetchHubSkillDetails(slug) {
+    const baseUrl = getHubBaseUrl();
+    const url = new URL(`/api/skills/${encodeURIComponent(slug)}`, baseUrl);
+    const res = await fetch(url);
+    if (!res.ok) {
+        const body = await res.text().catch(() => "");
+        throw new Error(`Hub skill lookup failed (${res.status}): ${body}`);
+    }
+    const data = (await res.json());
+    if (!data.skill?.slug || !data.skill?.name) {
+        throw new Error("Hub skill lookup failed (invalid response)");
+    }
+    return {
+        slug: data.skill.slug,
+        name: data.skill.name,
+        dependencies: normalizeHubDependencies(data.skill.dependencies),
+    };
+}
+async function downloadSkillArtifact(slug) {
+    const baseUrl = getHubBaseUrl();
+    const url = new URL(`/api/skills/${encodeURIComponent(slug)}/download`, baseUrl);
+    const res = await fetch(url, { method: "POST" });
+    if (!res.ok) {
+        const body = await res.text().catch(() => "");
+        throw new Error(`Download request failed (${res.status}): ${body}`);
+    }
+    return (await res.json());
+}
+function slugToDirName(slug) {
+    return slug.replace(/[\\/]/g, "__");
+}
+function dirNameToSlug(dirName) {
+    return dirName.split("__").join("/");
+}
+async function ensureDir(dir) {
+    await fs.mkdir(dir, { recursive: true });
+}
+async function loadManagedSkillSlugs(managedSkillsDir) {
+    const slugs = new Set();
+    const managedDir = path.join(managedSkillsDir, "managed");
+    let entries = [];
+    try {
+        entries = await fs.readdir(managedDir, { withFileTypes: true });
+    }
+    catch {
+        return slugs;
+    }
+    for (const entry of entries) {
+        if (!entry.isDirectory())
+            continue;
+        const slug = dirNameToSlug(entry.name);
+        if (!slug)
+            continue;
+        slugs.add(normalizeSkillKey(slug));
+    }
+    return slugs;
+}
+function isSkillInstalled(id, installed) {
+    const key = normalizeSkillKey(id);
+    return installed.names.has(key) || installed.slugs.has(key);
+}
+async function streamToFile(res, outPath) {
+    if (!res.body) {
+        throw new Error("Download response had no body");
+    }
+    await ensureDir(path.dirname(outPath));
+    const stream = Readable.fromWeb(res.body);
+    const handle = await fs.open(outPath, "w");
+    try {
+        await pipeline(stream, handle.createWriteStream());
+    }
+    finally {
+        await handle.close();
+    }
+}
+async function sha256File(filePath) {
+    const data = await fs.readFile(filePath);
+    return crypto.createHash("sha256").update(data).digest("hex");
+}
+async function extractArchive(artifactPath, destDir) {
+    let ext = "";
+    try {
+        const type = await fileTypeFromFile(artifactPath);
+        ext = type?.ext ?? "";
+    }
+    catch {
+        ext = "";
+    }
+    await ensureDir(destDir);
+    if (ext === "zip" || artifactPath.endsWith(".zip")) {
+        if (!hasBinary("unzip")) {
+            throw new Error("Missing 'unzip' binary. Install unzip or extract manually.");
+        }
+        const result = await runCommandWithTimeout(["unzip", "-q", artifactPath, "-d", destDir], 300_000);
+        if (result.code !== 0) {
+            throw new Error(result.stderr || result.stdout || "Unzip failed");
+        }
+        return;
+    }
+    if (!hasBinary("tar")) {
+        throw new Error("Missing 'tar' binary. Install tar or extract manually.");
+    }
+    const result = await runCommandWithTimeout(["tar", "-xf", artifactPath, "-C", destDir], 300_000);
+    if (result.code !== 0) {
+        throw new Error(result.stderr || result.stdout || "Tar extraction failed");
+    }
+}
+async function normalizeSkillRoot(destDir) {
+    const skillPath = path.join(destDir, "SKILL.md");
+    try {
+        await fs.access(skillPath);
+        return;
+    }
+    catch {
+        // continue
+    }
+    const entries = await fs.readdir(destDir, { withFileTypes: true });
+    if (entries.length !== 1)
+        return;
+    const only = entries[0];
+    if (!only.isDirectory())
+        return;
+    const nested = path.join(destDir, only.name);
+    const nestedSkill = path.join(nested, "SKILL.md");
+    try {
+        await fs.access(nestedSkill);
+    }
+    catch {
+        return;
+    }
+    const nestedEntries = await fs.readdir(nested);
+    for (const entry of nestedEntries) {
+        await fs.rename(path.join(nested, entry), path.join(destDir, entry));
+    }
+    await fs.rm(nested, { recursive: true, force: true });
+}
+async function resolveHubDependencyPlan(slug, installed, getDetails, onMissing) {
+    const plan = [];
+    const visiting = new Set();
+    const visited = new Set();
+    const addDependency = async (depSlug) => {
+        const key = normalizeSkillKey(depSlug);
+        if (!key || isSkillInstalled(depSlug, installed) || visited.has(key)) {
+            return;
+        }
+        if (visiting.has(key)) {
+            return;
+        }
+        visiting.add(key);
+        let details;
+        try {
+            details = await getDetails(depSlug);
+        }
+        catch {
+            visiting.delete(key);
+            if (onMissing)
+                onMissing(depSlug);
+            return;
+        }
+        const deps = [
+            ...details.dependencies.tools,
+            ...details.dependencies.connectors,
+        ];
+        for (const dep of deps) {
+            await addDependency(dep);
+        }
+        visiting.delete(key);
+        visited.add(key);
+        plan.push(details.slug);
+    };
+    let root;
+    try {
+        root = await getDetails(slug);
+    }
+    catch {
+        if (onMissing)
+            onMissing(slug);
+        return plan;
+    }
+    const rootDeps = [
+        ...root.dependencies.tools,
+        ...root.dependencies.connectors,
+    ];
+    for (const dep of rootDeps) {
+        await addDependency(dep);
+    }
+    return plan;
+}
+async function resolveSkillFile(inputPath) {
+    const stats = await fs.stat(inputPath);
+    if (stats.isFile()) {
+        return { skillDir: path.dirname(inputPath), skillFile: inputPath };
+    }
+    const skillFile = path.join(inputPath, "SKILL.md");
+    return { skillDir: inputPath, skillFile };
+}
+async function createTarball(sourceDir, outPath) {
+    if (!hasBinary("tar")) {
+        throw new Error("Missing 'tar' binary. Install tar to publish skills.");
+    }
+    const result = await runCommandWithTimeout(["tar", "-czf", outPath, "-C", sourceDir, "."], 300_000);
+    if (result.code !== 0) {
+        throw new Error(result.stderr || result.stdout || "Tar failed");
+    }
+}
+async function computeArtifactInfo(filePath) {
+    const hash = await sha256File(filePath);
+    const stats = await fs.stat(filePath);
+    return { sha256: hash, bytes: stats.size };
+}
+async function resolveHubToken(input) {
+    if (input && input.trim())
+        return input.trim();
+    const envToken = process.env.NEXUS_HUB_TOKEN ||
+        process.env.NEXUS_WEBSITE_TOKEN ||
+        process.env.SKILLS_HUB_API_TOKEN;
+    if (envToken?.trim())
+        return envToken.trim();
+    const entries = await listCredentialEntries();
+    const candidates = entries.filter((entry) => entry.service === "nexus-hub" || entry.service === "nexus-cloud");
+    for (const entry of candidates) {
+        const resolved = await resolveCredentialValue(entry.record);
+        if (resolved?.value) {
+            return resolved.value;
+        }
+    }
+    return null;
+}
+function buildManifestPayload(input) {
+    const { frontmatter, body, overrides } = input;
+    const metadata = normalizeMetadata(frontmatter.metadata);
+    const nexusMeta = metadata.nexus && typeof metadata.nexus === "object"
+        ? metadata.nexus
+        : {};
+    const name = overrides.name ||
+        (typeof frontmatter.name === "string" ? frontmatter.name : "") ||
+        "";
+    const description = overrides.description ||
+        (typeof frontmatter.description === "string" ? frontmatter.description : "") ||
+        "";
+    const type = overrides.type ||
+        (typeof frontmatter.type === "string" ? frontmatter.type : "") ||
+        (typeof nexusMeta.type === "string" ? nexusMeta.type : "") ||
+        "";
+    const version = overrides.version ||
+        (typeof frontmatter.version === "string" ? frontmatter.version : "") ||
+        "";
+    const license = overrides.license ||
+        (typeof frontmatter.license === "string" ? frontmatter.license : "") ||
+        "";
+    const repository = overrides.repository ||
+        (typeof frontmatter.repository === "string" ? frontmatter.repository : "") ||
+        (typeof frontmatter.repo === "string" ? frontmatter.repo : "") ||
+        "";
+    const homepage = overrides.homepage ||
+        (typeof frontmatter.homepage === "string" ? frontmatter.homepage : "") ||
+        (typeof frontmatter.website === "string" ? frontmatter.website : "") ||
+        "";
+    const baseManifest = {
+        ...frontmatter,
+        name,
+        description,
+        type,
+        version,
+        license,
+        ...(repository ? { repository } : {}),
+        ...(homepage ? { homepage } : {}),
+    };
+    const manifestEntry = {
+        ...baseManifest,
+        metadata: {
+            ...metadata,
+            nexus: {
+                ...nexusMeta,
+                ...(type ? { type } : {}),
+            },
+        },
+    };
+    const capabilityCandidates = {
+        ...manifestEntry,
+        capabilities: overrides.capabilities ?? manifestEntry.capabilities,
+    };
+    const capabilities = resolveCapabilities(capabilityCandidates);
+    if (capabilities.length > 0) {
+        manifestEntry.capabilities = capabilities;
+        const nexus = manifestEntry.metadata;
+        nexus.nexus = {
+            ...(nexus.nexus ?? {}),
+            provides: capabilities,
+        };
+    }
+    const readmeExcerpt = extractExcerpt(body || description);
+    return {
+        name,
+        description,
+        type,
+        version,
+        license,
+        repository,
+        homepage,
+        capabilities,
+        manifest: manifestEntry,
+        readmeExcerpt,
+    };
+}
+async function installHubSkill(params) {
+    const dirName = slugToDirName(params.slug);
+    const destDir = path.join(params.managedDir, dirName);
+    try {
+        if (!params.force) {
+            await fs.access(destDir);
+            if (params.allowSkip) {
+                return { installed: false, destDir };
+            }
+            throw new Error(`Skill already installed at ${destDir}. Use --force to overwrite.`);
+        }
+        await fs.rm(destDir, { recursive: true, force: true });
+    }
+    catch (err) {
+        if (err.code !== "ENOENT") {
+            throw err;
+        }
+    }
+    const download = await downloadSkillArtifact(params.slug);
+    if (!download.downloadUrl || !download.artifactSha256) {
+        throw new Error("Download URL missing from hub response");
+    }
+    const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), "nexus-skill-"));
+    const artifactPath = path.join(tmpDir, "artifact.bin");
+    const downloadHeaders = {};
+    if (download.cloudToken) {
+        downloadHeaders.authorization = `Bearer ${download.cloudToken}`;
+    }
+    const res = await fetch(download.downloadUrl, { headers: downloadHeaders });
+    if (!res.ok) {
+        const body = await res.text().catch(() => "");
+        throw new Error(`Download failed (${res.status}): ${body}`);
+    }
+    await streamToFile(res, artifactPath);
+    const hash = await sha256File(artifactPath);
+    if (hash !== download.artifactSha256) {
+        throw new Error(`Checksum mismatch (expected ${download.artifactSha256}, got ${hash})`);
+    }
+    await extractArchive(artifactPath, destDir);
+    await normalizeSkillRoot(destDir);
+    const manifest = await generateSkillManifest(MANAGED_SKILLS_DIR, params.userSkillsDir);
+    await writeSkillManifest(manifest);
+    return { installed: true, destDir };
+}
+export function registerSkillsHubCommand(program) {
+    const skills = program.command("skills").description("Search and install skills from the Nexus Hub");
+    skills
+        .command("search <query>")
+        .description("Search local skills and the Nexus Hub")
+        .option("--type <type>", "Filter by type (guide|tool|connector)")
+        .option("--capability <cap>", "Filter by capability")
+        .option("--limit <n>", "Hub results to return", (value) => Number(value))
+        .option("--local-only", "Only search local skills")
+        .option("--hub-only", "Only search the hub")
+        .option("--suggest", "Suggest up to 3 uninstalled hub skills")
+        .option("--json", "Output JSON")
+        .action(async (query, opts) => {
+        const suggestMode = Boolean(opts.suggest);
+        const limitRaw = Number(opts.limit);
+        const hubLimit = Number.isFinite(limitRaw) && limitRaw > 0
+            ? limitRaw
+            : suggestMode
+                ? 3
+                : 10;
+        const cfg = loadConfig();
+        const workspaceDir = resolveUserPath(cfg.agent?.workspace ?? DEFAULT_AGENT_WORKSPACE_DIR);
+        const managedSkillsDir = MANAGED_SKILLS_DIR;
+        const status = buildWorkspaceSkillStatus(workspaceDir, {
+            config: cfg,
+            managedSkillsDir,
+        });
+        const metadataEntries = loadWorkspaceSkillEntries(workspaceDir, {
+            config: cfg,
+            managedSkillsDir,
+        });
+        const metadataByName = new Map(metadataEntries.map((entry) => [entry.skill.name, getSkillMetadata(entry)]));
+        const installedNames = new Set(metadataEntries.map((entry) => normalizeSkillKey(entry.skill.name)));
+        const installedSlugs = await loadManagedSkillSlugs(managedSkillsDir);
+        const installedIndex = {
+            names: installedNames,
+            slugs: installedSlugs,
+        };
+        const localMatches = status.skills
+            .map((skill) => {
+            const metadata = metadataByName.get(skill.name);
+            let score = scoreTextMatch(query, skill.name, skill.description);
+            if (opts.type && metadata?.type && metadata.type !== opts.type) {
+                score = 0;
+            }
+            if (opts.capability) {
+                const provides = metadata?.provides ?? [];
+                if (!provides.includes(String(opts.capability))) {
+                    score = 0;
+                }
+            }
+            const deps = extractDependencies(metadata ?? undefined);
+            return {
+                name: skill.name,
+                description: skill.description,
+                type: metadata?.type,
+                installed: true,
+                eligible: skill.eligible,
+                missing: {
+                    bins: skill.missing.bins,
+                    env: skill.missing.env,
+                    config: skill.missing.config,
+                    os: skill.missing.os,
+                    credentials: deps.credentials,
+                },
+                install: summarizeInstallOptions(skill.install),
+                provides: metadata?.provides ?? [],
+                score,
+            };
+        })
+            .filter((skill) => skill.score > 0)
+            .sort((a, b) => b.score - a.score)
+            .map(({ score, ...rest }) => rest);
+        let hubMatches = [];
+        if (!opts.localOnly) {
+            try {
+                const hubSkills = await fetchHubSkills(query, {
+                    limit: Math.max(1, hubLimit),
+                    type: opts.type,
+                    capability: opts.capability,
+                });
+                hubMatches = hubSkills.map((skill) => {
+                    const metadata = manifestToMetadata(skill.manifest);
+                    const deps = extractDependencies(metadata ?? undefined);
+                    return {
+                        slug: skill.slug,
+                        name: skill.name,
+                        description: skill.description,
+                        type: skill.type,
+                        version: skill.version ?? null,
+                        capabilities: skill.capabilities ?? [],
+                        installed: installedIndex.names.has(normalizeSkillKey(skill.name)) ||
+                            installedIndex.slugs.has(normalizeSkillKey(skill.slug)),
+                        verified: Boolean(skill.verified),
+                        dependencies: deps,
+                    };
+                });
+            }
+            catch (err) {
+                if (opts.json) {
+                    console.log(JSON.stringify({
+                        query,
+                        local: localMatches,
+                        hub: [],
+                        error: err instanceof Error ? err.message : String(err),
+                    }, null, 2));
+                    return;
+                }
+                console.error(`Hub search failed: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+        if (suggestMode) {
+            const maxSuggestions = Math.min(3, hubLimit);
+            const suggestions = hubMatches
+                .filter((skill) => !skill.installed)
+                .slice(0, maxSuggestions);
+            const suggestionDetails = await Promise.all(suggestions.map(async (skill) => {
+                try {
+                    const details = await fetchHubSkillDetails(skill.slug);
+                    return { skill, dependencies: details.dependencies };
+                }
+                catch {
+                    return {
+                        skill,
+                        dependencies: { dependencies: [], tools: [], connectors: [] },
+                    };
+                }
+            }));
+            if (opts.json) {
+                console.log(JSON.stringify({
+                    query,
+                    suggestions: suggestionDetails.map(({ skill, dependencies }) => ({
+                        slug: skill.slug,
+                        name: skill.name,
+                        description: skill.description,
+                        type: skill.type,
+                        version: skill.version ?? null,
+                        verified: Boolean(skill.verified),
+                        dependencies,
+                        installCommand: `nexus skills install ${skill.slug}`,
+                        installWithDepsCommand: `nexus skills install ${skill.slug} --with-deps`,
+                    })),
+                    hubUrl: getHubBaseUrl(),
+                }, null, 2));
+                return;
+            }
+            console.log(`\nSuggested hub skills (${suggestionDetails.length})\n`);
+            if (suggestionDetails.length === 0) {
+                console.log("  (none)\n");
+                return;
+            }
+            for (const { skill, dependencies } of suggestionDetails) {
+                const verified = skill.verified ? "verified" : "unverified";
+                console.log(`  🌐 ${skill.slug} — ${skill.description} (${verified})`);
+                console.log(`     Install → nexus skills install ${skill.slug}`);
+                console.log(`     Install chain → nexus skills install ${skill.slug} --with-deps`);
+                const deps = [
+                    dependencies.tools.length > 0
+                        ? `Tools: ${dependencies.tools.join(", ")}`
+                        : null,
+                    dependencies.connectors.length > 0
+                        ? `Connectors: ${dependencies.connectors.join(", ")}`
+                        : null,
+                ].filter(Boolean);
+                if (deps.length > 0) {
+                    console.log(`     Requires → ${deps.join(" | ")}`);
+                }
+            }
+            console.log("");
+            return;
+        }
+        if (opts.json) {
+            console.log(JSON.stringify({
+                query,
+                local: opts.hubOnly ? [] : localMatches,
+                hub: opts.localOnly ? [] : hubMatches,
+                hubUrl: getHubBaseUrl(),
+            }, null, 2));
+            return;
+        }
+        if (!opts.hubOnly) {
+            console.log(`\nLocal matches (${localMatches.length})\n`);
+            if (localMatches.length === 0) {
+                console.log("  (none)\n");
+            }
+            else {
+                for (const skill of localMatches) {
+                    const status = skill.eligible ? "✅" : "🔧";
+                    console.log(`  ${status} ${skill.name} — ${skill.description}`);
+                    const deps = [
+                        skill.missing.credentials.length > 0
+                            ? `Connectors: ${skill.missing.credentials.join(", ")}`
+                            : null,
+                        skill.missing.bins.length > 0
+                            ? `Bins: ${skill.missing.bins.join(", ")}`
+                            : null,
+                        skill.missing.env.length > 0
+                            ? `Env: ${skill.missing.env.join(", ")}`
+                            : null,
+                        skill.missing.config.length > 0
+                            ? `Config: ${skill.missing.config.join(", ")}`
+                            : null,
+                    ].filter(Boolean);
+                    if (deps.length > 0) {
+                        console.log(`     Requires → ${deps.join(" | ")}`);
+                    }
+                    if (skill.install.length > 0) {
+                        console.log(`     Install → ${skill.install.map((i) => i.label).filter(Boolean).join(", ")}`);
+                    }
+                }
+                console.log("");
+            }
+        }
+        if (!opts.localOnly) {
+            console.log(`Hub matches (${hubMatches.length})\n`);
+            if (hubMatches.length === 0) {
+                console.log("  (none)\n");
+            }
+            else {
+                for (const skill of hubMatches) {
+                    const status = skill.installed ? "✅" : "🌐";
+                    const verified = skill.verified ? "verified" : "unverified";
+                    console.log(`  ${status} ${skill.slug} — ${skill.description} (${verified})`);
+                    if (!skill.installed) {
+                        console.log(`     Install → nexus skills install ${skill.slug}`);
+                    }
+                    const deps = [
+                        skill.dependencies.credentials.length > 0
+                            ? `Connectors: ${skill.dependencies.credentials.join(", ")}`
+                            : null,
+                        skill.dependencies.bins.length > 0
+                            ? `Bins: ${skill.dependencies.bins.join(", ")}`
+                            : null,
+                        skill.dependencies.env.length > 0
+                            ? `Env: ${skill.dependencies.env.join(", ")}`
+                            : null,
+                        skill.dependencies.config.length > 0
+                            ? `Config: ${skill.dependencies.config.join(", ")}`
+                            : null,
+                    ].filter(Boolean);
+                    if (deps.length > 0) {
+                        console.log(`     Requires → ${deps.join(" | ")}`);
+                    }
+                }
+                console.log("");
+            }
+        }
+    });
+    skills
+        .command("publish [skillPath]")
+        .description("Publish a skill to the Nexus Hub")
+        .option("--slug <slug>", "Publish a new version for an existing skill")
+        .option("--name <name>", "Override skill name")
+        .option("--description <description>", "Override skill description")
+        .option("--type <type>", "Override skill type (guide|tool|connector)")
+        .option("--version <version>", "Override skill version")
+        .option("--license <license>", "Override license")
+        .option("--repository <url>", "Override repository URL")
+        .option("--homepage <url>", "Override homepage URL")
+        .option("--visibility <value>", "public or unlisted", "public")
+        .option("--capability <cap>", "Add capability", (value, prev) => {
+        const list = Array.isArray(prev) ? prev : [];
+        list.push(value);
+        return list;
+    })
+        .option("--capabilities <list>", "Comma-separated capabilities")
+        .option("--source <path>", "Optional source archive or directory")
+        .option("--source-commit <sha>", "Optional source commit SHA")
+        .option("--token <token>", "Hub API token (or NEXUS_HUB_TOKEN)")
+        .option("--base <url>", "Hub base URL (default getnexus.sh)")
+        .action(async (skillPath, opts) => {
+        try {
+            const inputPath = resolveUserPath(skillPath ?? process.cwd());
+            const { skillDir, skillFile } = await resolveSkillFile(inputPath);
+            const content = await fs.readFile(skillFile, "utf-8");
+            const { frontmatter, body } = parseFrontmatter(content);
+            const capOverrides = [
+                ...(Array.isArray(opts.capability) ? opts.capability : []),
+                ...normalizeStringList(opts.capabilities),
+            ].map((cap) => cap.trim()).filter(Boolean);
+            const overrides = {
+                path: skillDir,
+                slug: typeof opts.slug === "string" ? opts.slug.trim() : undefined,
+                name: typeof opts.name === "string" ? opts.name.trim() : undefined,
+                description: typeof opts.description === "string" ? opts.description.trim() : undefined,
+                type: typeof opts.type === "string" ? opts.type.trim() : undefined,
+                version: typeof opts.version === "string" ? opts.version.trim() : undefined,
+                license: typeof opts.license === "string" ? opts.license.trim() : undefined,
+                repository: typeof opts.repository === "string" ? opts.repository.trim() : undefined,
+                homepage: typeof opts.homepage === "string" ? opts.homepage.trim() : undefined,
+                visibility: typeof opts.visibility === "string" ? opts.visibility.trim() : "public",
+                capabilities: capOverrides.length > 0 ? capOverrides : undefined,
+                sourcePath: typeof opts.source === "string" ? resolveUserPath(opts.source) : undefined,
+                sourceCommit: typeof opts.sourceCommit === "string"
+                    ? opts.sourceCommit.trim()
+                    : undefined,
+                token: typeof opts.token === "string" ? opts.token.trim() : undefined,
+                baseUrl: typeof opts.base === "string" ? opts.base.trim() : undefined,
+            };
+            const token = await resolveHubToken(overrides.token);
+            if (!token) {
+                throw new Error("Missing hub token. Run `nexus cloud login` or set NEXUS_HUB_TOKEN.");
+            }
+            const payload = buildManifestPayload({
+                frontmatter,
+                body,
+                overrides,
+            });
+            const missing = [];
+            if (!payload.name)
+                missing.push("name");
+            if (!payload.description)
+                missing.push("description");
+            if (!payload.type)
+                missing.push("type");
+            if (!payload.version)
+                missing.push("version");
+            if (!payload.license)
+                missing.push("license");
+            if (missing.length > 0) {
+                throw new Error(`Missing required fields: ${missing.join(", ")} (use flags or frontmatter)`);
+            }
+            const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), "nexus-skill-publish-"));
+            const artifactPath = path.join(tmpDir, "artifact.tgz");
+            await createTarball(skillDir, artifactPath);
+            const artifact = await computeArtifactInfo(artifactPath);
+            let source = null;
+            let sourcePath = null;
+            if (overrides.sourcePath) {
+                const sourceStats = await fs.stat(overrides.sourcePath);
+                if (sourceStats.isDirectory()) {
+                    sourcePath = path.join(tmpDir, "source.tgz");
+                    await createTarball(overrides.sourcePath, sourcePath);
+                }
+                else {
+                    sourcePath = overrides.sourcePath;
+                }
+                source = await computeArtifactInfo(sourcePath);
+            }
+            const baseUrl = overrides.baseUrl || getHubBaseUrl();
+            const endpoint = overrides.slug
+                ? `/api/skills/${encodeURIComponent(overrides.slug)}/versions`
+                : "/api/skills";
+            const response = await fetch(new URL(endpoint, baseUrl), {
+                method: "POST",
+                headers: {
+                    "content-type": "application/json",
+                    authorization: `Bearer ${token}`,
+                },
+                body: JSON.stringify({
+                    name: payload.name,
+                    description: payload.description,
+                    type: payload.type,
+                    version: payload.version,
+                    license: payload.license,
+                    repository: payload.repository || "",
+                    homepage: payload.homepage || "",
+                    visibility: overrides.visibility || "public",
+                    sourceCommit: overrides.sourceCommit || "",
+                    capabilities: payload.capabilities,
+                    readmeExcerpt: payload.readmeExcerpt,
+                    manifest: payload.manifest,
+                    artifact: { sha256: artifact.sha256, bytes: artifact.bytes },
+                    ...(source
+                        ? { source: { sha256: source.sha256, bytes: source.bytes } }
+                        : {}),
+                }),
+            });
+            const data = await response.json().catch(() => ({}));
+            if (!response.ok) {
+                if (response.status === 409 && !overrides.slug) {
+                    throw new Error("Skill already exists. Re-run with --slug <owner/name> to publish a new version.");
+                }
+                throw new Error(data?.error || `Publish failed (${response.status})`);
+            }
+            const upload = data?.upload;
+            const needed = Array.isArray(upload?.needed) ? upload.needed : [];
+            const fileMap = new Map([
+                [artifact.sha256, artifactPath],
+            ]);
+            if (source && sourcePath) {
+                fileMap.set(source.sha256, sourcePath);
+            }
+            for (const item of needed) {
+                if (!item?.id || !item?.url)
+                    continue;
+                const filePath = fileMap.get(item.id);
+                if (!filePath)
+                    continue;
+                const blob = await fs.readFile(filePath);
+                const headers = {};
+                if (upload?.cloudToken && item.url.includes("/api/v1/blobs/")) {
+                    headers.authorization = `Bearer ${upload.cloudToken}`;
+                }
+                const uploadResp = await fetch(item.url, {
+                    method: "PUT",
+                    headers,
+                    body: blob,
+                });
+                if (!uploadResp.ok) {
+                    const bodyText = await uploadResp.text().catch(() => "");
+                    throw new Error(`Upload failed (${uploadResp.status}): ${bodyText || "unknown error"}`);
+                }
+            }
+            console.log(`✅ Published ${payload.name} (${payload.version})` +
+                (data?.skill?.slug ? ` as ${data.skill.slug}` : ""));
+            if (needed.length > 0) {
+                console.log(`   Uploaded ${needed.length} artifact(s)`);
+            }
+        }
+        catch (err) {
+            console.error(err instanceof Error ? err.message : `Publish failed: ${String(err)}`);
+            process.exit(1);
+        }
+    });
+    skills
+        .command("install <slug>")
+        .description("Install a skill from the Nexus Hub")
+        .option("--force", "Overwrite if destination exists")
+        .option("--with-deps", "Install tool/connector dependencies first")
+        .action(async (slug, opts) => {
+        try {
+            const cfg = loadConfig();
+            const workspaceDir = resolveUserPath(cfg.agent?.workspace ?? DEFAULT_AGENT_WORKSPACE_DIR);
+            const userSkillsDir = path.join(workspaceDir, "skills");
+            const managedSkillsDir = MANAGED_SKILLS_DIR;
+            const managedDir = path.join(managedSkillsDir, "managed");
+            const metadataEntries = loadWorkspaceSkillEntries(workspaceDir, {
+                config: cfg,
+                managedSkillsDir,
+            });
+            const installedNames = new Set(metadataEntries.map((entry) => normalizeSkillKey(entry.skill.name)));
+            const installedSlugs = await loadManagedSkillSlugs(managedSkillsDir);
+            const installedIndex = {
+                names: installedNames,
+                slugs: installedSlugs,
+            };
+            const detailsCache = new Map();
+            const getDetails = async (detailSlug) => {
+                const key = normalizeSkillKey(detailSlug);
+                const cached = detailsCache.get(key);
+                if (cached)
+                    return cached;
+                const details = await fetchHubSkillDetails(detailSlug);
+                detailsCache.set(key, details);
+                return details;
+            };
+            if (opts.withDeps) {
+                const missingDeps = [];
+                const plan = await resolveHubDependencyPlan(slug, installedIndex, getDetails, (missing) => {
+                    missingDeps.push(missing);
+                });
+                if (plan.length > 0) {
+                    console.log(`\nInstalling dependencies (${plan.length})...\n`);
+                }
+                for (const dep of plan) {
+                    const result = await installHubSkill({
+                        slug: dep,
+                        managedDir,
+                        userSkillsDir,
+                        allowSkip: true,
+                    });
+                    if (result.installed) {
+                        installedIndex.slugs.add(normalizeSkillKey(dep));
+                        const detail = detailsCache.get(normalizeSkillKey(dep));
+                        if (detail?.name) {
+                            installedIndex.names.add(normalizeSkillKey(detail.name));
+                        }
+                        console.log(`✅ Installed dependency ${dep}`);
+                    }
+                    else {
+                        console.log(`⏭️  Dependency already installed: ${dep}`);
+                    }
+                }
+                if (plan.length > 0) {
+                    console.log("");
+                }
+                if (missingDeps.length > 0) {
+                    console.log(`⚠️  Missing dependencies in hub: ${missingDeps.join(", ")}`);
+                }
+            }
+            const result = await installHubSkill({
+                slug,
+                managedDir,
+                userSkillsDir,
+                force: Boolean(opts.force),
+            });
+            console.log(`✅ Installed ${slug} to ${result.destDir}`);
+            console.log(`   Run: nexus skill use ${path.basename(slug)}`);
+        }
+        catch (err) {
+            console.error(err instanceof Error ? err.message : `Install failed: ${String(err)}`);
+            process.exit(1);
+        }
+    });
+}
+// Cloud login moved to cloud-cli.