@yottameta/yotta-skills-plugin 0.28.2 → 0.29.0

package/skills/yotta-skills/lib/host-purge.js

@@ -0,0 +1,167 @@
+'use strict';
+/**
+ * 残留目录清理核心（0.29.0 F3）：CLI 与面板共用。
+ *
+ * 只处理 state=orphan 的宿主目录 —— 全量 unlink（只删指向 Hub 的链接，含死链）
+ * → 目录移入回收站（保留 7 天，跨卷走复制 + 校验 + 删源）→ 清注册 / 链接台账
+ * → 写审计。非 Hub 链接 / 非链接内容保留并报告。
+ *
+ * fail-closed：Hub 真源 / 子目录、锁与数据桥接目录、非残留状态（可用 / 仅标记 /
+ * 未创建 / 已忽略）一律拒绝；需要人工确认时先 hub hosts mark --state orphan。
+ */
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const hubLib = require('./hub');
+const agentDirsLib = require('./agent-dirs');
+const agentDiscoveryLib = require('./agent-discovery');
+const hostsRegistryLib = require('./hosts-registry');
+
+function purgeStamp(now) {
+  const d = now instanceof Date ? now : new Date();
+  const pad = (value) => String(value).padStart(2, '0');
+  return d.getFullYear() + pad(d.getMonth() + 1) + pad(d.getDate()) + '-' +
+    pad(d.getHours()) + pad(d.getMinutes()) + pad(d.getSeconds()) + '-' + process.pid;
+}
+
+function safeOrphanName(value) {
+  const cleaned = String(value || '')
+    .replace(/[\\/:*?"<>|\s]+/g, '-')
+    .replace(/^-+|-+$/g, '');
+  return cleaned || 'host';
+}
+
+function pathKey(dir) {
+  let real = path.resolve(dir);
+  try {
+    real = fs.realpathSync.native(real);
+  } catch (_) {
+    try { real = fs.realpathSync(real); } catch (_) { /* keep resolved */ }
+  }
+  return process.platform === 'win32' ? real.toLowerCase() : real;
+}
+
+function isInside(root, target) {
+  const relative = path.relative(path.resolve(root), path.resolve(target));
+  return relative === '' || (!relative.startsWith('..') && !path.isAbsolute(relative));
+}
+
+/** 只读预检 + 清理计划（不写任何文件）。 */
+function planHostPurge(options) {
+  const opts = options || {};
+  const hubDir = path.resolve(opts.hubDir);
+  const target = path.resolve(opts.dir);
+  const homeDir = opts.homeDir || os.homedir();
+  const env = opts.env || process.env;
+
+  if (!fs.existsSync(target)) {
+    return { ok: false, code: 400, error: '目录不存在: ' + target };
+  }
+  if (isInside(hubDir, target)) {
+    return { ok: false, code: 400, error: '该目录不允许残留清理（Hub 真源 / 子目录）: ' + target };
+  }
+  if (agentDirsLib.isBridgeOnlyDir(target, { homeDir, env })) {
+    return { ok: false, code: 400, error: '锁 / 数据桥接目录不参与残留清理: ' + target };
+  }
+
+  const discovery = opts.discovery || agentDiscoveryLib.discoverHosts({ homeDir, env });
+  const host = discovery.hosts.find((item) => pathKey(item.dir) === pathKey(target));
+  const state = host ? host.state : null;
+  if (state !== 'orphan') {
+    return {
+      ok: false,
+      code: 400,
+      state,
+      error: '目标不是「残留（实体未确认）」状态' + (state ? '（当前: ' + state + '）' : '（不在发现列表）'),
+    };
+  }
+
+  const linkSlugs = [];
+  let keptLinks = 0;
+  let keptEntries = 0;
+  let entries = [];
+  try { entries = fs.readdirSync(target, { withFileTypes: true }); } catch (_) { entries = []; }
+  for (const entry of entries) {
+    const full = path.join(target, entry.name);
+    const cls = hubLib.classifyTarget(full, hubDir);
+    if (cls.kind === 'link') {
+      if (cls.inHub) linkSlugs.push(entry.name);
+      else keptLinks++;
+    } else if (cls.kind !== 'missing') {
+      keptEntries++;
+    }
+  }
+  const trashRoot = hubLib.resolveTrashRoot(hubDir, opts);
+  const label = host && host.label ? host.label : path.basename(target);
+  const trashPath = path.join(trashRoot, purgeStamp(opts.now), 'orphan-' + safeOrphanName(label));
+  return {
+    ok: true,
+    hubDir,
+    target,
+    state,
+    label,
+    linkSlugs,
+    keptLinks,
+    keptEntries,
+    trashRoot,
+    trashPath,
+  };
+}
+
+/** 执行清理：unlink → trash → 清注册 / 台账 → 审计。 */
+function applyHostPurge(options) {
+  const opts = options || {};
+  const plan = planHostPurge(opts);
+  if (!plan.ok) return plan;
+
+  const unlinkResult = hubLib.unlinkSkills({
+    hubDir: plan.hubDir,
+    targetDir: plan.target,
+    slugs: plan.linkSlugs,
+    dryRun: false,
+  });
+  const unlinkedCount = (unlinkResult.results || [])
+    .filter((item) => item.status === 'unlinked').length;
+
+  fs.mkdirSync(path.dirname(plan.trashPath), { recursive: true });
+  hubLib.moveEntryAcrossDevices(plan.target, plan.trashPath);
+  try {
+    hubLib.pruneTrash(plan.trashRoot, { days: hubLib.TRASH_RETENTION_DAYS });
+  } catch (_) { /* best-effort */ }
+
+  const registryOpts = { homeDir: opts.homeDir, env: opts.env, hub: opts.hub };
+  const registry = hostsRegistryLib.readHostsRegistry(registryOpts);
+  if (registry.hosts.some((item) => pathKey(item.dir) === pathKey(plan.target))) {
+    hostsRegistryLib.removeHost(registryOpts, { dir: plan.target });
+  }
+
+  try {
+    hubLib.appendAudit(plan.hubDir, {
+      event: 'hosts.purge',
+      dir: plan.target,
+      label: plan.label,
+      state: plan.state,
+      trashedTo: plan.trashPath,
+      unlinked: unlinkedCount,
+      keptLinks: plan.keptLinks,
+      keptEntries: plan.keptEntries,
+    });
+  } catch (_) { /* 审计失败不阻断 */ }
+
+  return {
+    ok: true,
+    dir: plan.target,
+    state: plan.state,
+    unlinkCount: unlinkedCount,
+    keptLinks: plan.keptLinks,
+    keptEntries: plan.keptEntries,
+    trashedTo: plan.trashPath,
+  };
+}
+
+module.exports = {
+  planHostPurge,
+  applyHostPurge,
+  purgeStamp,
+  safeOrphanName,
+};

package/skills/yotta-skills/lib/hosts-registry.js

@@ -0,0 +1,197 @@
+'use strict';
+/**
+ * 用户级自定义宿主注册表（0.29.0 F2）—— <root>/hosts.json。
+ *
+ * root = YOTTA_SKILLS_HOME 或 ~/.yottaskills（与 self.json 同根，独立于 Hub 目录）。
+ * schema v1：{ version, hosts:[{ dir, label, agentId, scope:"verified", note,
+ * addedAt, source:"manual", manualState? }] }
+ *
+ * 注册只影响发现 / 分发 / 收编范围：不创建目录、不改宿主配置；
+ * 移除注册绝不删除目录。
+ */
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const hubLib = require('./hub');
+const agentDirsLib = require('./agent-dirs');
+
+const HOSTS_REGISTRY_VERSION = 1;
+const LABEL_MAX_LENGTH = 48;
+const MANUAL_STATES = ['available', 'orphan', 'ignored'];
+
+function nowIso() {
+  return new Date().toISOString();
+}
+
+function resolveSkillsRoot(opts) {
+  const options = opts || {};
+  const env = options.env || process.env;
+  const explicit = options.skillsRoot || env.YOTTA_SKILLS_HOME;
+  if (explicit) return path.resolve(explicit);
+  return path.join(options.homeDir || os.homedir(), '.yottaskills');
+}
+
+function hostsRegistryPath(opts) {
+  return path.join(resolveSkillsRoot(opts), 'hosts.json');
+}
+
+function readHostsRegistry(opts) {
+  try {
+    const value = JSON.parse(fs.readFileSync(hostsRegistryPath(opts), 'utf8'));
+    if (value && typeof value === 'object' && Array.isArray(value.hosts)) {
+      return {
+        version: HOSTS_REGISTRY_VERSION,
+        hosts: value.hosts.filter((item) => item && typeof item.dir === 'string' && item.dir),
+      };
+    }
+  } catch (_) { /* missing or corrupt registry falls back to empty */ }
+  return { version: HOSTS_REGISTRY_VERSION, hosts: [] };
+}
+
+function writeHostsRegistry(opts, registry) {
+  const file = hostsRegistryPath(opts);
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const tmp = file + '.tmp-' + process.pid;
+  fs.writeFileSync(tmp, JSON.stringify({
+    version: HOSTS_REGISTRY_VERSION,
+    hosts: registry.hosts,
+  }, null, 2) + '\n', 'utf8');
+  fs.renameSync(tmp, file);
+  return file;
+}
+
+function safeRealpath(target) {
+  try {
+    return fs.realpathSync.native(target);
+  } catch (_) {
+    try {
+      return fs.realpathSync(target);
+    } catch (_) {
+      return path.resolve(target);
+    }
+  }
+}
+
+function samePath(left, right) {
+  const a = safeRealpath(left);
+  const b = safeRealpath(right);
+  if (process.platform === 'win32') return a.toLowerCase() === b.toLowerCase();
+  return a === b;
+}
+
+function isInside(root, target) {
+  const relative = path.relative(path.resolve(root), path.resolve(target));
+  return relative === '' || (!relative.startsWith('..') && !path.isAbsolute(relative));
+}
+
+/** fail-closed 校验：返回中文错误或 null。 */
+function validateHostDir(dir, opts) {
+  const target = path.resolve(dir);
+  let stat;
+  try {
+    stat = fs.statSync(target);
+  } catch (_) {
+    return '目录不存在：' + target;
+  }
+  if (!stat.isDirectory()) return '不是目录：' + target;
+  const hubDir = hubLib.resolveHubDir(opts);
+  if (samePath(target, hubDir) || isInside(hubDir, target)) {
+    return '指向 Hub 自身或子目录，不允许注册：' + target;
+  }
+  if (agentDirsLib.isBridgeOnlyDir(target, opts)) {
+    return '锁 / 数据桥接目录不允许注册：' + target;
+  }
+  return null;
+}
+
+function validateLabel(label) {
+  const value = String(label || '').trim();
+  if (!value) return 'label 不能为空';
+  if (/[\u0000-\u001f\u007f]/.test(value)) return 'label 含控制字符';
+  if (value.length > LABEL_MAX_LENGTH) return 'label 过长（最多 ' + LABEL_MAX_LENGTH + ' 字符）';
+  return null;
+}
+
+/** 注册自定义宿主目录（fail-closed；不创建目录、不改宿主配置）。 */
+function addHost(opts, input) {
+  const options = opts || {};
+  const dir = input && input.dir ? path.resolve(input.dir) : null;
+  if (!dir) return { ok: false, error: '缺少目录：hub hosts add <dir>' };
+  const guard = validateHostDir(dir, options);
+  if (guard) return { ok: false, error: guard };
+  const label = String((input && input.label) || path.basename(dir)).trim();
+  const labelError = validateLabel(label);
+  if (labelError) return { ok: false, error: labelError };
+  const agentId = input && input.agentId ? String(input.agentId).trim().toLowerCase() : null;
+
+  const registry = readHostsRegistry(options);
+  const existing = registry.hosts.find((item) => samePath(item.dir, dir));
+  if (existing) {
+    return { ok: false, error: '该目录已注册：' + dir, existing };
+  }
+  const entry = {
+    dir,
+    label,
+    agentId,
+    scope: 'verified',
+    note: (input && input.note) || null,
+    addedAt: nowIso(),
+    source: 'manual',
+  };
+  registry.hosts.push(entry);
+  writeHostsRegistry(options, registry);
+  return { ok: true, entry, registry };
+}
+
+/** 移除注册（只移除登记，绝不删除目录）。 */
+function removeHost(opts, target) {
+  const options = opts || {};
+  const registry = readHostsRegistry(options);
+  const index = registry.hosts.findIndex((item) =>
+    (target && target.dir && samePath(item.dir, target.dir)) ||
+    (target && target.id && String(item.agentId || '').toLowerCase() === String(target.id).toLowerCase()));
+  if (index < 0) return { ok: false, error: '未找到注册项' };
+  const removed = registry.hosts.splice(index, 1)[0];
+  writeHostsRegistry(options, registry);
+  return { ok: true, removed, registry };
+}
+
+/** 手动标记宿主状态（可用 / 残留 / 忽略）；条目不存在时先注册。 */
+function markHost(opts, input) {
+  const options = opts || {};
+  const state = input && input.state ? String(input.state).toLowerCase() : null;
+  if (!MANUAL_STATES.includes(state)) {
+    return { ok: false, error: '未知手动状态：' + state + '（可用 available / 残留 orphan / 忽略 ignored）' };
+  }
+  const dir = input && input.dir ? path.resolve(input.dir) : null;
+  if (!dir) return { ok: false, error: '缺少目录' };
+  const registry = readHostsRegistry(options);
+  let entry = registry.hosts.find((item) => samePath(item.dir, dir));
+  if (!entry) {
+    const added = addHost(options, { dir, label: input.label });
+    if (!added.ok) return added;
+    const refreshed = readHostsRegistry(options);
+    entry = refreshed.hosts.find((item) => samePath(item.dir, dir));
+    entry.manualState = state;
+    writeHostsRegistry(options, refreshed);
+    return { ok: true, entry, registry: refreshed };
+  }
+  entry.manualState = state;
+  writeHostsRegistry(options, registry);
+  return { ok: true, entry, registry };
+}
+
+module.exports = {
+  HOSTS_REGISTRY_VERSION,
+  MANUAL_STATES,
+  LABEL_MAX_LENGTH,
+  resolveSkillsRoot,
+  hostsRegistryPath,
+  readHostsRegistry,
+  writeHostsRegistry,
+  validateHostDir,
+  validateLabel,
+  addHost,
+  removeHost,
+  markHost,
+};

package/skills/yotta-skills/lib/hub-view-server.js

@@ -32,6 +32,9 @@ const routeFeaturesLib = require('./route-features');
 const routeDynamicLib = require('./route-dynamic');
 const providerLib = require('./provider');
 const usageLib = require('./usage-journal');
+const cliHelpLib = require('./cli-help');
+const hostsRegistryLib = require('./hosts-registry');
+const hostPurgeLib = require('./host-purge');
 
 const DEFAULT_HOST = '127.0.0.1';
 const DEFAULT_PORT = 8789;
@@ -41,7 +44,7 @@ const DEFAULT_LIMIT = 100;
 const MAX_LIMIT = 500;
 const TOKEN_HEADER = 'x-yotta-view-token';
 const TOKEN_PLACEHOLDER = '__YOTTA_VIEW_TOKEN__';
-const CONFIRM = { unlink: 'unlink', rollback: 'rollback' };
+const CONFIRM = { unlink: 'unlink', rollback: 'rollback', remove: 'remove', purge: 'purge' };
 const SLUG_RE = /^[a-z0-9][a-z0-9-]*$/;
 
 function nowIso() {
@@ -218,6 +221,14 @@ function hostsPayload(ctx) {
       installedMarks: found.installed.length,
       links: links.length,
       brokenLinks: links.filter((link) => link.status !== 'ok').length,
+      // 0.29.0 F3：宿主生命周期状态细分（面板分组 / 筛选）。
+      states: {
+        available: hosts.filter((host) => host.state === 'available').length,
+        orphan: hosts.filter((host) => host.state === 'orphan').length,
+        missing: hosts.filter((host) => host.state === 'missing').length,
+        markerOnly: hosts.filter((host) => host.state === 'marker-only').length,
+        ignored: hosts.filter((host) => host.state === 'ignored').length,
+      },
     },
   };
 }
@@ -372,6 +383,65 @@ function restoreFromSnapshot(ctx, slug, snapshotPath) {
   };
 }
 
+/**
+ * 面板删除技能的目标范围 = 已核实宿主 ∪ 本技能链接台账（与 CLI 默认范围一致）。
+ */
+function removeTargets(ctx, slug) {
+  const found = discovery(ctx);
+  const targets = [];
+  const seen = new Set();
+  const add = (dir, label, agentId) => {
+    if (!dir) return;
+    const resolved = path.resolve(dir);
+    const key = normalizeDir(resolved);
+    if (seen.has(key)) return;
+    seen.add(key);
+    targets.push({ dir: resolved, label: label || '指定目录', agentId: agentId || null });
+  };
+  for (const host of found.hosts || []) {
+    if (!host.exists || host.bridgeOnly || !host.verified) continue;
+    add(host.dir, host.label, host.agentId);
+  }
+  for (const item of hubLib.readLinkState(ctx.hubDir).links.filter((link) => link.slug === slug)) {
+    add(item.dir, item.label || '台账记录目录', item.agent);
+  }
+  return targets;
+}
+
+function removePlanPayload(ctx, slug) {
+  return hubLib.removeSkills({
+    hubDir: ctx.hubDir,
+    slug,
+    targets: removeTargets(ctx, slug),
+    dryRun: true,
+    manifest: ctx.manifest,
+    homeDir: ctx.homeDir,
+    env: ctx.env,
+  });
+}
+
+function writeRemove(ctx, body) {
+  if (String(body.confirm || '') !== CONFIRM.remove) {
+    return { code: 400, payload: { error: '破坏性操作确认不匹配；请确认后再执行。' } };
+  }
+  const slug = String(body.slug || '').trim().toLowerCase();
+  if (!SLUG_RE.test(slug)) return { code: 400, payload: { error: '技能 slug 非法。' } };
+  if (String(body.confirmSlug || '') !== slug) {
+    return { code: 400, payload: { error: '技能名确认不匹配；请输入完整 slug。' } };
+  }
+  const payload = hubLib.removeSkills({
+    hubDir: ctx.hubDir,
+    slug,
+    targets: removeTargets(ctx, slug),
+    dryRun: false,
+    manifest: ctx.manifest,
+    homeDir: ctx.homeDir,
+    env: ctx.env,
+  });
+  const code = payload.verdict === 'failed' ? 500 : payload.verdict === 'not-found' ? 404 : 200;
+  return { code, payload };
+}
+
 function writeAdopt(ctx, body) {
   if (body.skipScan || body.allowUnverified) {
     return {
@@ -465,6 +535,74 @@ function writeRollback(ctx, body) {
   return { code: result.error ? (result.code || 400) : 200, payload: result };
 }
 
+// ── 宿主注册与残留清理（0.29.0 F2/F3） ─────────────────────────────────────
+function auditViewHostEvent(ctx, entry) {
+  try {
+    if (fs.existsSync(ctx.hubDir)) hubLib.appendAudit(ctx.hubDir, entry);
+  } catch (_) { /* 审计失败不阻断主流程 */ }
+}
+
+function writeHostAdd(ctx, body) {
+  const dir = String(body.dir || '').trim();
+  if (!dir) return { code: 400, payload: { error: '缺少目录。' } };
+  const label = String(body.label || '').trim();
+  const result = hostsRegistryLib.addHost(
+    { homeDir: ctx.homeDir, env: ctx.env },
+    { dir, label: label || undefined },
+  );
+  if (!result.ok) return { code: 400, payload: { error: result.error } };
+  auditViewHostEvent(ctx, {
+    event: 'hosts.add',
+    dir: result.entry.dir,
+    label: result.entry.label,
+    agentId: result.entry.agentId,
+    via: 'view',
+  });
+  return { code: 200, payload: { action: 'hosts.add', entry: result.entry } };
+}
+
+function writeHostRemove(ctx, body) {
+  const dir = String(body.dir || '').trim();
+  if (!dir) return { code: 400, payload: { error: '缺少目录。' } };
+  const result = hostsRegistryLib.removeHost({ homeDir: ctx.homeDir, env: ctx.env }, { dir });
+  if (!result.ok) return { code: 400, payload: { error: result.error } };
+  auditViewHostEvent(ctx, {
+    event: 'hosts.remove',
+    dir: result.removed.dir,
+    label: result.removed.label,
+    agentId: result.removed.agentId,
+    via: 'view',
+  });
+  return { code: 200, payload: { action: 'hosts.remove', removed: result.removed } };
+}
+
+function writeHostPurge(ctx, body) {
+  if (String(body.confirm || '') !== CONFIRM.purge) {
+    return { code: 400, payload: { error: '破坏性操作确认不匹配；请确认后再执行。' } };
+  }
+  const dir = String(body.dir || '').trim();
+  if (!dir) return { code: 400, payload: { error: '缺少目录。' } };
+  const result = hostPurgeLib.applyHostPurge({
+    hubDir: ctx.hubDir,
+    dir,
+    homeDir: ctx.homeDir,
+    env: ctx.env,
+  });
+  if (!result.ok) return { code: result.code || 400, payload: { error: result.error, state: result.state || null } };
+  return {
+    code: 200,
+    payload: {
+      action: 'hosts.purge',
+      dir: result.dir,
+      state: result.state,
+      unlinkCount: result.unlinkCount,
+      keptLinks: result.keptLinks,
+      keptEntries: result.keptEntries,
+      trashedTo: result.trashedTo,
+    },
+  };
+}
+
 function json(res, code, value) {
   if (res.writableEnded) return;
   res.writeHead(code, {
@@ -558,7 +696,39 @@ function handleGet(ctx, pathname, url, res) {
     });
   }
   if (pathname === '/api/overview') return json(res, 200, overviewPayload(ctx));
+  if (pathname === '/api/help') {
+    return json(res, 200, {
+      version: ctx.version || '',
+      groups: cliHelpLib.CLI_HELP_MODEL,
+      quick: cliHelpLib.CLI_HELP_QUICK,
+      options: cliHelpLib.CLI_GLOBAL_OPTIONS,
+    });
+  }
+  if (pathname === '/api/skills/remove-plan') {
+    const slug = String(url.searchParams.get('slug') || '').trim().toLowerCase();
+    if (!SLUG_RE.test(slug)) return json(res, 400, { error: '技能 slug 非法。' });
+    return json(res, 200, removePlanPayload(ctx, slug));
+  }
   if (pathname === '/api/hosts') return json(res, 200, hostsPayload(ctx));
+  if (pathname === '/api/hosts/purge-plan') {
+    const dir = url.searchParams.get('dir') || '';
+    if (!dir) return json(res, 400, { error: '缺少 dir 参数（目标宿主目录）。' });
+    const plan = hostPurgeLib.planHostPurge({
+      hubDir: ctx.hubDir,
+      dir,
+      homeDir: ctx.homeDir,
+      env: ctx.env,
+    });
+    if (!plan.ok) return json(res, plan.code || 400, { error: plan.error, state: plan.state || null });
+    return json(res, 200, {
+      dir: plan.target,
+      state: plan.state,
+      unlinkCount: plan.linkSlugs.length,
+      keptLinks: plan.keptLinks,
+      keptEntries: plan.keptEntries,
+      trashedTo: plan.trashPath,
+    });
+  }
   if (pathname === '/api/adopt/scan') return json(res, 200, adoptScanPayload(ctx));
   if (pathname === '/api/links') return json(res, 200, linksPayload(ctx));
   if (pathname === '/api/links/plan') {
@@ -590,6 +760,10 @@ function handlePost(ctx, pathname, req, res) {
       if (pathname === '/api/links/apply') return writeLink(ctx, body);
       if (pathname === '/api/links/remove') return writeUnlink(ctx, body);
       if (pathname === '/api/rollback/apply') return writeRollback(ctx, body);
+      if (pathname === '/api/skills/remove') return writeRemove(ctx, body);
+      if (pathname === '/api/hosts/add') return writeHostAdd(ctx, body);
+      if (pathname === '/api/hosts/remove') return writeHostRemove(ctx, body);
+      if (pathname === '/api/hosts/purge') return writeHostPurge(ctx, body);
       return { code: 404, payload: { error: 'not found' } };
     };
     ctx.queue(run)