@memtensor/memos-local-openclaw-plugin 1.0.4-beta.6 → 1.0.4-beta.7

package/src/client/connector.ts

@@ -0,0 +1,212 @@
+import type { Logger, MemosLocalConfig } from "../types";
+import type { UserRole, UserStatus } from "../sharing/types";
+import type { SqliteStore } from "../storage/sqlite";
+import { hubRequestJson, normalizeHubUrl } from "./hub";
+
+export interface HubSessionInfo {
+  hubUrl: string;
+  userId: string;
+  username: string;
+  userToken: string;
+  role: UserRole;
+  connectedAt: number;
+}
+
+export interface HubStatusInfo {
+  connected: boolean;
+  hubUrl?: string;
+  user: null | {
+    id: string;
+    username: string;
+    role: UserRole;
+    status: UserStatus | string;
+  };
+}
+
+export async function connectToHub(store: SqliteStore, config: MemosLocalConfig, log?: Logger): Promise<HubSessionInfo> {
+  const hubAddress = config.sharing?.client?.hubAddress ?? "";
+  let userToken = config.sharing?.client?.userToken ?? "";
+
+  if (!userToken) {
+    const persisted = store.getClientHubConnection();
+    if (persisted?.userToken) userToken = persisted.userToken;
+  }
+
+  if (!userToken && config.sharing?.client?.teamToken) {
+    if (!log) throw new Error("hub client connection is not configured (no userToken, has teamToken but no logger for auto-join)");
+    return autoJoinHub(store, config, log);
+  }
+
+  if (!hubAddress || !userToken) {
+    throw new Error("hub client connection is not configured");
+  }
+
+  const hubUrl = normalizeHubUrl(hubAddress);
+  const me = await hubRequestJson(hubUrl, userToken, "/api/v1/hub/me", { method: "GET" }) as any;
+  store.setClientHubConnection({
+    hubUrl,
+    userId: String(me.id),
+    username: String(me.username ?? ""),
+    userToken,
+    role: String(me.role ?? "member") as UserRole,
+    connectedAt: Date.now(),
+  });
+  return store.getClientHubConnection()!;
+}
+
+export async function getHubStatus(store: SqliteStore, config: MemosLocalConfig): Promise<HubStatusInfo> {
+  const conn = store.getClientHubConnection();
+  const hubAddress = conn?.hubUrl || config.sharing?.client?.hubAddress || "";
+  const userToken = conn?.userToken || config.sharing?.client?.userToken || "";
+
+  if (conn && conn.userId && (!userToken || userToken === "")) {
+    const teamToken = config.sharing?.client?.teamToken ?? "";
+    if (hubAddress && teamToken) {
+      try {
+        const result = await hubRequestJson(normalizeHubUrl(hubAddress), "", "/api/v1/hub/join", {
+          method: "POST",
+          body: JSON.stringify({ teamToken, username: conn.username || "user" }),
+        }) as any;
+        if (result.status === "pending") {
+          return {
+            connected: false,
+            hubUrl: normalizeHubUrl(hubAddress),
+            user: {
+              id: conn.userId,
+              username: conn.username || "",
+              role: "member",
+              status: "pending",
+            },
+          };
+        }
+        if (result.status === "active" && result.userToken) {
+          store.setClientHubConnection({
+            hubUrl: normalizeHubUrl(hubAddress),
+            userId: String(result.userId),
+            username: conn.username || "",
+            userToken: result.userToken,
+            role: "member",
+            connectedAt: Date.now(),
+          });
+          const me = await hubRequestJson(normalizeHubUrl(hubAddress), result.userToken, "/api/v1/hub/me", { method: "GET" }) as any;
+          return {
+            connected: true,
+            hubUrl: normalizeHubUrl(hubAddress),
+            user: {
+              id: String(me.id),
+              username: String(me.username ?? ""),
+              role: String(me.role ?? "member") as UserRole,
+              status: String(me.status ?? "active"),
+            },
+          };
+        }
+        if (result.status === "rejected") {
+          return {
+            connected: false,
+            hubUrl: normalizeHubUrl(hubAddress),
+            user: {
+              id: conn.userId,
+              username: conn.username || "",
+              role: "member",
+              status: "rejected",
+            },
+          };
+        }
+      } catch { /* fall through */ }
+    }
+    return { connected: false, user: null };
+  }
+
+  if (!hubAddress || !userToken) {
+    return { connected: false, user: null };
+  }
+
+  try {
+    const me = await hubRequestJson(normalizeHubUrl(hubAddress), userToken, "/api/v1/hub/me", { method: "GET" }) as any;
+    return {
+      connected: true,
+      hubUrl: normalizeHubUrl(hubAddress),
+      user: {
+        id: String(me.id),
+        username: String(me.username ?? ""),
+        role: String(me.role ?? "member") as UserRole,
+        status: String(me.status ?? "active"),
+      },
+    };
+  } catch {
+    return { connected: false, user: null };
+  }
+}
+
+export async function autoJoinHub(
+  store: SqliteStore,
+  config: MemosLocalConfig,
+  log: Logger,
+): Promise<HubSessionInfo> {
+  const hubAddress = config.sharing?.client?.hubAddress ?? "";
+  const teamToken = config.sharing?.client?.teamToken ?? "";
+  if (!hubAddress || !teamToken) {
+    throw new Error("hubAddress and teamToken are required for auto-join");
+  }
+  const hubUrl = normalizeHubUrl(hubAddress);
+  const osModule = typeof globalThis.process !== "undefined" ? await import("os") : null;
+  const hostname = osModule ? osModule.hostname() : "unknown";
+  const username = osModule ? osModule.userInfo().username : "user";
+  let clientIp = "";
+  if (osModule) {
+    const nets = osModule.networkInterfaces();
+    for (const name of Object.keys(nets)) {
+      for (const net of nets[name] ?? []) {
+        if (net.family === "IPv4" && !net.internal) { clientIp = net.address; break; }
+      }
+      if (clientIp) break;
+    }
+  }
+
+  log.info(`Joining Hub at ${hubUrl} as "${username}"...`);
+  const result = await hubRequestJson(hubUrl, "", "/api/v1/hub/join", {
+    method: "POST",
+    body: JSON.stringify({ teamToken, username, deviceName: hostname, clientIp }),
+  }) as any;
+
+  if (result.status === "pending") {
+    log.info(`Join request submitted, awaiting admin approval. userId=${result.userId}`);
+    store.setClientHubConnection({
+      hubUrl,
+      userId: String(result.userId),
+      username,
+      userToken: "",
+      role: "member",
+      connectedAt: Date.now(),
+    });
+    throw new PendingApprovalError(result.userId);
+  }
+
+  if (result.status === "rejected") {
+    throw new Error(`Join request was rejected by the Hub admin.`);
+  }
+
+  if (!result.userToken) {
+    throw new Error(`Hub join failed: ${JSON.stringify(result)}`);
+  }
+
+  log.info(`Joined Hub successfully! userId=${result.userId}`);
+  store.setClientHubConnection({
+    hubUrl,
+    userId: String(result.userId),
+    username,
+    userToken: result.userToken,
+    role: "member",
+    connectedAt: Date.now(),
+  });
+  return store.getClientHubConnection()!;
+}
+
+export class PendingApprovalError extends Error {
+  public readonly userId: string;
+  constructor(userId: string) {
+    super("Awaiting admin approval");
+    this.name = "PendingApprovalError";
+    this.userId = userId;
+  }
+}

package/src/client/hub.ts

@@ -0,0 +1,207 @@
+import type { PluginContext } from "../types";
+import type { SqliteStore } from "../storage/sqlite";
+import type { HubMemoryDetail, HubScope, HubSearchResult, HubSkillSearchResult } from "../sharing/types";
+
+export interface ResolvedHubClient {
+  hubUrl: string;
+  userToken: string;
+  userId: string;
+  username: string;
+  role: string;
+}
+
+export async function resolveHubClient(store: SqliteStore, ctx: PluginContext, overrides?: { hubAddress?: string; userToken?: string }): Promise<ResolvedHubClient> {
+  const persisted = store.getClientHubConnection() as any;
+  if (persisted?.hubUrl && persisted?.userToken) {
+    return {
+      hubUrl: normalizeHubUrl(String(persisted.hubUrl)),
+      userToken: String(persisted.userToken),
+      userId: String(persisted.userId),
+      username: String(persisted.username ?? ""),
+      role: String(persisted.role ?? "member"),
+    };
+  }
+
+  const hubAddress = overrides?.hubAddress ?? ctx.config.sharing?.client?.hubAddress ?? "";
+  const userToken = overrides?.userToken ?? ctx.config.sharing?.client?.userToken ?? "";
+  if (!hubAddress || !userToken) {
+    throw new Error("hub client connection is not configured");
+  }
+
+  const hubUrl = normalizeHubUrl(hubAddress);
+  const me = await hubRequestJson(hubUrl, userToken, "/api/v1/hub/me", { method: "GET" }) as any;
+
+  return {
+    hubUrl,
+    userToken,
+    userId: String(me.id),
+    username: String(me.username ?? ""),
+    role: String(me.role ?? "member"),
+  };
+}
+
+export async function hubListMemories(
+  store: SqliteStore,
+  ctx: PluginContext,
+  input?: { limit?: number; hubAddress?: string; userToken?: string },
+): Promise<{ memories: Array<any> }> {
+  const client = await resolveHubClient(store, ctx, { hubAddress: input?.hubAddress, userToken: input?.userToken });
+  const url = new URL(`${client.hubUrl}/api/v1/hub/memories`);
+  if (input?.limit != null) url.searchParams.set("limit", String(input.limit));
+  return hubRequestJson(url.origin, client.userToken, `${url.pathname}${url.search}`, {
+    method: "GET",
+  }) as Promise<{ memories: Array<any> }>;
+}
+
+export async function hubListTasks(
+  store: SqliteStore,
+  ctx: PluginContext,
+  input?: { limit?: number; hubAddress?: string; userToken?: string },
+): Promise<{ tasks: Array<any> }> {
+  const client = await resolveHubClient(store, ctx, { hubAddress: input?.hubAddress, userToken: input?.userToken });
+  const url = new URL(`${client.hubUrl}/api/v1/hub/tasks`);
+  if (input?.limit != null) url.searchParams.set("limit", String(input.limit));
+  return hubRequestJson(url.origin, client.userToken, `${url.pathname}${url.search}`, {
+    method: "GET",
+  }) as Promise<{ tasks: Array<any> }>;
+}
+
+export async function hubListSkills(
+  store: SqliteStore,
+  ctx: PluginContext,
+  input?: { limit?: number; hubAddress?: string; userToken?: string },
+): Promise<{ skills: Array<any> }> {
+  const client = await resolveHubClient(store, ctx, { hubAddress: input?.hubAddress, userToken: input?.userToken });
+  const url = new URL(`${client.hubUrl}/api/v1/hub/skills/list`);
+  if (input?.limit != null) url.searchParams.set("limit", String(input.limit));
+  return hubRequestJson(url.origin, client.userToken, `${url.pathname}${url.search}`, {
+    method: "GET",
+  }) as Promise<{ skills: Array<any> }>;
+}
+
+export async function hubSearchMemories(
+  store: SqliteStore,
+  ctx: PluginContext,
+  input: { query: string; maxResults?: number; scope?: HubScope; hubAddress?: string; userToken?: string },
+): Promise<HubSearchResult> {
+  const client = await resolveHubClient(store, ctx, { hubAddress: input.hubAddress, userToken: input.userToken });
+  return hubRequestJson(client.hubUrl, client.userToken, "/api/v1/hub/search", {
+    method: "POST",
+    body: JSON.stringify({
+      query: input.query,
+      maxResults: input.maxResults,
+      scope: input.scope,
+    }),
+  }) as Promise<HubSearchResult>;
+}
+
+
+export async function hubSearchSkills(
+  store: SqliteStore,
+  ctx: PluginContext,
+  input: { query: string; maxResults?: number; hubAddress?: string; userToken?: string },
+): Promise<HubSkillSearchResult> {
+  const client = await resolveHubClient(store, ctx, { hubAddress: input.hubAddress, userToken: input.userToken });
+  const url = new URL(`${client.hubUrl}/api/v1/hub/skills`);
+  url.searchParams.set("query", input.query);
+  if (input.maxResults != null) url.searchParams.set("maxResults", String(input.maxResults));
+  return hubRequestJson(url.origin, client.userToken, `${url.pathname}${url.search}`, {
+    method: "GET",
+  }) as Promise<HubSkillSearchResult>;
+}
+
+export async function hubGetMemoryDetail(
+  store: SqliteStore,
+  ctx: PluginContext,
+  input: { remoteHitId: string; hubAddress?: string; userToken?: string },
+): Promise<HubMemoryDetail> {
+  const client = await resolveHubClient(store, ctx, { hubAddress: input.hubAddress, userToken: input.userToken });
+  const detail = await hubRequestJson(client.hubUrl, client.userToken, "/api/v1/hub/memory-detail", {
+    method: "POST",
+    body: JSON.stringify({
+      remoteHitId: input.remoteHitId,
+    }),
+  }) as Omit<HubMemoryDetail, "remoteHitId">;
+
+  return {
+    remoteHitId: input.remoteHitId,
+    content: String(detail.content ?? ""),
+    summary: String(detail.summary ?? ""),
+    source: {
+      ts: Number(detail.source?.ts ?? 0),
+      role: String(detail.source?.role ?? "assistant") as any,
+    },
+  };
+}
+
+export async function hubUpdateUsername(
+  store: SqliteStore,
+  ctx: PluginContext,
+  newUsername: string,
+): Promise<{ ok: boolean; username: string; userToken: string }> {
+  const client = await resolveHubClient(store, ctx);
+  const result = await hubRequestJson(client.hubUrl, client.userToken, "/api/v1/hub/me/update-profile", {
+    method: "POST",
+    body: JSON.stringify({ username: newUsername }),
+  }) as { ok: boolean; username: string; userToken: string };
+  if (result.ok && result.userToken) {
+    store.setClientHubConnection({
+      hubUrl: client.hubUrl,
+      userId: client.userId,
+      username: result.username,
+      userToken: result.userToken,
+      role: client.role as "admin" | "member",
+      connectedAt: Date.now(),
+    });
+  }
+  return result;
+}
+
+let _cachedClientIp: string | null = null;
+function getClientIp(): string {
+  if (_cachedClientIp !== null) return _cachedClientIp;
+  try {
+    const os = require("os");
+    const nets = os.networkInterfaces();
+    for (const name of Object.keys(nets)) {
+      for (const net of nets[name] ?? []) {
+        if (net.family === "IPv4" && !net.internal) { _cachedClientIp = net.address; return _cachedClientIp!; }
+      }
+    }
+  } catch { /* browser or no os module */ }
+  _cachedClientIp = "";
+  return "";
+}
+
+export async function hubRequestJson(
+  hubUrl: string,
+  userToken: string,
+  route: string,
+  init: RequestInit = {},
+): Promise<unknown> {
+  const clientIp = getClientIp();
+  const res = await fetch(`${normalizeHubUrl(hubUrl)}${route}`, {
+    ...init,
+    headers: {
+      authorization: `Bearer ${userToken}`,
+      ...(clientIp ? { "x-client-ip": clientIp } : {}),
+      ...(init.body ? { "content-type": "application/json" } : {}),
+      ...(init.headers ?? {}),
+    },
+  });
+
+  if (!res.ok) {
+    const body = await res.text();
+    throw new Error(`hub request failed (${res.status}): ${body || res.statusText}`);
+  }
+
+  if (res.status === 204) return null;
+  return res.json();
+}
+
+export function normalizeHubUrl(hubAddress: string): string {
+  const trimmed = hubAddress.trim().replace(/\/+$/, "");
+  if (!trimmed) return "";
+  if (/^https?:\/\//i.test(trimmed)) return trimmed;
+  return `http://${trimmed}`;
+}

package/src/client/skill-sync.ts

@@ -0,0 +1,216 @@
+import * as fs from "fs";
+import * as path from "path";
+import { randomUUID } from "crypto";
+import type { PluginContext, Skill, SkillVersion } from "../types";
+import type { SqliteStore } from "../storage/sqlite";
+import type { SkillGenerateOutput } from "../types";
+import type { SkillBundle } from "../sharing/types";
+import { resolveHubClient, hubRequestJson } from "./hub";
+
+export function buildSkillBundleForHub(store: SqliteStore, skillId: string): SkillBundle {
+  const skill = store.getSkill(skillId);
+  if (!skill) {
+    throw new Error(`Skill not found: ${skillId}`);
+  }
+
+  const latestVersion = store.getLatestSkillVersion(skillId);
+  const skillMd = readSkillMarkdown(skill.dirPath, latestVersion?.content ?? "");
+
+  return {
+    metadata: {
+      id: skill.id,
+      name: skill.name,
+      description: skill.description,
+      version: skill.version,
+      qualityScore: skill.qualityScore,
+    },
+    bundle: {
+      skill_md: skillMd,
+      scripts: readCompanionFiles(path.join(skill.dirPath, "scripts")),
+      references: readCompanionFiles(path.join(skill.dirPath, "references")),
+      evals: readEvals(path.join(skill.dirPath, "evals", "evals.json")),
+    } satisfies SkillGenerateOutput,
+  };
+}
+
+function readSkillMarkdown(dirPath: string, fallback: string): string {
+  const skillMdPath = path.join(dirPath, "SKILL.md");
+  if (fs.existsSync(skillMdPath)) {
+    return fs.readFileSync(skillMdPath, "utf8");
+  }
+  return fallback;
+}
+
+function readCompanionFiles(dirPath: string): Array<{ filename: string; content: string }> {
+  if (!fs.existsSync(dirPath)) return [];
+
+  const out: Array<{ filename: string; content: string }> = [];
+  walkFiles(dirPath, dirPath, out);
+  return out.sort((left, right) => left.filename.localeCompare(right.filename));
+}
+
+function walkFiles(rootDir: string, currentDir: string, out: Array<{ filename: string; content: string }>): void {
+  for (const entry of fs.readdirSync(currentDir, { withFileTypes: true })) {
+    const fullPath = path.join(currentDir, entry.name);
+    if (entry.isDirectory()) {
+      walkFiles(rootDir, fullPath, out);
+      continue;
+    }
+    if (!entry.isFile()) continue;
+    out.push({
+      filename: path.relative(rootDir, fullPath).replace(/\\/g, "/"),
+      content: fs.readFileSync(fullPath, "utf8"),
+    });
+  }
+}
+
+function readEvals(evalsPath: string): Array<{ id: number; prompt: string; expectations: string[] }> {
+  if (!fs.existsSync(evalsPath)) return [];
+  const raw = JSON.parse(fs.readFileSync(evalsPath, "utf8")) as { evals?: Array<{ id: number; prompt: string; expectations: string[] }> };
+  return Array.isArray(raw.evals) ? raw.evals : [];
+}
+
+
+export async function publishSkillBundleToHub(
+  store: SqliteStore,
+  ctx: PluginContext,
+  input: { skillId: string; visibility: "public" | "group"; groupId?: string; hubAddress?: string; userToken?: string },
+): Promise<{ skillId: string; visibility: "public" | "group" }> {
+  const bundle = buildSkillBundleForHub(store, input.skillId);
+  const client = await resolveHubClient(store, ctx, { hubAddress: input.hubAddress, userToken: input.userToken });
+  return hubRequestJson(client.hubUrl, client.userToken, "/api/v1/hub/skills/publish", {
+    method: "POST",
+    body: JSON.stringify({
+      visibility: input.visibility,
+      groupId: input.groupId,
+      metadata: bundle.metadata,
+      bundle: bundle.bundle,
+    }),
+  }) as Promise<{ skillId: string; visibility: "public" | "group" }>;
+}
+
+export async function unpublishSkillBundleFromHub(
+  store: SqliteStore,
+  ctx: PluginContext,
+  input: { skillId: string; hubAddress?: string; userToken?: string },
+): Promise<{ ok: boolean }> {
+  const client = await resolveHubClient(store, ctx, { hubAddress: input.hubAddress, userToken: input.userToken });
+  return hubRequestJson(client.hubUrl, client.userToken, "/api/v1/hub/skills/unpublish", {
+    method: "POST",
+    body: JSON.stringify({
+      sourceSkillId: input.skillId,
+    }),
+  }) as Promise<{ ok: boolean }>;
+}
+
+export async function fetchHubSkillBundle(
+  store: SqliteStore,
+  ctx: PluginContext,
+  input: { skillId: string; hubAddress?: string; userToken?: string },
+): Promise<SkillBundle & { skillId: string }> {
+  const client = await resolveHubClient(store, ctx, { hubAddress: input.hubAddress, userToken: input.userToken });
+  return hubRequestJson(client.hubUrl, client.userToken, `/api/v1/hub/skills/${encodeURIComponent(input.skillId)}/bundle`, {
+    method: "GET",
+  }) as Promise<SkillBundle & { skillId: string }>;
+}
+
+export function restoreSkillBundleFromHub(
+  store: SqliteStore,
+  ctx: PluginContext,
+  payload: SkillBundle & { skillId?: string },
+): { localSkillId: string; localName: string; dirPath: string } {
+  validateBundle(payload.bundle);
+
+  const skillsStoreDir = path.join(ctx.stateDir, "skills-store");
+  fs.mkdirSync(skillsStoreDir, { recursive: true });
+
+  const baseName = sanitizeName(payload.metadata.name) || `hub-skill-${(payload.skillId ?? payload.metadata.id).slice(0, 8)}`;
+  const resolvedName = resolveLocalSkillName(store, baseName, payload.skillId ?? payload.metadata.id);
+  const dirPath = path.join(skillsStoreDir, resolvedName);
+  fs.mkdirSync(dirPath, { recursive: true });
+  fs.writeFileSync(path.join(dirPath, "SKILL.md"), payload.bundle.skill_md, "utf8");
+
+  writeCompanionFiles(dirPath, "scripts", payload.bundle.scripts);
+  writeCompanionFiles(dirPath, "references", payload.bundle.references);
+  if (payload.bundle.evals.length > 0) {
+    const evalDir = path.join(dirPath, "evals");
+    fs.mkdirSync(evalDir, { recursive: true });
+    fs.writeFileSync(path.join(evalDir, "evals.json"), JSON.stringify({ skill_name: payload.metadata.name, evals: payload.bundle.evals }, null, 2), "utf8");
+  }
+
+  const now = Date.now();
+  const localSkillId = randomUUID();
+  const skill: Skill = {
+    id: localSkillId,
+    name: resolvedName,
+    description: payload.metadata.description,
+    version: payload.metadata.version,
+    status: "active",
+    tags: JSON.stringify(["hub-import"]),
+    sourceType: "manual",
+    dirPath,
+    installed: 0,
+    owner: "agent:main",
+    visibility: "private",
+    qualityScore: payload.metadata.qualityScore,
+    createdAt: now,
+    updatedAt: now,
+  };
+  const version: SkillVersion = {
+    id: randomUUID(),
+    skillId: localSkillId,
+    version: payload.metadata.version,
+    content: payload.bundle.skill_md,
+    changelog: "Imported from hub",
+    changeSummary: "Imported from hub",
+    upgradeType: "create",
+    sourceTaskId: null,
+    metrics: "{}",
+    qualityScore: payload.metadata.qualityScore,
+    createdAt: now,
+  };
+
+  store.insertSkill(skill);
+  store.insertSkillVersion(version);
+  return { localSkillId, localName: resolvedName, dirPath };
+}
+
+function validateBundle(bundle: SkillGenerateOutput): void {
+  const allowedExtensions = new Set([".md", ".ts", ".js", ".sh", ".json", ".yaml", ".yml", ".txt"]);
+  const files = [...bundle.scripts, ...bundle.references];
+  if (Buffer.byteLength(bundle.skill_md, "utf8") > 100 * 1024) throw new Error("SKILL.md exceeds size limit");
+  if (files.length > 50) throw new Error("bundle contains too many files");
+
+  let totalBytes = Buffer.byteLength(bundle.skill_md, "utf8");
+  for (const file of files) {
+    const name = file.filename;
+    if (!name || path.isAbsolute(name) || name.startsWith("/") || name.includes("..")) throw new Error(`unsafe filename: ${name}`);
+    if (!/^[A-Za-z0-9._/-]+$/.test(name)) throw new Error(`invalid filename: ${name}`);
+    const ext = path.extname(name).toLowerCase();
+    if (!allowedExtensions.has(ext)) throw new Error(`unsupported file type: ${name}`);
+    const fileSize = Buffer.byteLength(file.content, "utf8");
+    if (fileSize > 512 * 1024) throw new Error(`file exceeds size limit: ${name}`);
+    totalBytes += fileSize;
+  }
+  if (totalBytes > 5 * 1024 * 1024) throw new Error("bundle exceeds size limit");
+}
+
+function writeCompanionFiles(dirPath: string, root: "scripts" | "references", files: Array<{ filename: string; content: string }>): void {
+  if (files.length === 0) return;
+  const rootDir = path.join(dirPath, root);
+  fs.mkdirSync(rootDir, { recursive: true });
+  for (const file of files) {
+    const target = path.join(rootDir, file.filename);
+    fs.mkdirSync(path.dirname(target), { recursive: true });
+    fs.writeFileSync(target, file.content, "utf8");
+  }
+}
+
+function sanitizeName(input: string): string {
+  return input.trim().replace(/[^A-Za-z0-9._-]+/g, "-").replace(/^-+|-+$/g, "");
+}
+
+function resolveLocalSkillName(store: SqliteStore, baseName: string, sourceId: string): string {
+  if (!store.getSkillByName(baseName)) return baseName;
+  return `${baseName}-hub-${sourceId.slice(0, 8)}`;
+}