skillcaddy 0.27.0

package/lib/webManager.js

@@ -0,0 +1,370 @@
+import { createHash } from 'node:crypto';
+import { execFile, spawn as childSpawn } from 'node:child_process';
+import { readFile as fsReadFile, rm as fsRm, writeFile as fsWriteFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { setTimeout as sleep } from 'node:timers/promises';
+import { promisify } from 'node:util';
+import http from 'node:http';
+
+const execFileAsync = promisify(execFile);
+
+export const DEFAULT_WEB_HOST = '127.0.0.1';
+export const DEFAULT_WEB_PORT = 4173;
+export const DEFAULT_START_TIMEOUT_MS = 5000;
+export const DEFAULT_STOP_TIMEOUT_MS = 2000;
+
+function normalizePort(port) {
+  const value = Number(port);
+  if (!Number.isInteger(value) || value < 1 || value > 65535) {
+    throw new Error(`invalid Web port: ${port}`);
+  }
+  return value;
+}
+
+function runtimeFileName(rootDir, port) {
+  const digest = createHash('sha256')
+    .update(`${path.resolve(rootDir)}:${port}`)
+    .digest('hex')
+    .slice(0, 16);
+  return `skillcaddy-web-${digest}.json`;
+}
+
+export function getRuntimePath(rootDir, port = DEFAULT_WEB_PORT, runtimeDir = tmpdir()) {
+  return path.join(runtimeDir, runtimeFileName(rootDir, normalizePort(port)));
+}
+
+export function buildWebUrl({ host = DEFAULT_WEB_HOST, port = DEFAULT_WEB_PORT, projectPath } = {}) {
+  const normalizedPort = normalizePort(port);
+  const url = new URL(`http://${host}:${normalizedPort}/`);
+  if (projectPath) {
+    url.searchParams.set('projectPath', path.resolve(projectPath));
+  }
+  return url.toString();
+}
+
+function defaultProbe({ host, port, timeoutMs = 500 } = {}) {
+  return new Promise((resolve) => {
+    const request = http.get(
+      {
+        host,
+        port,
+        path: '/api/version',
+        timeout: timeoutMs,
+      },
+      (response) => {
+        response.resume();
+        resolve(true);
+      },
+    );
+
+    request.on('timeout', () => {
+      request.destroy();
+      resolve(false);
+    });
+    request.on('error', () => resolve(false));
+  });
+}
+
+function defaultIsAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    if (error?.code === 'ESRCH') return false;
+    if (error?.code === 'EPERM') return true;
+    throw error;
+  }
+}
+
+async function defaultIsOwned(record) {
+  if (process.platform === 'win32') {
+    return false;
+  }
+
+  try {
+    const { stdout } = await execFileAsync('ps', ['-p', String(record.pid), '-o', 'command=']);
+    const command = stdout.trim();
+    return command.includes(record.serverEntry) && command.includes(record.rootDir);
+  } catch {
+    return false;
+  }
+}
+
+function defaultTerminate(pid) {
+  process.kill(pid, 'SIGTERM');
+}
+
+function defaultOpenBrowser(url) {
+  const command = process.platform === 'darwin'
+    ? ['open', [url]]
+    : process.platform === 'win32'
+      ? ['cmd', ['/c', 'start', '', url]]
+      : ['xdg-open', [url]];
+
+  return new Promise((resolve) => {
+    const child = childSpawn(command[0], command[1], { detached: true, stdio: 'ignore' });
+    child.once('error', () => resolve(false));
+    child.unref();
+    resolve(true);
+  });
+}
+
+function makeDependencies(overrides = {}) {
+  return {
+    readFile: fsReadFile,
+    writeFile: fsWriteFile,
+    rm: fsRm,
+    spawn: childSpawn,
+    probe: defaultProbe,
+    isAlive: defaultIsAlive,
+    isOwned: defaultIsOwned,
+    terminate: defaultTerminate,
+    wait: sleep,
+    openBrowser: defaultOpenBrowser,
+    now: () => new Date().toISOString(),
+    ...overrides,
+  };
+}
+
+/**
+ * 子进程环境。原件库根通过 SKILLCADDY_ROOT 传给 server.js，
+ * 让 Web 侧的原件库与 CLI 侧解析到同一个目录。
+ */
+function buildChildEnv(libraryRoot, port) {
+  const env = { ...process.env, PORT: String(port) };
+  if (libraryRoot) env.SKILLCADDY_ROOT = path.resolve(libraryRoot);
+  return env;
+}
+
+async function readRecord(runtimePath, dependencies) {
+  try {
+    const content = await dependencies.readFile(runtimePath, 'utf8');
+    const record = JSON.parse(content);
+    if (!Number.isInteger(record.pid) || record.pid < 1) {
+      throw new Error('invalid pid record');
+    }
+    return record;
+  } catch (error) {
+    if (error?.code === 'ENOENT') return null;
+    await dependencies.rm(runtimePath, { force: true }).catch(() => {});
+    return null;
+  }
+}
+
+async function removeRecord(runtimePath, dependencies, expectedPid) {
+  if (expectedPid !== undefined) {
+    const current = await readRecord(runtimePath, dependencies);
+    if (current && current.pid !== expectedPid) return false;
+  }
+  await dependencies.rm(runtimePath, { force: true });
+  return true;
+}
+
+async function waitForProbe(dependencies, { host, port, timeoutMs = DEFAULT_START_TIMEOUT_MS }) {
+  const deadline = Date.now() + timeoutMs;
+  do {
+    if (await dependencies.probe({ host, port, timeoutMs: 500 })) return true;
+    if (Date.now() >= deadline) break;
+    await dependencies.wait(100);
+  } while (Date.now() < deadline);
+  return false;
+}
+
+async function waitForExit(dependencies, pid, timeoutMs = DEFAULT_STOP_TIMEOUT_MS) {
+  const deadline = Date.now() + timeoutMs;
+  do {
+    if (!(await dependencies.isAlive(pid))) return true;
+    if (Date.now() >= deadline) break;
+    await dependencies.wait(100);
+  } while (Date.now() < deadline);
+  return false;
+}
+
+function makeRecord({ rootDir, port, serverEntry, pid, dependencies }) {
+  return {
+    pid,
+    host: DEFAULT_WEB_HOST,
+    port,
+    rootDir: path.resolve(rootDir),
+    serverEntry: path.resolve(serverEntry),
+    startedAt: dependencies.now(),
+  };
+}
+
+async function openIfRequested(dependencies, url, open) {
+  if (!open) return false;
+  try {
+    return await dependencies.openBrowser(url);
+  } catch {
+    return false;
+  }
+}
+
+export async function startWeb({
+  rootDir,
+  codeRoot,
+  libraryRoot,
+  projectPath = process.cwd(),
+  port = DEFAULT_WEB_PORT,
+  open = true,
+  runtimeDir = tmpdir(),
+  runtimePath,
+  serverEntry,
+  startTimeoutMs = DEFAULT_START_TIMEOUT_MS,
+  dependencies: dependencyOverrides,
+} = {}) {
+  if (!rootDir && !codeRoot) throw new Error('rootDir is required');
+
+  // Web 进程跑的是代码根里的 server.js；原件库根通过环境变量传给子进程，
+  // 两者解耦之后 Web 才能在任意安装形态下指向同一个原件库。
+  const resolvedCodeRoot = path.resolve(codeRoot || rootDir);
+  const resolvedServerEntry = serverEntry ? path.resolve(serverEntry) : path.join(resolvedCodeRoot, 'server.js');
+
+  const dependencies = makeDependencies(dependencyOverrides);
+  const normalizedPort = normalizePort(port);
+  const host = DEFAULT_WEB_HOST;
+  const pidPath = runtimePath ?? getRuntimePath(resolvedCodeRoot, normalizedPort, runtimeDir);
+  const url = buildWebUrl({ host, port: normalizedPort, projectPath });
+  const existing = await readRecord(pidPath, dependencies);
+
+  if (existing) {
+    if (existing.rootDir !== resolvedCodeRoot || existing.port !== normalizedPort) {
+      throw new Error(`Web PID record does not belong to ${resolvedCodeRoot}:${normalizedPort}`);
+    }
+
+    if (await dependencies.isAlive(existing.pid) && await dependencies.isOwned(existing)) {
+      const ready = await waitForProbe(dependencies, {
+        host,
+        port: normalizedPort,
+        timeoutMs: startTimeoutMs,
+      });
+      if (!ready) throw new Error(`managed Web process ${existing.pid} did not become ready`);
+      await openIfRequested(dependencies, url, open);
+      return { status: 'already-running', managed: true, pid: existing.pid, port: normalizedPort, url };
+    }
+
+    await removeRecord(pidPath, dependencies, existing.pid);
+  }
+
+  if (await dependencies.probe({ host, port: normalizedPort, timeoutMs: 500 })) {
+    await openIfRequested(dependencies, url, open);
+    return { status: 'already-running', managed: false, port: normalizedPort, url };
+  }
+
+  const child = dependencies.spawn(process.execPath, [resolvedServerEntry], {
+    cwd: resolvedCodeRoot,
+    env: buildChildEnv(libraryRoot, normalizedPort),
+    detached: true,
+    stdio: 'ignore',
+  });
+  const record = makeRecord({
+    rootDir: resolvedCodeRoot,
+    port: normalizedPort,
+    serverEntry: resolvedServerEntry,
+    pid: child.pid,
+    dependencies,
+  });
+
+  try {
+    await dependencies.writeFile(pidPath, `${JSON.stringify(record)}\n`, {
+      encoding: 'utf8',
+      flag: 'wx',
+    });
+  } catch (error) {
+    if (child.pid && typeof dependencies.terminate === 'function') {
+      await terminateBestEffort(dependencies, child.pid);
+    }
+    if (error?.code === 'EEXIST') {
+      const concurrent = await readRecord(pidPath, dependencies);
+      if (concurrent && await dependencies.isAlive(concurrent.pid)) {
+        return {
+          status: 'already-running',
+          managed: true,
+          pid: concurrent.pid,
+          port: normalizedPort,
+          url,
+        };
+      }
+    }
+    throw error;
+  }
+
+  if (typeof child.unref === 'function') child.unref();
+  const ready = await waitForProbe(dependencies, {
+    host,
+    port: normalizedPort,
+    timeoutMs: startTimeoutMs,
+  });
+  if (!ready) {
+    await terminateBestEffort(dependencies, child.pid);
+    await removeRecord(pidPath, dependencies, child.pid);
+    throw new Error(`Web process ${child.pid} did not become ready on port ${normalizedPort}`);
+  }
+
+  await openIfRequested(dependencies, url, open);
+  return { status: 'started', managed: true, pid: child.pid, port: normalizedPort, url };
+}
+
+async function terminateBestEffort(dependencies, pid) {
+  try {
+    await dependencies.terminate(pid);
+  } catch (error) {
+    if (error?.code !== 'ESRCH') throw error;
+  }
+}
+
+export async function stopWeb({
+  rootDir,
+  codeRoot,
+  port = DEFAULT_WEB_PORT,
+  runtimeDir = tmpdir(),
+  runtimePath,
+  stopTimeoutMs = DEFAULT_STOP_TIMEOUT_MS,
+  dependencies: dependencyOverrides,
+} = {}) {
+  if (!rootDir && !codeRoot) throw new Error('rootDir is required');
+
+  const resolvedCodeRoot = path.resolve(codeRoot || rootDir);
+  const dependencies = makeDependencies(dependencyOverrides);
+  const normalizedPort = normalizePort(port);
+  const host = DEFAULT_WEB_HOST;
+  const pidPath = runtimePath ?? getRuntimePath(resolvedCodeRoot, normalizedPort, runtimeDir);
+  const url = buildWebUrl({ host, port: normalizedPort });
+  const record = await readRecord(pidPath, dependencies);
+
+  if (!record) {
+    const external = await dependencies.probe({ host, port: normalizedPort, timeoutMs: 500 });
+    return { status: external ? 'not-managed' : 'not-running', managed: false, port: normalizedPort, url };
+  }
+
+  if (record.rootDir !== resolvedCodeRoot || record.port !== normalizedPort) {
+    throw new Error(`Web PID record does not belong to ${resolvedCodeRoot}:${normalizedPort}`);
+  }
+
+  if (!(await dependencies.isAlive(record.pid))) {
+    await removeRecord(pidPath, dependencies, record.pid);
+    const external = await dependencies.probe({ host, port: normalizedPort, timeoutMs: 500 });
+    return { status: external ? 'not-managed' : 'not-running', managed: !external, port: normalizedPort, url };
+  }
+
+  if (!(await dependencies.isOwned(record))) {
+    throw new Error(`refusing to stop PID ${record.pid}: process ownership could not be verified`);
+  }
+
+  await dependencies.terminate(record.pid);
+  if (!(await waitForExit(dependencies, record.pid, stopTimeoutMs))) {
+    throw new Error(`Web process ${record.pid} did not stop within ${stopTimeoutMs}ms`);
+  }
+  await removeRecord(pidPath, dependencies, record.pid);
+  return { status: 'stopped', managed: true, pid: record.pid, port: normalizedPort, url };
+}
+
+export async function restartWeb(options = {}) {
+  const stopped = await stopWeb(options);
+  if (stopped.status === 'not-managed') {
+    throw new Error(`refusing to restart an unmanaged Web process on port ${stopped.port}`);
+  }
+  const started = await startWeb(options);
+  return { status: 'restarted', stopped, started };
+}

package/package.json

@@ -0,0 +1,74 @@
+{
+  "name": "skillcaddy",
+  "version": "0.27.0",
+  "description": "Local skill source library with project, global, and Hermes symlink scopes.",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "skillcaddy": "scripts/tui.js"
+  },
+  "files": [
+    "lib/",
+    "scripts/cli.js",
+    "scripts/source.js",
+    "scripts/tui.js",
+    "scripts/pull-github.sh",
+    "scripts/cron-sync-update-git.sh",
+    "public/",
+    "skills/",
+    "!skills/.claude",
+    "collection-metadata/",
+    "server.js",
+    "README.md",
+    "README_CN.md",
+    "CHANGELOG.md",
+    "CONTEXT.md",
+    "LICENSE"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/chenweil/skillcaddy.git"
+  },
+  "homepage": "https://github.com/chenweil/skillcaddy#readme",
+  "bugs": {
+    "url": "https://github.com/chenweil/skillcaddy/issues"
+  },
+  "keywords": [
+    "skill",
+    "skills",
+    "agent",
+    "claude-code",
+    "codex",
+    "opencode",
+    "symlink",
+    "skill-library"
+  ],
+  "scripts": {
+    "start": "node server.js",
+    "source": "node scripts/source.js",
+    "test": "node --test test/*.test.js && npm run lint:imports && npm run check:specs",
+    "test:unit": "node --test test/*.test.js",
+    "check:specs": "node scripts/check-specs.js",
+    "enable:spec-pipeline": "node scripts/enable-spec-pipeline.js",
+    "lint:imports": "node scripts/check-imports.js",
+    "lint": "node scripts/check-imports.js",
+    "install:manager": "node scripts/manager-skill.js install",
+    "check:manager": "node scripts/manager-skill.js check",
+    "install:cli": "node scripts/tui-command.js install cli",
+    "check:cli": "node scripts/tui-command.js check cli",
+    "install:tui": "node scripts/tui-command.js install tui",
+    "check:tui": "node scripts/tui-command.js check tui",
+    "migrate:metadata": "node scripts/migrate-metadata.js",
+    "pull:github": "bash scripts/pull-github.sh",
+    "tui": "node scripts/tui.js"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "tldts": "^7.4.9"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/public/agentsUi.js

@@ -0,0 +1,138 @@
+import { emptyState } from './emptyState.js';
+
+export function renderAgentsSkills({ enabled, skills, elements, onDisable, scope = 'project', isPreview = false, query = '' }) {
+  const config = scopeConfig(scope, elements);
+  const list = config.list;
+  const clearButton = config.clearButton;
+  const normalizedQuery = query.trim().toLowerCase();
+  const filtered = enabled.filter((skill) => matchesEnabledQuery(skill, skills, normalizedQuery));
+  clearButton.disabled = isPreview && config.previewOnly ? true : !enabled.some((skill) => skill.canDisable ?? skill.isSymlink);
+  if (isPreview && config.previewOnly) {
+    clearButton.title = '预览模式只读：先在下方读取你自己的项目再操作';
+  }
+  config.resultCount.hidden = !normalizedQuery;
+  config.resultCount.textContent = normalizedQuery ? `显示 ${filtered.length}/${enabled.length}` : '';
+  list.replaceChildren();
+  if (enabled.length === 0) {
+    list.append(emptyState(
+      config.emptyTitle,
+      config.emptyDetail
+    ));
+    return 0;
+  }
+  if (filtered.length === 0) {
+    list.append(emptyState('没有匹配的 skill', '换一个名称或来源，或清空上方搜索。'));
+    return 0;
+  }
+
+  filtered.forEach((skill) => {
+    const item = document.createElement('article');
+    item.className = 'enabled';
+    item.dataset.focusScope = '';
+    item.innerHTML = `
+      <div>
+        <div class="enabled-head">
+          <strong class="name"></strong>
+          <span class="tag-pill enabled-source"></span>
+        </div>
+        <p class="path"></p>
+      </div>
+      <div class="actions"></div>
+    `;
+    item.querySelector('.name').textContent = skill.alias;
+    item.querySelector('.path').textContent = skill.targetPath || skill.linkPath;
+
+    const sourceSkill = skills.find((s) => s.path === skill.targetPath);
+    const sourceChip = item.querySelector('.enabled-source');
+    if (sourceSkill) {
+      // 同名 skill 可能来自多个来源：alias 旁标注来源，否则两行同名条目无法区分。
+      sourceChip.textContent = sourceSkill.source;
+      sourceChip.title = `${sourceSkill.collection} 来源`;
+    } else {
+      sourceChip.hidden = true;
+    }
+    if (sourceSkill) {
+      const description = sourceSkill.note || sourceSkill.description;
+      if (description) item.title = description;
+    }
+
+    const button = document.createElement('button');
+    button.className = 'secondary danger';
+    button.type = 'button';
+    // 单条用「移除」，只有整栏批量才叫「清空」：此前两者共用一个词，
+    // 光看标签分不出作用域。
+    button.textContent = '移除';
+    button.dataset.focusKey = `${config.key}-remove:${skill.alias}`;
+    button.dataset.focusFallbackSelector = `${config.selector} [data-focus-key^="${config.key}-remove:"]:not(:disabled)`;
+    button.dataset.focusFallbackKey = 'enabled-search';
+    button.setAttribute('aria-label', `从${config.label} ${config.directory} 移除 ${skill.alias}${sourceSkill ? `（${sourceSkill.source}）` : ''}`);
+    button.disabled = isPreview && config.previewOnly ? true : !(skill.canDisable ?? skill.isSymlink);
+    if (isPreview && config.previewOnly) {
+      button.title = '预览模式只读：先在下方读取你自己的项目再操作';
+    }
+    button.addEventListener('click', () => onDisable(skill.alias));
+    item.querySelector('.actions').append(button);
+    list.append(item);
+  });
+  return filtered.length;
+}
+
+function matchesEnabledQuery(skill, skills, query) {
+  if (!query) return true;
+  const sourceSkill = skills.find((candidate) => candidate.path === skill.targetPath);
+  const fields = [
+    skill.alias,
+    skill.targetPath,
+    skill.linkPath,
+    sourceSkill?.name,
+    sourceSkill?.source,
+    sourceSkill?.collection,
+    sourceSkill?.description,
+    sourceSkill?.note,
+    ...(sourceSkill?.tags || [])
+  ];
+  return fields.some((value) => String(value || '').toLowerCase().includes(query));
+}
+
+function scopeConfig(scope, elements) {
+  if (scope === 'global') {
+    return {
+      key: 'global',
+      label: '全局',
+      directory: '.agents/skills',
+      list: elements.globalList,
+      clearButton: elements.disableGlobal,
+      resultCount: elements.globalResultCount,
+      selector: '#globalList',
+      previewOnly: false,
+      emptyTitle: '还没有全局 skill',
+      emptyDetail: '在原件库中选择「启用到全局」，即可让所有项目使用。'
+    };
+  }
+  if (scope === 'hermes') {
+    return {
+      key: 'hermes',
+      label: 'Hermes',
+      directory: '~/.hermes/skills',
+      list: elements.hermesList,
+      clearButton: elements.disableHermes,
+      resultCount: elements.hermesResultCount,
+      selector: '#hermesList',
+      previewOnly: false,
+      emptyTitle: '还没有 Hermes skill',
+      emptyDetail: '在原件库中选择「启用到 Hermes」，只会管理 eligible 的 official/github/personal skill。'
+    };
+  }
+  return {
+    key: 'agents',
+    label: '当前项目',
+    directory: '.agents/skills',
+    list: elements.enabledList,
+    clearButton: elements.disableAgents,
+    resultCount: elements.agentsResultCount,
+    selector: '#enabledList',
+    previewOnly: true,
+    emptyTitle: '当前项目还没有启用 skill',
+    emptyDetail: '在「Skill 原件库」里展开任意分组，点「启用 agents skill」即可加入这里。'
+  };
+}