@paradigma-inc/flywheel 0.1.4 → 0.1.9

package/src/skill-installer.mjs

@@ -0,0 +1,542 @@
+import { execFile as execFileCb } from "node:child_process";
+import { existsSync } from "node:fs";
+import {
+  access,
+  cp,
+  lstat,
+  mkdir,
+  mkdtemp,
+  readFile,
+  readlink,
+  readdir,
+  rm,
+  symlink,
+  writeFile,
+} from "node:fs/promises";
+import { createRequire } from "node:module";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { promisify } from "node:util";
+import { dump as dumpYaml, load as loadYaml } from "js-yaml";
+
+const execFile = promisify(execFileCb);
+const requireFromInstaller = createRequire(import.meta.url);
+const DEFAULT_SKILL_MCP_SERVER_NAME = "flywheel";
+const DEFAULT_SKILL_MCP_SERVER_URL = "https://flywheel.paradigma.inc/mcp-server";
+const OPENAI_AGENT_METADATA_RELATIVE_PATH = path.join("agents", "openai.yaml");
+
+export const INSTALL_SKILLS_AGENT_BY_HOST = Object.freeze({
+  claude: "claude-code",
+  codex: "codex",
+  opencode: "opencode",
+  cursor: "cursor",
+  openclaw: "openclaw",
+  "pi-mono": "pi",
+});
+
+export const SUPPORTED_INSTALL_SKILL_HOSTS = Object.freeze([
+  "codex",
+  "claude",
+  "opencode",
+  "cursor",
+  "openclaw",
+  "pi-mono",
+]);
+
+export function resolvePackageRoot(moduleUrl = import.meta.url) {
+  const modulePath = fileURLToPath(moduleUrl);
+  const moduleDir = path.dirname(modulePath);
+  return path.resolve(moduleDir, "..");
+}
+
+export async function listBundledSkills(packageRoot) {
+  let skillEntries;
+  try {
+    skillEntries = await readdir(path.join(packageRoot, "skills"), {
+      withFileTypes: true,
+    });
+  } catch (error) {
+    if (error && typeof error === "object" && "code" in error && error.code === "ENOENT") {
+      return [];
+    }
+    throw error;
+  }
+  const bundledSkillNames = [];
+
+  for (const entry of skillEntries) {
+    if (!entry.isDirectory()) {
+      continue;
+    }
+
+    const skillPath = path.join(packageRoot, "skills", entry.name, "SKILL.md");
+    if (await pathExists(skillPath)) {
+      bundledSkillNames.push(entry.name);
+    }
+  }
+
+  return bundledSkillNames.sort();
+}
+
+function normalizeBundledSkillName(skillName) {
+  const normalizedSkillName = String(skillName ?? "").trim();
+  if (normalizedSkillName.length === 0) {
+    throw new Error("Bundled skill name is required.");
+  }
+  return normalizedSkillName;
+}
+
+export function resolveBundledSkillDir(packageRoot, skillName) {
+  return path.join(packageRoot, "skills", normalizeBundledSkillName(skillName));
+}
+
+export function resolveSkillsCliPath(packageRoot) {
+  try {
+    return requireFromInstaller.resolve("skills/bin/cli.mjs", {
+      paths: [packageRoot],
+    });
+  } catch (error) {
+    const reason = error instanceof Error ? error.message : String(error);
+    throw new Error(
+      `Unable to resolve 'skills/bin/cli.mjs' from package root '${packageRoot}'. Ensure dependency 'skills' is installed. (${reason})`,
+    );
+  }
+}
+
+export function resolveSkillsAgentName(hostName) {
+  const agentName = INSTALL_SKILLS_AGENT_BY_HOST[hostName];
+  if (!agentName) {
+    throw new Error(`--install-skill is not supported for host '${hostName}'.`);
+  }
+  return agentName;
+}
+
+export function formatSupportedInstallSkillHosts() {
+  return SUPPORTED_INSTALL_SKILL_HOSTS.join(", ");
+}
+
+function uniqueValues(values) {
+  return [...new Set(values)];
+}
+
+function normalizeBundledSkillNames(skillNames) {
+  if (!Array.isArray(skillNames) || skillNames.length === 0) {
+    throw new Error("At least one bundled skill name is required.");
+  }
+  return uniqueValues(skillNames.map(normalizeBundledSkillName)).sort();
+}
+
+function normalizeInstallScope(scope) {
+  return scope === "global" ? "global" : "project";
+}
+
+function resolveScopeRoot(projectRoot, scope) {
+  return normalizeInstallScope(scope) === "global" ? os.homedir() : projectRoot;
+}
+
+function resolveOpenClawGlobalSkillsRoot(homeDir) {
+  // Must stay aligned with pinned skills runtime precedence.
+  // skills@1.4.7 getOpenClawGlobalSkillsDir:
+  // .openclaw -> .clawdbot -> .moltbot -> default .openclaw.
+  if (existsSync(path.join(homeDir, ".openclaw"))) {
+    return path.join(homeDir, ".openclaw", "skills");
+  }
+  if (existsSync(path.join(homeDir, ".clawdbot"))) {
+    return path.join(homeDir, ".clawdbot", "skills");
+  }
+  if (existsSync(path.join(homeDir, ".moltbot"))) {
+    return path.join(homeDir, ".moltbot", "skills");
+  }
+  return path.join(homeDir, ".openclaw", "skills");
+}
+
+function resolveInstalledSkillDirsForHosts(
+  projectRoot,
+  hostNames = [],
+  scope = "project",
+  skillName,
+) {
+  return uniqueValues(
+    hostNames.map((hostName) =>
+      resolveInstalledSkillDir(projectRoot, hostName, scope, skillName),
+    ),
+  );
+}
+
+export function partitionInstallSkillHosts(hostNames) {
+  const supportedHosts = [];
+  const unsupportedHosts = [];
+
+  for (const hostName of uniqueValues(hostNames)) {
+    if (hostName in INSTALL_SKILLS_AGENT_BY_HOST) {
+      supportedHosts.push(hostName);
+    } else {
+      unsupportedHosts.push(hostName);
+    }
+  }
+
+  return { supportedHosts, unsupportedHosts };
+}
+
+export function resolveInstalledSkillDir(
+  projectRoot,
+  hostName,
+  scope = "project",
+  skillName,
+) {
+  const normalizedScope = normalizeInstallScope(scope);
+  const normalizedSkillName = normalizeBundledSkillName(skillName);
+  const root = resolveScopeRoot(projectRoot, normalizedScope);
+  switch (hostName) {
+    case "claude":
+      return path.join(root, ".claude", "skills", normalizedSkillName);
+    case "codex":
+    case "opencode":
+    case "cursor":
+      return path.join(root, ".agents", "skills", normalizedSkillName);
+    case "openclaw": {
+      if (normalizedScope === "global") {
+        return path.join(
+          resolveOpenClawGlobalSkillsRoot(root),
+          normalizedSkillName,
+        );
+      }
+      return path.join(root, "skills", normalizedSkillName);
+    }
+    case "pi-mono":
+      if (normalizedScope === "global") {
+        return path.join(root, ".pi", "agent", "skills", normalizedSkillName);
+      }
+      return path.join(root, ".pi", "skills", normalizedSkillName);
+    default:
+      throw new Error(`--install-skill is not supported for host '${hostName}'.`);
+  }
+}
+
+function resolveProjectSkillsLockPath(projectRoot) {
+  return path.join(projectRoot, "skills-lock.json");
+}
+
+async function pathExists(targetPath) {
+  try {
+    await access(targetPath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function createBackupDirPath(backupRoot) {
+  const backupSnapshotRoot = await mkdtemp(path.join(backupRoot, "snapshot-"));
+  return path.join(backupSnapshotRoot, "artifact");
+}
+
+async function inspectInstalledSkillDir({
+  backupRoot,
+  installedSkillDir,
+}) {
+  try {
+    const stats = await lstat(installedSkillDir);
+    if (stats.isSymbolicLink()) {
+      return {
+        installedSkillDir,
+        hadInstalledSkillDir: true,
+        priorArtifactKind: "symlink",
+        backupDir: null,
+        symlinkTarget: await readlink(installedSkillDir),
+      };
+    }
+    if (!stats.isDirectory()) {
+      throw new Error(
+        `Installed skill path '${installedSkillDir}' must be a directory or symlink.`,
+      );
+    }
+
+    const backupDir = await createBackupDirPath(backupRoot);
+    await cp(installedSkillDir, backupDir, { recursive: true });
+    return {
+      installedSkillDir,
+      hadInstalledSkillDir: true,
+      priorArtifactKind: "directory",
+      backupDir,
+      symlinkTarget: null,
+    };
+  } catch (error) {
+    if (error && typeof error === "object" && "code" in error && error.code === "ENOENT") {
+      return {
+        installedSkillDir,
+        hadInstalledSkillDir: false,
+        priorArtifactKind: null,
+        backupDir: null,
+        symlinkTarget: null,
+      };
+    }
+    throw error;
+  }
+}
+
+export async function inspectInstalledSkillArtifactsForHosts({
+  projectRoot = process.cwd(),
+  hostNames = [],
+  scope = "project",
+  skillNames,
+} = {}) {
+  const normalizedScope = normalizeInstallScope(scope);
+  const normalizedSkillNames = normalizeBundledSkillNames(skillNames);
+  const skillsLockPath =
+    normalizedScope === "project"
+      ? resolveProjectSkillsLockPath(projectRoot)
+      : null;
+  const hadSkillsLock = skillsLockPath ? await pathExists(skillsLockPath) : false;
+  const skillsLockContents =
+    hadSkillsLock && skillsLockPath
+      ? await readFile(skillsLockPath, "utf8").catch(() => null)
+      : null;
+  const backupRoot = await mkdtemp(
+    path.join(os.tmpdir(), "flywheel-install-skill-backup-"),
+  );
+  const skillStates = new Map();
+
+  for (const skillName of normalizedSkillNames) {
+    const installedSkillDirs = resolveInstalledSkillDirsForHosts(
+      projectRoot,
+      hostNames,
+      normalizedScope,
+      skillName,
+    );
+    const skillState = {
+      installedSkillDirs: [],
+    };
+
+    for (const installedSkillDir of installedSkillDirs) {
+      // eslint-disable-next-line no-await-in-loop
+      skillState.installedSkillDirs.push(
+        await inspectInstalledSkillDir({
+          backupRoot,
+          installedSkillDir,
+        }),
+      );
+    }
+
+    skillStates.set(skillName, skillState);
+  }
+
+  return {
+    backupRoot,
+    skillStates,
+    skillsLockPath,
+    hadSkillsLock,
+    skillsLockContents,
+  };
+}
+
+export async function installBundledSkillForHosts({
+  projectRoot = process.cwd(),
+  hostNames = [],
+  scope = "project",
+  serverName = DEFAULT_SKILL_MCP_SERVER_NAME,
+  serverUrl = DEFAULT_SKILL_MCP_SERVER_URL,
+  skillNames,
+} = {}) {
+  const packageRoot = resolvePackageRoot();
+  const skillsCliPath = resolveSkillsCliPath(packageRoot);
+  const normalizedScope = normalizeInstallScope(scope);
+  const normalizedSkillNames = normalizeBundledSkillNames(skillNames);
+  const resolvedServerName =
+    String(serverName || "").trim() || DEFAULT_SKILL_MCP_SERVER_NAME;
+  const resolvedServerUrl =
+    String(serverUrl || "").trim() || DEFAULT_SKILL_MCP_SERVER_URL;
+  const shouldStageSkillSource =
+    resolvedServerName !== DEFAULT_SKILL_MCP_SERVER_NAME ||
+    resolvedServerUrl !== DEFAULT_SKILL_MCP_SERVER_URL;
+
+  for (const skillName of normalizedSkillNames) {
+    const bundledSkillDir = resolveBundledSkillDir(packageRoot, skillName);
+    let installSkillSourceDir = bundledSkillDir;
+    let stagedSkillSourceRoot = null;
+    if (shouldStageSkillSource) {
+      // The stage root must be unique per skill so rewrites do not overlap.
+      stagedSkillSourceRoot = await mkdtemp(
+        path.join(os.tmpdir(), `flywheel-install-skill-${skillName}-`),
+      );
+      installSkillSourceDir = path.join(stagedSkillSourceRoot, skillName);
+      await cp(bundledSkillDir, installSkillSourceDir, { recursive: true });
+      await rewriteOpenAiAgentMetadataMcpTarget({
+        skillDir: installSkillSourceDir,
+        serverName: resolvedServerName,
+        serverUrl: resolvedServerUrl,
+      });
+    }
+
+    try {
+      for (const hostName of uniqueValues(hostNames)) {
+        const agentName = resolveSkillsAgentName(hostName);
+        const addArgs = [
+          skillsCliPath,
+          "add",
+          installSkillSourceDir,
+          "--agent",
+          agentName,
+          "--copy",
+          "--yes",
+        ];
+        if (normalizedScope === "global") {
+          addArgs.push("--global");
+        }
+        // eslint-disable-next-line no-await-in-loop
+        await execFile(process.execPath, addArgs, {
+          cwd: projectRoot,
+          env: process.env,
+        });
+      }
+    } finally {
+      if (stagedSkillSourceRoot) {
+        await rm(stagedSkillSourceRoot, { force: true, recursive: true });
+      }
+    }
+  }
+}
+
+async function rewriteOpenAiAgentMetadataMcpTarget({
+  skillDir,
+  serverName,
+  serverUrl,
+}) {
+  const openAiAgentMetadataPath = path.join(
+    skillDir,
+    OPENAI_AGENT_METADATA_RELATIVE_PATH,
+  );
+  let metadataRaw = "";
+  try {
+    metadataRaw = await readFile(openAiAgentMetadataPath, "utf8");
+  } catch {
+    return;
+  }
+
+  const metadata = loadYaml(metadataRaw);
+  if (!metadata || typeof metadata !== "object" || Array.isArray(metadata)) {
+    return;
+  }
+  const dependencies = metadata.dependencies;
+  if (!dependencies || typeof dependencies !== "object" || Array.isArray(dependencies)) {
+    return;
+  }
+  const tools = dependencies.tools;
+  if (!Array.isArray(tools)) {
+    return;
+  }
+
+  let didRewrite = false;
+  for (const tool of tools) {
+    if (!tool || typeof tool !== "object" || Array.isArray(tool)) {
+      continue;
+    }
+    if (tool.type !== "mcp") {
+      continue;
+    }
+
+    if (tool.value !== serverName) {
+      tool.value = serverName;
+      didRewrite = true;
+    }
+    if (tool.url !== serverUrl) {
+      tool.url = serverUrl;
+      didRewrite = true;
+    }
+  }
+
+  if (!didRewrite) {
+    return;
+  }
+
+  await writeFile(openAiAgentMetadataPath, dumpYaml(metadata, { noRefs: true }), {
+    encoding: "utf8",
+    mode: 0o600,
+  });
+}
+
+export async function cleanupInstalledSkillArtifactsForHosts({
+  projectRoot = process.cwd(),
+  hostNames = [],
+  priorState = null,
+  scope = "project",
+  skillNames,
+} = {}) {
+  const normalizedScope = normalizeInstallScope(scope);
+  const normalizedSkillNames = normalizeBundledSkillNames(skillNames);
+  const skillStates =
+    priorState?.skillStates ??
+    new Map(
+      normalizedSkillNames.map((skillName) => [
+        skillName,
+        {
+          installedSkillDirs: resolveInstalledSkillDirsForHosts(
+            projectRoot,
+            hostNames,
+            normalizedScope,
+            skillName,
+          ).map((installedSkillDir) => ({
+            installedSkillDir,
+            hadInstalledSkillDir: false,
+            priorArtifactKind: null,
+            backupDir: null,
+            symlinkTarget: null,
+          })),
+        },
+      ]),
+    );
+
+  for (const skillName of normalizedSkillNames) {
+    const skillState = skillStates.get(skillName) ?? { installedSkillDirs: [] };
+    for (const installedSkillState of skillState.installedSkillDirs) {
+      const {
+        installedSkillDir,
+        priorArtifactKind,
+        backupDir,
+        symlinkTarget,
+      } = installedSkillState;
+      if (priorArtifactKind === "directory") {
+        // eslint-disable-next-line no-await-in-loop
+        await rm(installedSkillDir, { force: true, recursive: true });
+        // eslint-disable-next-line no-await-in-loop
+        await mkdir(path.dirname(installedSkillDir), { recursive: true });
+        // eslint-disable-next-line no-await-in-loop
+        await cp(backupDir, installedSkillDir, { recursive: true });
+        continue;
+      }
+      if (priorArtifactKind === "symlink") {
+        // eslint-disable-next-line no-await-in-loop
+        await rm(installedSkillDir, { force: true, recursive: true });
+        // eslint-disable-next-line no-await-in-loop
+        await mkdir(path.dirname(installedSkillDir), { recursive: true });
+        // eslint-disable-next-line no-await-in-loop
+        await symlink(symlinkTarget, installedSkillDir);
+        continue;
+      }
+      // eslint-disable-next-line no-await-in-loop
+      await rm(installedSkillDir, { force: true, recursive: true });
+    }
+  }
+
+  const removeSkillsLock =
+    normalizedScope === "project" && !(priorState?.hadSkillsLock ?? false);
+  if (
+    normalizedScope === "project" &&
+    (priorState?.hadSkillsLock ?? false) &&
+    priorState?.skillsLockPath &&
+    typeof priorState.skillsLockContents === "string"
+  ) {
+    await writeFile(priorState.skillsLockPath, priorState.skillsLockContents, {
+      encoding: "utf8",
+      mode: 0o600,
+    });
+  } else if (removeSkillsLock && priorState?.skillsLockPath) {
+    await rm(priorState.skillsLockPath, { force: true });
+  } else if (removeSkillsLock) {
+    await rm(resolveProjectSkillsLockPath(projectRoot), { force: true });
+  }
+
+  if (priorState?.backupRoot) {
+    await rm(priorState.backupRoot, { force: true, recursive: true });
+  }
+}