@klingai/plugin-cn 0.0.0-stage → 0.0.2-beta

package/lib/install.mjs

@@ -0,0 +1,910 @@
+import { spawnSync } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
+import {
+  accessSync,
+  chmodSync,
+  constants,
+  cpSync,
+  existsSync,
+  lstatSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  readlinkSync,
+  renameSync,
+  rmSync,
+  symlinkSync,
+  writeFileSync,
+} from 'node:fs';
+import { homedir } from 'node:os';
+import { basename, delimiter, dirname, join, resolve, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { PLUGIN_REGIONS, pluginRegionForPackage } from './region.mjs';
+
+const PACKAGE_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const DISTRIBUTION_PACKAGE = JSON.parse(readFileSync(join(PACKAGE_ROOT, 'package.json'), 'utf8'));
+const DISTRIBUTION = pluginRegionForPackage(DISTRIBUTION_PACKAGE.name);
+
+export const PACKAGE_NAME = DISTRIBUTION.packageName;
+export const PLUGIN_NAME = 'kling-universal';
+export const LEGACY_PLUGIN_NAME = 'kling-agent-plugin';
+export const MARKETPLACE_NAME = DISTRIBUTION.marketplaceName;
+export const MCP_SERVER_NAME = 'kling-ai';
+export const PLUGIN_DISPLAY_NAME = DISTRIBUTION.displayName;
+export const PLUGIN_BASE_URL = DISTRIBUTION.baseUrl;
+export const SKILL_HOST_PATHS = Object.freeze({
+  agents: ['.agents', 'skills'],
+  cursor: ['.cursor', 'skills'],
+  gemini: ['.gemini', 'skills'],
+  copilot: ['.copilot', 'skills'],
+  vscode: ['.copilot', 'skills'],
+  opencode: ['.config', 'opencode', 'skills'],
+  qwen: ['.qwen', 'skills'],
+  qwenwork: ['.qwenworkcn', 'skills'],
+  cline: ['.cline', 'skills'],
+  roo: ['.roo', 'skills'],
+  windsurf: ['.codeium', 'windsurf', 'skills'],
+  devin: ['.config', 'devin', 'skills'],
+  amp: ['.config', 'agents', 'skills'],
+  goose: ['.agents', 'skills'],
+  openhands: ['.agents', 'skills'],
+  factory: ['.factory', 'skills'],
+  droid: ['.factory', 'skills'],
+  kiro: ['.kiro', 'skills'],
+  junie: ['.junie', 'skills'],
+  letta: ['.letta', 'skills'],
+  qoder: ['.qoder', 'skills'],
+  qoderwork: ['.qoderwork', 'skills'],
+  codebuddy: ['.codebuddy', 'skills'],
+  workbuddy: ['.workbuddy', 'skills'],
+  'workbuddy-ai': ['.workbuddy-ai', 'skills'],
+  kimi: ['.kimi-code', 'skills'],
+  antigravity: ['.gemini', 'config', 'skills'],
+  commandcode: ['.commandcode', 'skills'],
+  trae: ['.trae', 'skills'],
+  'trae-cn': ['.trae-cn', 'skills'],
+  'trae-cli': ['.traecli', 'skills'],
+  vibe: ['.vibe', 'skills'],
+  hermes: ['.hermes', 'skills'],
+  openclaw: ['.openclaw', 'skills'],
+});
+// Codex and Pi discover the shared directory; install one copy for both.
+export const ALL_SKILL_HOST_PATHS = Object.freeze({
+  codex: ['.agents', 'skills'],
+  claude: ['.claude', 'skills'],
+  pi: ['.agents', 'skills'],
+  ...SKILL_HOST_PATHS,
+});
+
+function hostSkillPaths(host, options = {}) {
+  return (options.skillsOnly ? ALL_SKILL_HOST_PATHS : SKILL_HOST_PATHS)[host];
+}
+
+export const SUPPORTED_HOSTS = [
+  'codex',
+  'claude',
+  'pi',
+  ...Object.keys(SKILL_HOST_PATHS),
+];
+// Expand this list only after checking discovery with the actual Host runtime.
+// Native registration/discovery and Agent invocation are separate acceptance steps.
+export const DEFAULT_SKILL_HOSTS = ['codex', 'claude', 'pi', 'workbuddy', 'workbuddy-ai', 'qwenwork', 'openclaw'];
+export const SKILL_NAMES = [
+  'kling-ai-plugin',
+];
+export const LEGACY_SKILL_NAMES = [
+  'Kling AI Plugin',
+  'kling-universal',
+  'kling-universal-generate-image',
+  'kling-universal-generate-video',
+  'kling-ai',
+  'kling-ai-generate-image',
+  'kling-ai-generate-video',
+];
+const CODEX_DISCOVERED_SKILL_PATHS = [
+  ['.codex', 'skills'],
+  ['.agents', 'skills'],
+];
+
+const WRAPPER_NAME = 'kling-plugin';
+// Earlier releases exposed the private wrapper under these names.
+const LEGACY_WRAPPER_NAMES = ['kling-ai-plugin', 'kling-ai-plugin.cmd', 'kling', 'kling.cmd'];
+const MANAGED_MARKER = 'managed-by: @klingai/plugin-family';
+const LEGACY_MANAGED_MARKER = 'managed-by: @klingai/plugin';
+const SKILL_MARKER = '.kling-universal';
+const LEGACY_SKILL_MARKER = '.kling-agent-plugin';
+const MANAGED_PACKAGE_NAMES = new Set(['@klingai/plugin', ...Object.values(PLUGIN_REGIONS).map((region) => region.packageName)]);
+const PLUGIN_ENTRIES = [
+  '.mcp.json',
+  '.claude-plugin',
+  '.codex-plugin',
+  '.workbuddy-plugin',
+  'assets',
+  'bin',
+  'dist',
+  'lib',
+  'mcp.json',
+  'plugin.json',
+  'package.json',
+  'README.md',
+  'skills',
+];
+
+function readJson(path) {
+  return JSON.parse(readFileSync(path, 'utf8'));
+}
+
+function writeJson(path, value) {
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, `${JSON.stringify(value, null, 2)}\n`);
+}
+
+function assertPackageComplete(packageRoot) {
+  for (const entry of PLUGIN_ENTRIES) {
+    if (!existsSync(join(packageRoot, entry))) {
+      throw new Error(`Package is incomplete: missing ${entry}`);
+    }
+  }
+}
+
+function assertManagedWrapperTargets(klingHome) {
+  for (const name of [WRAPPER_NAME, `${WRAPPER_NAME}.cmd`]) {
+    const wrapper = join(klingHome, 'bin', name);
+    const content = existsSync(wrapper) ? readFileSync(wrapper, 'utf8') : '';
+    if (content && !isManagedContent(content)) {
+      throw new Error(`Refusing to overwrite an unmanaged executable: ${wrapper}`);
+    }
+  }
+}
+
+function isManagedContent(content) {
+  return content.includes(MANAGED_MARKER) || content.includes(LEGACY_MANAGED_MARKER);
+}
+
+function pathExists(path) {
+  return Boolean(lstatSync(path, { throwIfNoEntry: false }));
+}
+
+export function isManagedSkill(destination, pluginRoot) {
+  const stat = lstatSync(destination, { throwIfNoEntry: false });
+  if (stat?.isSymbolicLink()) {
+    return Boolean(pluginRoot)
+      && resolve(dirname(destination), readlinkSync(destination))
+        === join(pluginRoot, 'skills', basename(destination));
+  }
+  if (!stat?.isDirectory()) return false;
+  const marker = [SKILL_MARKER, LEGACY_SKILL_MARKER]
+    .map((name) => join(destination, name))
+    .find(existsSync);
+  if (!marker) return false;
+  const content = readFileSync(marker, 'utf8');
+  try {
+    return MANAGED_PACKAGE_NAMES.has(JSON.parse(content).managedBy);
+  } catch {
+    return isManagedContent(content);
+  }
+}
+
+function replaceSkillLink(source, destination) {
+  const parent = dirname(destination);
+  const suffix = randomUUID();
+  const next = join(parent, `.kling-next-${suffix}`);
+  const previous = join(parent, `.kling-previous-${suffix}`);
+  mkdirSync(parent, { recursive: true });
+  symlinkSync(source, next, process.platform === 'win32' ? 'junction' : 'dir');
+  try {
+    if (pathExists(destination)) renameSync(destination, previous);
+    renameSync(next, destination);
+  } catch (error) {
+    rmSync(next, { force: true });
+    if (!pathExists(destination) && pathExists(previous)) renameSync(previous, destination);
+    throw error;
+  }
+  if (pathExists(previous)) rmSync(previous, { recursive: true, force: true });
+}
+
+function replaceDirectory(source, destination) {
+  const parent = dirname(destination);
+  const next = join(parent, `.next-${process.pid}`);
+  const previous = join(parent, `.previous-${process.pid}`);
+  mkdirSync(parent, { recursive: true });
+  rmSync(next, { recursive: true, force: true });
+  rmSync(previous, { recursive: true, force: true });
+  cpSync(source, next, { recursive: true });
+  if (pathExists(destination)) renameSync(destination, previous);
+  renameSync(next, destination);
+  rmSync(previous, { recursive: true, force: true });
+}
+
+function copyPluginPackage(sourceRoot, destination, options) {
+  const staging = join(dirname(destination), `.plugin-${process.pid}`);
+  rmSync(staging, { recursive: true, force: true });
+  mkdirSync(staging, { recursive: true });
+  try {
+    for (const entry of PLUGIN_ENTRIES) {
+      const source = join(sourceRoot, entry);
+      if (!existsSync(source)) throw new Error(`Package is incomplete: missing ${entry}`);
+      cpSync(source, join(staging, entry), { recursive: true });
+    }
+    replaceDirectory(staging, destination);
+  } finally {
+    rmSync(staging, { recursive: true, force: true });
+  }
+}
+
+function createMarketplace(pluginRoot, marketplaceRoot) {
+  const staging = join(dirname(marketplaceRoot), `.marketplace-${process.pid}`);
+  rmSync(staging, { recursive: true, force: true });
+  mkdirSync(join(staging, 'plugins'), { recursive: true });
+  cpSync(pluginRoot, join(staging, 'plugins', PLUGIN_NAME), { recursive: true });
+  // Local Codex/Claude/WorkBuddy marketplaces consume their compatibility
+  // manifests. Keep the portable root manifest in the durable/npm package,
+  // but omit it from this host-specific marketplace copy so older hosts do
+  // not stop before loading .codex-plugin/.claude-plugin metadata.
+  rmSync(join(staging, 'plugins', PLUGIN_NAME, 'plugin.json'));
+
+  writeJson(join(staging, '.agents', 'plugins', 'marketplace.json'), {
+    name: MARKETPLACE_NAME,
+    interface: { displayName: PLUGIN_DISPLAY_NAME },
+    plugins: [
+      {
+        name: PLUGIN_NAME,
+        source: { source: 'local', path: `./plugins/${PLUGIN_NAME}` },
+        policy: { installation: 'AVAILABLE', authentication: 'ON_INSTALL' },
+        category: 'Creativity',
+      },
+    ],
+  });
+
+  writeJson(join(staging, '.claude-plugin', 'marketplace.json'), {
+    $schema: 'https://anthropic.com/claude-code/marketplace.schema.json',
+    name: MARKETPLACE_NAME,
+    description: `${PLUGIN_DISPLAY_NAME} official plugin marketplace`,
+    owner: { name: 'Kling AI' },
+    plugins: [
+      {
+        name: PLUGIN_NAME,
+        description: 'Universal Kling Plugin and Skills for image and video generation.',
+        source: `./plugins/${PLUGIN_NAME}`,
+        category: 'productivity',
+        homepage: PLUGIN_BASE_URL,
+      },
+    ],
+  });
+
+  writeJson(join(staging, 'marketplace.json'), {
+    name: MARKETPLACE_NAME,
+    interface: { displayName: PLUGIN_DISPLAY_NAME },
+    plugins: [
+      {
+        name: PLUGIN_NAME,
+        source: { source: 'local', path: `./plugins/${PLUGIN_NAME}` },
+        category: 'Creativity',
+      },
+    ],
+  });
+
+  replaceDirectory(staging, marketplaceRoot);
+  rmSync(staging, { recursive: true, force: true });
+}
+
+function shellQuote(value) {
+  return `'${value.replaceAll("'", `'\\''`)}'`;
+}
+
+function writeCliWrappers(klingHome, cliPath) {
+  const binDir = join(klingHome, 'bin');
+  mkdirSync(binDir, { recursive: true });
+  for (const { name, target } of [{ name: WRAPPER_NAME, target: cliPath }]) {
+    const wrapper = join(binDir, name);
+    const content = [
+      '#!/bin/sh',
+      `# ${MANAGED_MARKER}`,
+      `exec node ${shellQuote(target)} "$@"`,
+      '',
+    ].join('\n');
+    writeFileSync(wrapper, content);
+    chmodSync(wrapper, 0o755);
+    writeFileSync(
+      `${wrapper}.cmd`,
+      `@REM ${MANAGED_MARKER}\r\n@node "${target.replaceAll('"', '""')}" %*\r\n`,
+    );
+  }
+  for (const name of LEGACY_WRAPPER_NAMES) {
+    const old = join(binDir, name);
+    if (existsSync(old) && isManagedContent(readFileSync(old, 'utf8'))) rmSync(old);
+  }
+  return join(binDir, WRAPPER_NAME);
+}
+
+// Make `kling-plugin` runnable from a terminal without editing shell profiles:
+// link it into a writable directory that is already on PATH. Never overwrite a
+// command this package does not own; callers print a PATH hint when no link fits.
+export function exposeCommand(wrapper, options = {}) {
+  const userHome = resolve(options.userHome ?? homedir());
+  const pathDirs = (options.pathEnv ?? process.env.PATH ?? '').split(delimiter).filter(Boolean).map((dir) => resolve(dir));
+  const wrapperDir = resolve(dirname(wrapper));
+  if (pathDirs.includes(wrapperDir)) return { status: 'on-path', path: wrapper };
+  const preferred = (options.preferredDirs ?? [join(userHome, '.local', 'bin'), '/opt/homebrew/bin', '/usr/local/bin']).map((dir) => resolve(dir));
+  const candidates = [...preferred.filter((dir) => pathDirs.includes(dir)), ...pathDirs.filter((dir) => dir.startsWith(`${userHome}${sep}`) && !preferred.includes(dir))];
+  const conflicts = [];
+  for (const dir of candidates) {
+    const link = join(dir, WRAPPER_NAME);
+    try {
+      accessSync(dir, constants.W_OK);
+      const stat = lstatSync(link, { throwIfNoEntry: false });
+      if (stat) {
+        const ours = stat.isSymbolicLink() && resolve(dir, readlinkSync(link)) === resolve(wrapper);
+        const managed = stat.isSymbolicLink() && /[\\/]\.kling[\\/]bin[\\/]kling-plugin$/.test(resolve(dir, readlinkSync(link)));
+        if (ours) return { status: 'linked', path: link };
+        if (!managed) { conflicts.push(link); continue; }
+        rmSync(link);
+      }
+      symlinkSync(wrapper, link);
+      return { status: 'linked', path: link };
+    } catch { /* try the next PATH directory */ }
+  }
+  return conflicts.length > 0
+    ? { status: 'conflict', path: conflicts[0], reason: `${conflicts[0]} is not managed by this package` }
+    : { status: 'not-on-path', path: wrapper };
+}
+
+export function removeExposedCommand(klingHome, options = {}) {
+  const wrapper = resolve(join(klingHome, 'bin', WRAPPER_NAME));
+  const removed = [];
+  for (const dir of (options.pathEnv ?? process.env.PATH ?? '').split(delimiter).filter(Boolean)) {
+    const link = join(resolve(dir), WRAPPER_NAME);
+    try {
+      const stat = lstatSync(link, { throwIfNoEntry: false });
+      if (stat?.isSymbolicLink() && resolve(dirname(link), readlinkSync(link)) === wrapper) { rmSync(link); removed.push(link); }
+    } catch { /* not ours or not removable */ }
+  }
+  return removed;
+}
+
+function skillRootForHost(userHome, host, options = {}) {
+  const segments = hostSkillPaths(host, options);
+  return segments ? join(userHome, ...segments) : undefined;
+}
+
+function unmanagedSkillMessage(destination) {
+  return `Refusing to overwrite an unmanaged Skill: ${destination}. `
+    + `If you do not need it, move it aside (for example: mv "${destination}" "${destination}.bak") and run the installer again`;
+}
+
+function installSkillsAtRoot(skillsRoot, pluginRoot, options = {}) {
+  const version = readJson(join(pluginRoot, 'package.json')).version;
+  for (const name of SKILL_NAMES) {
+    const destination = join(skillsRoot, name);
+    if (pathExists(destination) && !isManagedSkill(destination, pluginRoot)) {
+      throw new Error(unmanagedSkillMessage(destination));
+    }
+  }
+  for (const name of SKILL_NAMES) {
+    const destination = join(skillsRoot, name);
+    const source = join(pluginRoot, 'skills', name);
+    if (options.linkSkills) {
+      replaceSkillLink(source, destination);
+    } else {
+      replaceDirectory(source, destination);
+      writeJson(join(destination, SKILL_MARKER), {
+        managedBy: PACKAGE_NAME,
+        plugin: PLUGIN_NAME,
+        skill: name,
+        version,
+      });
+    }
+  }
+  for (const name of LEGACY_SKILL_NAMES) {
+    const destination = join(skillsRoot, name);
+    if (isManagedSkill(destination, pluginRoot)) {
+      rmSync(destination, { recursive: true, force: true });
+    }
+  }
+  return skillsRoot;
+}
+
+function removeManagedSkills(skillsRoot, pluginRoot) {
+  for (const name of [...SKILL_NAMES, ...LEGACY_SKILL_NAMES]) {
+    const target = join(skillsRoot, name);
+    if (isManagedSkill(target, pluginRoot)) {
+      rmSync(target, { recursive: true, force: true });
+    }
+  }
+}
+
+function removeManagedCodexDuplicates(userHome, pluginRoot) {
+  for (const segments of CODEX_DISCOVERED_SKILL_PATHS) {
+    removeManagedSkills(join(userHome, ...segments), pluginRoot);
+  }
+}
+
+// Earlier all-host installs wrote unverified directories that can shadow shared Skills.
+// Default upgrades retire only our copies there; explicit/custom installs stay scoped.
+export function removeManagedObsoleteSkills(staged) {
+  const keep = new Set(DEFAULT_SKILL_HOSTS.map((host) => join(staged.userHome, ...ALL_SKILL_HOST_PATHS[host])));
+  const roots = new Set([...Object.values(ALL_SKILL_HOST_PATHS), ...CODEX_DISCOVERED_SKILL_PATHS]
+    .map((parts) => join(staged.userHome, ...parts)));
+  for (const root of roots) {
+    if (!keep.has(root)) removeManagedSkills(root, staged.pluginRoot);
+  }
+}
+
+function otherLinkedSkillRoots(userHome, pluginRoot, excludedRoot) {
+  const roots = new Set(Object.values(ALL_SKILL_HOST_PATHS).map((segments) => join(userHome, ...segments)));
+  return [...roots].filter((skillsRoot) => skillsRoot !== excludedRoot && existsSync(skillsRoot) && SKILL_NAMES.some((name) => {
+    const destination = join(skillsRoot, name);
+    return lstatSync(destination, { throwIfNoEntry: false })?.isSymbolicLink()
+      && isManagedSkill(destination, pluginRoot);
+  }));
+}
+
+function skillFilesReady(skillsRoot, name) {
+  try {
+    const root = join(skillsRoot, name);
+    const content = readFileSync(join(root, 'SKILL.md'), 'utf8');
+    if (!content.startsWith(`---\nname: ${name}\n`)) return false;
+    return [...content.matchAll(/\[[^\]]*\]\(([^)\s]+)\)/g)].every(([, link]) => (
+      /^[a-z]+:|^#/.test(link) || existsSync(resolve(root, link.split('#')[0]))
+    ));
+  } catch {
+    return false;
+  }
+}
+
+function skillInstallChecks(skillsRoot, pluginRoot, version) {
+  return !LEGACY_SKILL_NAMES.some((name) => isManagedSkill(join(skillsRoot, name), pluginRoot)) && SKILL_NAMES.every((name) => {
+    const destination = join(skillsRoot, name);
+    if (!isManagedSkill(destination, pluginRoot) || !skillFilesReady(skillsRoot, name)) return false;
+    if (lstatSync(destination).isSymbolicLink()) return true;
+    try {
+      const marker = readJson(join(destination, SKILL_MARKER));
+      return marker.managedBy === PACKAGE_NAME && marker.version === version;
+    } catch {
+      return false;
+    }
+  });
+}
+
+export function readInstallState(klingHome) {
+  const path = join(klingHome, 'plugins', PLUGIN_NAME, 'installations.json');
+  if (!existsSync(path)) return { skills: [], npm: [] };
+  const state = readJson(path);
+  if (state.managedBy !== 'kling-plugin-installer' || !Array.isArray(state.skills) || !Array.isArray(state.npm)) {
+    throw new Error(`Invalid install record: ${path}`);
+  }
+  return state;
+}
+
+function writeInstallState(klingHome, state) {
+  writeJson(join(klingHome, 'plugins', PLUGIN_NAME, 'installations.json'), {
+    managedBy: 'kling-plugin-installer', ...state,
+  });
+}
+
+export function recordNpmInstallation(packageRoot, options = {}) {
+  const userHome = resolve(options.userHome ?? homedir());
+  const klingHome = resolve(options.klingHome ?? process.env.KLING_HOME ?? join(userHome, '.kling'));
+  const root = resolve(packageRoot);
+  if (basename(dirname(dirname(root))) !== 'node_modules') return;
+  const manifest = readJson(join(root, 'package.json'));
+  if (!MANAGED_PACKAGE_NAMES.has(manifest.name)) return;
+  const global = options.global ?? process.env.npm_config_global === 'true';
+  const parent = dirname(dirname(dirname(root)));
+  const prefix = global && basename(parent) === 'lib' ? dirname(parent) : parent;
+  const state = readInstallState(klingHome);
+  state.npm = state.npm.filter((item) => item.path !== root);
+  state.npm.push({ name: manifest.name, path: root, prefix, global });
+  writeInstallState(klingHome, state);
+}
+
+export function installSkillDirectory(skillsDir, staged, options = {}) {
+  const skillsRoot = resolve(skillsDir);
+  installSkillsAtRoot(skillsRoot, staged.pluginRoot, options);
+  const state = readInstallState(staged.klingHome);
+  state.skills = [...new Set([...state.skills, skillsRoot])];
+  writeInstallState(staged.klingHome, state);
+  return { status: 'installed', path: skillsRoot };
+}
+
+export function doctorSkillDirectory(skillsDir, options = {}) {
+  const userHome = resolve(options.userHome ?? homedir());
+  const klingHome = resolve(options.klingHome ?? process.env.KLING_HOME ?? join(userHome, '.kling'));
+  const pluginRoot = join(klingHome, 'plugins', PLUGIN_NAME, 'current');
+  const checks = {
+    package: existsSync(join(pluginRoot, 'package.json')),
+    cli: existsSync(join(pluginRoot, 'dist', 'cli.js')),
+    mcp: existsSync(join(pluginRoot, '.mcp.json'))
+      && existsSync(join(pluginRoot, 'mcp.json')),
+    skill: SKILL_NAMES.every((name) => skillFilesReady(join(pluginRoot, 'skills'), name)),
+    wrapper: existsSync(join(klingHome, 'bin', WRAPPER_NAME)),
+    skillCli: SKILL_NAMES.every((name) => existsSync(join(resolve(skillsDir), name, 'dist', 'cli.mjs'))),
+    hostInstall: existsSync(join(pluginRoot, 'package.json'))
+      && skillInstallChecks(resolve(skillsDir), pluginRoot, readJson(join(pluginRoot, 'package.json')).version),
+  };
+  return { ok: Object.values(checks).every(Boolean), pluginRoot, checks };
+}
+
+export function uninstallSkillDirectory(skillsDir, options = {}) {
+  const userHome = resolve(options.userHome ?? homedir());
+  const klingHome = resolve(options.klingHome ?? process.env.KLING_HOME ?? join(userHome, '.kling'));
+  const pluginRoot = join(klingHome, 'plugins', PLUGIN_NAME, 'current');
+  if (options.purge && otherLinkedSkillRoots(userHome, pluginRoot, resolve(skillsDir)).length > 0) {
+    throw new Error('Cannot purge while another Host still links to the shared Kling Skills');
+  }
+  removeManagedSkills(resolve(skillsDir), pluginRoot);
+  if (options.purge) {
+    for (const name of [WRAPPER_NAME, `${WRAPPER_NAME}.cmd`, ...LEGACY_WRAPPER_NAMES]) {
+      const wrapper = join(klingHome, 'bin', name);
+      if (existsSync(wrapper) && isManagedContent(readFileSync(wrapper, 'utf8'))) rmSync(wrapper);
+    }
+    removeExposedCommand(klingHome, options);
+    rmSync(join(klingHome, 'plugins', PLUGIN_NAME), { recursive: true, force: true });
+  }
+  return { status: 'uninstalled', credentialsPreserved: true };
+}
+
+export function stagePackage(options = {}) {
+  const packageRoot = resolve(options.packageRoot ?? PACKAGE_ROOT);
+  const userHome = resolve(options.userHome ?? homedir());
+  const klingHome = resolve(options.klingHome ?? process.env.KLING_HOME ?? join(userHome, '.kling'));
+  const base = join(klingHome, 'plugins', PLUGIN_NAME);
+  const pluginRoot = join(base, 'current');
+  const marketplaceRoot = join(base, 'marketplace');
+
+  assertPackageComplete(packageRoot);
+  assertManagedWrapperTargets(klingHome);
+  copyPluginPackage(packageRoot, pluginRoot, options);
+  createMarketplace(pluginRoot, marketplaceRoot);
+  const wrapper = writeCliWrappers(klingHome, join(pluginRoot, 'dist', 'cli.js'));
+  return { packageRoot, userHome, klingHome, pluginRoot, marketplaceRoot, wrapper };
+}
+
+function commandExists(command) {
+  const result = spawnSync(command, ['--version'], { stdio: 'ignore' });
+  return result.status === 0;
+}
+
+function captureCommand(command, args) {
+  const result = spawnSync(command, args, { encoding: 'utf8' });
+  return result.status === 0 ? result.stdout : '';
+}
+
+function nativeRegistrationMatches(host, pluginRoot, version, capture = captureCommand) {
+  try {
+    if (host === 'codex') {
+      const data = JSON.parse(capture('codex', ['plugin', 'list', '--json']));
+      return data.installed?.some((item) => item.pluginId === `${PLUGIN_NAME}@${MARKETPLACE_NAME}`
+        && item.installed && item.enabled && item.version === version) ?? false;
+    }
+    if (host === 'claude') {
+      const data = JSON.parse(capture('claude', ['plugin', 'list', '--json']));
+      return data.some((item) => item.id === `${PLUGIN_NAME}@${MARKETPLACE_NAME}`
+        && item.enabled && item.version === version);
+    }
+    if (host === 'pi') {
+      return capture('pi', ['list']).includes(pluginRoot);
+    }
+  } catch {
+    return false;
+  }
+  return false;
+}
+
+function nativeHostCommand(host) {
+  return host === 'claude' ? 'claude' : host;
+}
+
+function hostInstallTarget(host, options = {}) {
+  const userHome = resolve(options.userHome ?? homedir());
+  const klingHome = resolve(options.klingHome ?? process.env.KLING_HOME ?? join(userHome, '.kling'));
+  if (hostSkillPaths(host, options)) return skillRootForHost(userHome, host, options);
+  return join(klingHome, 'plugins', PLUGIN_NAME, 'current');
+}
+
+function hasHostConfiguration(configRoot, skillsRoot, pluginRoot) {
+  if (!existsSync(configRoot)) return false;
+  return readdirSync(configRoot).some((entry) => {
+    if (join(configRoot, entry) !== skillsRoot) return true;
+    return readdirSync(skillsRoot).some((name) => !isManagedSkill(join(skillsRoot, name), pluginRoot));
+  });
+}
+
+export function detectHosts(options = {}) {
+  const userHome = resolve(options.userHome ?? homedir());
+  const klingHome = resolve(options.klingHome ?? process.env.KLING_HOME ?? join(userHome, '.kling'));
+  const pluginRoot = join(klingHome, 'plugins', PLUGIN_NAME, 'current');
+  const hasCommand = options.commandExists ?? commandExists;
+  const detected = [];
+
+  for (const host of ['codex', 'claude', 'pi']) {
+    if (hasCommand(nativeHostCommand(host))) detected.push(host);
+  }
+
+  const seenSkillRoots = new Set();
+  for (const [host, segments] of Object.entries(SKILL_HOST_PATHS)) {
+    const configRoot = join(userHome, ...segments.slice(0, -1));
+    const skillsRoot = skillRootForHost(userHome, host);
+    // Codex also discovers ~/.agents/skills. Prefer its native plugin during
+    // automatic installation so the same Skills are not loaded twice.
+    if (detected.includes('codex') && skillsRoot === join(userHome, '.agents', 'skills')) continue;
+    // --host all may have created a directory containing only our Skills.
+    // That is not evidence that the corresponding Host is installed.
+    if (!hasHostConfiguration(configRoot, skillsRoot, pluginRoot) || seenSkillRoots.has(skillsRoot)) continue;
+    seenSkillRoots.add(skillsRoot);
+    detected.push(host);
+  }
+  return detected;
+}
+
+export function uniqueInstallHosts(hosts, options = {}) {
+  const seen = new Set();
+  const unique = [];
+  for (const host of hosts) {
+    const key = hostSkillPaths(host, options)
+      ? `skills:${hostInstallTarget(host, options)}`
+      : `native:${host}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    unique.push(host);
+  }
+  return unique;
+}
+
+export function resolveInstallHosts(host, options = {}) {
+  if (host && host !== 'all') {
+    if (!SUPPORTED_HOSTS.includes(host)) throw new Error(`Unsupported host: ${host}`);
+    return [host];
+  }
+  return uniqueInstallHosts(options.includeUnverified ? SUPPORTED_HOSTS : DEFAULT_SKILL_HOSTS, { ...options, skillsOnly: true });
+}
+
+export function createInstallPlan(hosts, options = {}) {
+  const userHome = resolve(options.userHome ?? homedir());
+  const klingHome = resolve(options.klingHome ?? process.env.KLING_HOME ?? join(userHome, '.kling'));
+  const pluginRoot = join(klingHome, 'plugins', PLUGIN_NAME, 'current');
+  return {
+    dryRun: true,
+    pluginRoot,
+    wrappers: [join(klingHome, 'bin', WRAPPER_NAME)],
+    hosts: hosts.map((host) => ({
+      host,
+      mode: hostSkillPaths(host, options) ? 'skills' : 'native',
+      target: hostInstallTarget(host, { ...options, userHome, klingHome }),
+    })),
+  };
+}
+
+export function preflightInstallHosts(hosts, options = {}) {
+  const userHome = resolve(options.userHome ?? homedir());
+  const klingHome = resolve(options.klingHome ?? process.env.KLING_HOME ?? join(userHome, '.kling'));
+  const pluginRoot = join(klingHome, 'plugins', PLUGIN_NAME, 'current');
+  const hasCommand = options.commandExists ?? commandExists;
+  return hosts.map((host) => {
+    if (hostSkillPaths(host, options)) {
+      const skillsRoot = skillRootForHost(userHome, host, options);
+      const conflict = SKILL_NAMES
+        .map((name) => join(skillsRoot, name))
+        .find((destination) => pathExists(destination) && !isManagedSkill(destination, pluginRoot));
+      if (conflict) {
+        return {
+          host,
+          status: 'failed',
+          reason: unmanagedSkillMessage(conflict),
+        };
+      }
+      return { host, status: 'ready' };
+    }
+    if (!hasCommand(nativeHostCommand(host))) {
+      return { host, status: 'unavailable', reason: `${host} CLI is not installed` };
+    }
+    if (host === 'claude') {
+      const conflicts = detectClaudeConflicts({ ...options, strict: true });
+      if (conflicts.length > 0) {
+        return {
+          host,
+          status: 'conflict',
+          reason: `Another enabled plugin provides ${MCP_SERVER_NAME}: ${[...new Set(conflicts.map((item) => item.id))].join(', ')}. Keep one Kling connector in Claude Code`,
+        };
+      }
+    }
+    return { host, status: 'ready' };
+  });
+}
+
+export function detectClaudeConflicts(options = {}) {
+  const capture = options.captureCommand ?? captureCommand;
+  const managedPluginIds = new Set([`${PLUGIN_NAME}@${MARKETPLACE_NAME}`]);
+  try {
+    const plugins = JSON.parse(capture('claude', ['plugin', 'list', '--json']));
+    return plugins
+      .filter((item) => !(managedPluginIds.has(item.id) && (!item.scope || item.scope === 'user'))
+        && item.enabled && item.mcpServers?.[MCP_SERVER_NAME])
+      .map((item) => ({
+        type: 'mcp-server',
+        id: item.id,
+        scope: item.scope,
+        blocking: true,
+        remediation: 'Review the other Kling plugin in Claude Code and keep only one active kling-ai MCP registration',
+      }));
+  } catch (error) {
+    if (options.strict) throw new Error(`Cannot inspect Claude plugins before install: ${error.message}`);
+    return [];
+  }
+}
+
+function run(command, args, options = {}) {
+  const result = spawnSync(command, args, { stdio: options.quiet ? 'ignore' : 'inherit' });
+  if (result.error?.code === 'ENOENT') {
+    if (options.allowFailure) return false;
+    throw new Error(`${command} is not installed`);
+  }
+  if (result.status !== 0 && !options.allowFailure) {
+    throw new Error(`${command} ${args.join(' ')} failed with exit code ${result.status ?? 'unknown'}`);
+  }
+  return result.status === 0;
+}
+
+export function installHost(host, staged, options = {}) {
+  const runner = options.run ?? run;
+  const hasCommand = options.commandExists ?? commandExists;
+  if (!SUPPORTED_HOSTS.includes(host)) throw new Error(`Unsupported host: ${host}`);
+
+  if (hostSkillPaths(host, options)) {
+    return installSkillDirectory(skillRootForHost(staged.userHome, host, options), staged, options);
+  }
+  if (!hasCommand(nativeHostCommand(host))) {
+    throw new Error(`${host} CLI is not installed; the staged plugin remains at ${staged.pluginRoot}`);
+  }
+
+  if (host === 'codex') {
+    runner('codex', ['plugin', 'remove', `${PLUGIN_NAME}@${MARKETPLACE_NAME}`, '--json'], { allowFailure: true, quiet: true });
+    runner('codex', ['plugin', 'marketplace', 'remove', MARKETPLACE_NAME], { allowFailure: true, quiet: true });
+    runner('codex', ['plugin', 'marketplace', 'add', staged.marketplaceRoot, '--json']);
+    runner('codex', ['plugin', 'add', `${PLUGIN_NAME}@${MARKETPLACE_NAME}`, '--json']);
+    removeManagedCodexDuplicates(staged.userHome, staged.pluginRoot);
+  } else if (host === 'claude') {
+    runner('claude', ['plugin', 'uninstall', `${PLUGIN_NAME}@${MARKETPLACE_NAME}`, '--scope', 'user'], { allowFailure: true, quiet: true });
+    runner('claude', ['plugin', 'marketplace', 'remove', MARKETPLACE_NAME], { allowFailure: true, quiet: true });
+    runner('claude', ['plugin', 'marketplace', 'add', staged.marketplaceRoot]);
+    runner('claude', ['plugin', 'install', `${PLUGIN_NAME}@${MARKETPLACE_NAME}`, '--scope', 'user']);
+  } else if (host === 'pi') {
+    runner('pi', ['remove', staged.pluginRoot], { allowFailure: true, quiet: true });
+    runner('pi', ['install', staged.pluginRoot]);
+  }
+  return { status: 'installed', path: staged.pluginRoot };
+}
+
+export function doctor(host, options = {}) {
+  if (!SUPPORTED_HOSTS.includes(host)) throw new Error(`Unsupported host: ${host}`);
+  const userHome = resolve(options.userHome ?? homedir());
+  const klingHome = resolve(options.klingHome ?? process.env.KLING_HOME ?? join(userHome, '.kling'));
+  if (options.skillsOnly) {
+    return doctorSkillDirectory(skillRootForHost(userHome, host, options), { ...options, userHome, klingHome });
+  }
+  const hasCommand = options.commandExists ?? commandExists;
+  const base = join(klingHome, 'plugins', PLUGIN_NAME);
+  const pluginRoot = join(base, 'current');
+  const checks = {
+    package: existsSync(join(pluginRoot, 'package.json')),
+    cli: existsSync(join(pluginRoot, 'dist', 'cli.js')),
+    mcp: existsSync(join(pluginRoot, '.mcp.json'))
+      && existsSync(join(pluginRoot, 'mcp.json')),
+    skill: SKILL_NAMES.every((name) => skillFilesReady(join(pluginRoot, 'skills'), name)),
+    wrapper: existsSync(join(klingHome, 'bin', WRAPPER_NAME)),
+    hostCli: Boolean(SKILL_HOST_PATHS[host]) || hasCommand(nativeHostCommand(host)),
+  };
+  if (SKILL_HOST_PATHS[host]) {
+    const skillsRoot = skillRootForHost(userHome, host);
+    checks.hostInstall = checks.package
+      && skillInstallChecks(skillsRoot, pluginRoot, readJson(join(pluginRoot, 'package.json')).version);
+  } else {
+    checks.hostInstall = checks.package && checks.hostCli
+      && nativeRegistrationMatches(
+        host,
+        pluginRoot,
+        readJson(join(pluginRoot, 'package.json')).version,
+        options.captureCommand,
+      );
+  }
+  const conflicts = host === 'claude' ? detectClaudeConflicts(options) : [];
+  return {
+    ok: Object.values(checks).every(Boolean) && conflicts.every((item) => !item.blocking),
+    pluginRoot,
+    checks,
+    conflicts,
+  };
+}
+
+export function uninstallHost(host, options = {}) {
+  if (!SUPPORTED_HOSTS.includes(host)) throw new Error(`Unsupported host: ${host}`);
+  const runner = options.run ?? run;
+  const hasCommand = options.commandExists ?? commandExists;
+  const userHome = resolve(options.userHome ?? homedir());
+  const klingHome = resolve(options.klingHome ?? process.env.KLING_HOME ?? join(userHome, '.kling'));
+  const pluginRoot = join(klingHome, 'plugins', PLUGIN_NAME, 'current');
+  if (options.purge && otherLinkedSkillRoots(userHome, pluginRoot, skillRootForHost(userHome, host, options)).length > 0) {
+    throw new Error('Cannot purge while another Host still links to the shared Kling Skills');
+  }
+
+  if (options.skillsOnly) {
+    removeManagedSkills(skillRootForHost(userHome, host, options), pluginRoot);
+  } else if (host === 'codex' && hasCommand('codex')) {
+    runner('codex', ['plugin', 'remove', `${PLUGIN_NAME}@${MARKETPLACE_NAME}`, '--json'], { allowFailure: true });
+    runner('codex', ['plugin', 'marketplace', 'remove', MARKETPLACE_NAME], { allowFailure: true });
+  } else if (host === 'claude' && hasCommand('claude')) {
+    runner('claude', ['plugin', 'uninstall', `${PLUGIN_NAME}@${MARKETPLACE_NAME}`, '--scope', 'user'], { allowFailure: true });
+    runner('claude', ['plugin', 'marketplace', 'remove', MARKETPLACE_NAME], { allowFailure: true });
+  } else if (host === 'pi' && hasCommand('pi')) {
+    runner('pi', ['remove', join(klingHome, 'plugins', PLUGIN_NAME, 'current')], { allowFailure: true });
+  } else if (SKILL_HOST_PATHS[host]) {
+    removeManagedSkills(skillRootForHost(userHome, host), pluginRoot);
+  }
+
+  if (options.purge) {
+    for (const name of [WRAPPER_NAME, `${WRAPPER_NAME}.cmd`, ...LEGACY_WRAPPER_NAMES]) {
+      const wrapper = join(klingHome, 'bin', name);
+      if (existsSync(wrapper) && isManagedContent(readFileSync(wrapper, 'utf8'))) rmSync(wrapper);
+    }
+    removeExposedCommand(klingHome, options);
+    rmSync(join(klingHome, 'plugins', PLUGIN_NAME), { recursive: true, force: true });
+  }
+  return { status: 'uninstalled', credentialsPreserved: true };
+}
+
+export function parseArgs(argv) {
+  const [command = 'help', ...rest] = argv;
+  let host;
+  let skillsDir;
+  let purge = false;
+  let dryRun = false;
+  let linkSkills = false;
+  for (let index = 0; index < rest.length; index += 1) {
+    const arg = rest[index];
+    if (arg === '--host') {
+      const value = rest[index + 1];
+      if (!value || value.startsWith('--')) throw new Error('--host requires a value');
+      host = value;
+      index += 1;
+    }
+    else if (arg.startsWith('--host=')) host = arg.slice('--host='.length);
+    else if (arg === '--skills-dir') {
+      const value = rest[index + 1];
+      if (!value || value.startsWith('--')) throw new Error('--skills-dir requires a path');
+      skillsDir = value;
+      index += 1;
+    }
+    else if (arg.startsWith('--skills-dir=')) skillsDir = arg.slice('--skills-dir='.length);
+    else if (arg === '--purge') purge = true;
+    else if (arg === '--dry-run') dryRun = true;
+    else if (arg === '--link-skills') linkSkills = true;
+    else throw new Error(`Unknown argument: ${arg}`);
+  }
+  if (host !== undefined) host = host.toLowerCase();
+  if (host !== undefined && !host.trim()) throw new Error('--host requires a value');
+  if (skillsDir !== undefined && !skillsDir.trim()) throw new Error('--skills-dir requires a path');
+  if (host && skillsDir) throw new Error('Choose either --host or --skills-dir, not both');
+  if (purge && command !== 'uninstall') throw new Error('--purge is only supported by uninstall');
+  if (dryRun && command !== 'install' && command !== 'uninstall') {
+    throw new Error('--dry-run is only supported by install or complete uninstall');
+  }
+  if (dryRun && command === 'uninstall' && (host || skillsDir)) {
+    throw new Error('uninstall --dry-run previews complete uninstall; omit --host and --skills-dir');
+  }
+  if (linkSkills && command !== 'install') throw new Error('--link-skills is only supported by install');
+  if (linkSkills && (!host || host === 'all' || !SKILL_HOST_PATHS[host])) {
+    throw new Error('--link-skills requires one directory-based --host');
+  }
+  if (host && host !== 'all' && !SUPPORTED_HOSTS.includes(host)) {
+    throw new Error(`Unsupported host: ${host}. Choose: ${SUPPORTED_HOSTS.join(', ')}, all`);
+  }
+  return { command, host, skillsDir, purge, dryRun, linkSkills };
+}
+
+export function packageVersion(packageRoot = PACKAGE_ROOT) {
+  return readJson(join(packageRoot, 'package.json')).version;
+}
+
+export function displayPath(path) {
+  return basename(path) === 'marketplace.json' ? path : resolve(path);
+}