@pwddd/skills-scanner 3.0.22 → 4.0.0

package/src/scanner.ts

@@ -1,54 +1,230 @@
-/**
- * Scanner module - handles Python script execution
- */
-
-import { promisify } from "node:util";
-import { exec } from "node:child_process";
-import type { ScanOptions, ScanResult } from "./types.js";
-
-const execAsync = promisify(exec);
-
-export async function runScan(
-  pythonCmd: string | null,
-  scanScript: string,
-  mode: "scan" | "batch" | "clawhub",
-  target: string,
-  opts: ScanOptions = {}
-): Promise<ScanResult> {
-  if (!pythonCmd) {
-    return { exitCode: 1, output: "Python is not available on this host" };
-  }
-
-  const args = [mode, target];
-  if (opts.detailed) args.push("--detailed");
-  if (opts.behavioral) args.push("--behavioral");
-  if (opts.recursive) args.push("--recursive");
-  if (opts.useLLM) args.push("--llm");
-  if (opts.policy) args.push("--policy", opts.policy);
-  if (opts.jsonOut) args.push("--json", opts.jsonOut);
-  if (opts.apiUrl) args.unshift("--api-url", opts.apiUrl);
-
-  const cmd = `"${pythonCmd}" "${scanScript}" ${args.map((a) => `"${a}"`).join(" ")}`;
-
-  try {
-    const env = { ...process.env };
-    // Remove proxy env vars to avoid connection issues
-    delete env.http_proxy;
-    delete env.https_proxy;
-    delete env.HTTP_PROXY;
-    delete env.HTTPS_PROXY;
-    delete env.all_proxy;
-    delete env.ALL_PROXY;
-
-    const { stdout, stderr } = await execAsync(cmd, {
-      timeout: 180_000,
-      env,
-    });
-    return { exitCode: 0, output: (stdout + stderr).trim() };
-  } catch (err: any) {
-    return {
-      exitCode: err.code ?? 1,
-      output: (err.stdout + err.stderr || "").trim() || err.message,
-    };
-  }
-}
+/**
+ * Scanner module - calls skill-scanner-api via HTTP
+ */
+
+import { SkillScannerApiClient, type ScanResult as ApiScanResult } from "./api-client.js";
+import { recordScan } from "./metrics.js";
+import { createActionableError } from "./error-handler.js";
+
+export interface ScanOptions {
+  detailed?: boolean;
+  behavioral?: boolean;
+  recursive?: boolean;
+  jsonOut?: string;
+  apiUrl?: string;
+  useLLM?: boolean;
+  policy?: string;
+  timeoutMs?: number; // Scan timeout in milliseconds
+  stateDir?: string; // State directory for metrics
+}
+
+export interface ScanResult {
+  exitCode: number;
+  output: string;
+  data?: ApiScanResult;
+}
+
+export async function runScan(
+  mode: "scan" | "batch" | "clawhub" | "health",
+  target: string,
+  opts: ScanOptions = {}
+): Promise<ScanResult> {
+  const apiUrl = opts.apiUrl || "https://110.vemic.com/skills-scanner";
+  const timeoutMs = opts.timeoutMs || 180000; // Default 3 minutes
+  const policy = (opts.policy || "balanced") as "strict" | "balanced" | "permissive";
+  const client = new SkillScannerApiClient(apiUrl, timeoutMs);
+
+  const startTime = Date.now();
+  let success = false;
+
+  try {
+    if (mode === "health") {
+      const health = await client.health();
+      const lines = [];
+      if (health.status === "healthy") {
+        lines.push("✅ API 服务正常");
+        if (health.version) lines.push(`  版本：${health.version}`);
+        if (health.analyzers_available) {
+          lines.push(`  可用分析器：${health.analyzers_available.join(", ")}`);
+        }
+        return { exitCode: 0, output: lines.join("\n"), data: health as any };
+      } else {
+        lines.push(`❌ API 服务不可用：${apiUrl}`);
+        lines.push(`  错误：${health.error || "未知错误"}`);
+        return { exitCode: 1, output: lines.join("\n"), data: health as any };
+      }
+    }
+
+    if (mode === "clawhub") {
+      const result = await client.scanClawHub(target, {
+        policy: opts.policy as any,
+        useLLM: opts.useLLM,
+        useBehavioral: opts.behavioral,
+      });
+      const output = formatScanResult(result, opts.detailed);
+      return {
+        exitCode: result.is_safe ? 0 : 1,
+        output,
+        data: result,
+      };
+    }
+
+    if (mode === "scan") {
+      const result = await client.scanUpload(target, {
+        policy: policy as any,
+        useLLM: opts.useLLM,
+        useBehavioral: opts.behavioral,
+      });
+      const output = formatScanResult(result, opts.detailed);
+      success = true;
+
+      // Record metrics
+      if (opts.stateDir) {
+        recordScan(opts.stateDir, {
+          success: true,
+          durationMs: Date.now() - startTime,
+          policy,
+        });
+      }
+
+      return {
+        exitCode: result.is_safe ? 0 : 1,
+        output,
+        data: result,
+      };
+    }
+
+    if (mode === "batch") {
+      const { readdirSync, statSync } = await import("node:fs");
+      const { join } = await import("node:path");
+      const { existsSync } = await import("node:fs");
+
+      if (!existsSync(target)) {
+        return { exitCode: 1, output: `路径不存在：${target}` };
+      }
+
+      const skills: string[] = [];
+      const entries = readdirSync(target);
+      for (const entry of entries) {
+        const skillPath = join(target, entry);
+        if (statSync(skillPath).isDirectory() && existsSync(join(skillPath, "SKILL.md"))) {
+          skills.push(skillPath);
+        }
+      }
+
+      if (skills.length === 0) {
+        return { exitCode: 1, output: `未找到任何 Skill：${target}` };
+      }
+
+      const results: ApiScanResult[] = [];
+      const lines: string[] = [];
+      let safe = 0;
+      let unsafe = 0;
+
+      for (let i = 0; i < skills.length; i++) {
+        const skillPath = skills[i];
+        lines.push(`[${i + 1}/${skills.length}] 正在扫描：${skillPath}`);
+
+        try {
+          const result = await client.scanUpload(skillPath, {
+            policy: opts.policy as any,
+            useLLM: opts.useLLM,
+            useBehavioral: opts.behavioral,
+          });
+          results.push(result);
+          if (result.is_safe) {
+            safe++;
+            lines.push(`  ✅ ${result.skill_name}: 安全`);
+          } else {
+            unsafe++;
+            lines.push(`  ❌ ${result.skill_name}: ${result.max_severity} (${result.findings_count} 个发现)`);
+          }
+        } catch (err: any) {
+          results.push({
+            skill_name: entry,
+            is_safe: false,
+            max_severity: "ERROR",
+            findings_count: 0,
+            error: err.message,
+          });
+          lines.push(`  ❌ ${entry}: 扫描失败 - ${err.message}`);
+        }
+      }
+
+      lines.push("");
+      lines.push(`批量扫描完成：${safe} 安全，${unsafe} 问题`);
+
+      if (opts.detailed && unsafe > 0) {
+        lines.push("");
+        lines.push("问题 Skills:");
+        for (const r of results.filter((r) => !r.is_safe)) {
+          lines.push(`  • ${r.skill_name} [${r.max_severity}] - ${r.findings_count} 条发现`);
+        }
+      }
+
+      return {
+        exitCode: unsafe === 0 ? 0 : 1,
+        output: lines.join("\n"),
+      };
+    }
+
+    return { exitCode: 1, output: `未知模式：${mode}` };
+  } catch (err: any) {
+    // Record failed scan
+    if (opts.stateDir && mode !== "health") {
+      recordScan(opts.stateDir, {
+        success: false,
+        durationMs: Date.now() - startTime,
+        policy,
+      });
+    }
+
+    // Create actionable error message
+    const errorMessage = createActionableError(
+      mode === "health" ? "健康检查" : "扫描操作",
+      err,
+      {
+        apiUrl,
+        path: target,
+        mode,
+        policy,
+      }
+    );
+
+    return {
+      exitCode: 1,
+      output: errorMessage,
+    };
+  }
+}
+
+/**
+ * Format scan result for display
+ */
+function formatScanResult(result: ApiScanResult, detailed = false): string {
+  const lines: string[] = [];
+  const statusIcon = result.is_safe ? "✅" : "❌";
+
+  lines.push(`${statusIcon} ${result.skill_name}`);
+  lines.push(`  严重性：${result.max_severity}`);
+  lines.push(`  发现数：${result.findings_count}`);
+
+  if (detailed && result.findings && result.findings.length > 0) {
+    lines.push("");
+    lines.push("发现详情:");
+    for (let i = 0; i < Math.min(result.findings.length, 10); i++) {
+      const finding = result.findings[i];
+      lines.push(`  ${i + 1}. [${finding.severity}] ${finding.category}`);
+      lines.push(`     ${finding.description}`);
+      if (finding.file) {
+        lines.push(`     文件：${finding.file}${finding.line ? `:${finding.line}` : ""}`);
+      }
+    }
+
+    if (result.findings.length > 10) {
+      lines.push(`  ... 还有 ${result.findings.length - 10} 条发现`);
+    }
+  }
+
+  return lines.join("\n");
+}

package/src/state.ts

@@ -1,71 +1,119 @@
-/**
- * State management module
- */
-
-import { readFileSync, writeFileSync, mkdirSync, existsSync } from "node:fs";
-import { join } from "node:path";
-import os from "node:os";
-import type { ScanState, ScannerConfig } from "./types.js";
-
-const STATE_DIR = join(os.homedir(), ".openclaw", "skills-scanner");
-const STATE_FILE = join(STATE_DIR, "state.json");
-
-export function loadState(): ScanState {
-  try {
-    return JSON.parse(readFileSync(STATE_FILE, "utf-8"));
-  } catch {
-    return {};
-  }
-}
-
-export function saveState(s: ScanState): void {
-  mkdirSync(STATE_DIR, { recursive: true });
-  writeFileSync(STATE_FILE, JSON.stringify(s, null, 2));
-}
-
-export function isFirstRun(cfg: ScannerConfig): boolean {
-  const state = loadState() as any;
-
-  if (state.configReviewed) {
-    return false;
-  }
-
-  const isDefaultConfig =
-    !cfg.apiUrl &&
-    (!cfg.scanDirs || cfg.scanDirs.length === 0) &&
-    cfg.behavioral !== true &&
-    cfg.useLLM !== true &&
-    cfg.policy !== "strict" &&
-    cfg.policy !== "permissive" &&
-    cfg.preInstallScan !== "off" &&
-    cfg.onUnsafe !== "delete" &&
-    cfg.onUnsafe !== "warn";
-
-  return isDefaultConfig;
-}
-
-export function markConfigReviewed(): void {
-  const state = loadState() as any;
-  saveState({ ...state, configReviewed: true });
-}
-
-export function expandPath(p: string): string {
-  return p.replace(/^~/, os.homedir());
-}
-
-export function defaultScanDirs(): string[] {
-  const dirs = [
-    join(os.homedir(), ".openclaw", "skills"),
-    join(os.homedir(), ".openclaw", "workspace", "skills"),
-  ];
-
-  for (const dir of dirs) {
-    if (!existsSync(dir)) {
-      mkdirSync(dir, { recursive: true });
-    }
-  }
-
-  return dirs;
-}
-
-export { STATE_DIR, STATE_FILE };
+/**
+ * State management module
+ */
+
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import os from "node:os";
+import type { ScanState, ScannerConfig } from "./types.js";
+import type { PluginRuntime } from "openclaw/plugin-sdk/runtime-store";
+
+// Current state schema version
+const CURRENT_STATE_VERSION = 2;
+
+// Legacy fallback path (used when runtime is not available)
+const LEGACY_STATE_DIR = join(os.homedir(), ".openclaw", "skills-scanner");
+
+/**
+ * Get state directory path using official OpenClaw API
+ */
+export function getStateDir(runtime?: PluginRuntime): string {
+  if (runtime?.state?.resolveStateDir) {
+    const stateDir = runtime.state.resolveStateDir();
+    return join(stateDir, "skills-scanner");
+  }
+  // Fallback to legacy path
+  return LEGACY_STATE_DIR;
+}
+
+/**
+ * Get state file path
+ */
+export function getStateFile(runtime?: PluginRuntime): string {
+  return join(getStateDir(runtime), "state.json");
+}
+
+/**
+ * Migrate state from old versions to current version
+ */
+function migrateState(state: any): ScanState {
+  const version = state.version || 1;
+
+  if (version === CURRENT_STATE_VERSION) {
+    return state;
+  }
+
+  // Migration from v1 to v2
+  if (version === 1) {
+    // v1 didn't have version field or lastShutdownAt
+    return {
+      ...state,
+      version: 2,
+      lastShutdownAt: undefined,
+    };
+  }
+
+  // Unknown version - return as-is with current version
+  return {
+    ...state,
+    version: CURRENT_STATE_VERSION,
+  };
+}
+
+export function loadState(runtime?: PluginRuntime): ScanState {
+  try {
+    const stateFile = getStateFile(runtime);
+    const rawState = JSON.parse(readFileSync(stateFile, "utf-8"));
+    return migrateState(rawState);
+  } catch {
+    return { version: CURRENT_STATE_VERSION };
+  }
+}
+
+export function saveState(s: ScanState, runtime?: PluginRuntime): void {
+  const stateDir = getStateDir(runtime);
+  const stateFile = getStateFile(runtime);
+
+  // Ensure version is set
+  const stateWithVersion = {
+    ...s,
+    version: CURRENT_STATE_VERSION,
+  };
+
+  mkdirSync(stateDir, { recursive: true });
+  writeFileSync(stateFile, JSON.stringify(stateWithVersion, null, 2));
+}
+
+export function isFirstRun(cfg: ScannerConfig, runtime?: PluginRuntime): boolean {
+  const state = loadState(runtime) as any;
+
+  if (state.configReviewed) {
+    return false;
+  }
+
+  const isDefaultConfig =
+    !cfg.apiUrl &&
+    cfg.behavioral !== true &&
+    cfg.useLLM !== true &&
+    cfg.policy !== "strict" &&
+    cfg.policy !== "permissive" &&
+    cfg.onUnsafe !== "delete" &&
+    cfg.onUnsafe !== "warn";
+
+  return isDefaultConfig;
+}
+
+export function markConfigReviewed(runtime?: PluginRuntime): void {
+  const state = loadState(runtime) as any;
+  saveState({ ...state, configReviewed: true }, runtime);
+}
+
+export function expandPath(p: string): string {
+  return p.replace(/^~/, os.homedir());
+}
+
+// Export for backward compatibility
+export { LEGACY_STATE_DIR as STATE_DIR };
+export function STATE_FILE(runtime?: PluginRuntime): string {
+  return getStateFile(runtime);
+}

package/src/structured-logger.ts

@@ -0,0 +1,97 @@
+/**
+ * Structured logging utilities
+ */
+
+import type { PluginLogger } from "./types.js";
+
+export interface LogContext {
+  module?: string;
+  action?: string;
+  duration?: number;
+  [key: string]: any;
+}
+
+/**
+ * Log with structured context
+ */
+export function logInfo(
+  logger: PluginLogger,
+  message: string,
+  context?: LogContext
+): void {
+  if (context) {
+    logger.info(message, context);
+  } else {
+    logger.info(message);
+  }
+}
+
+export function logDebug(
+  logger: PluginLogger,
+  message: string,
+  context?: LogContext
+): void {
+  if (context) {
+    logger.debug(message, context);
+  } else {
+    logger.debug(message);
+  }
+}
+
+export function logWarn(
+  logger: PluginLogger,
+  message: string,
+  context?: LogContext
+): void {
+  if (context) {
+    logger.warn(message, context);
+  } else {
+    logger.warn(message);
+  }
+}
+
+export function logError(
+  logger: PluginLogger,
+  message: string,
+  error?: Error,
+  context?: LogContext
+): void {
+  const errorContext = {
+    ...context,
+    error: error?.message,
+    stack: error?.stack,
+  };
+  logger.error(message, errorContext);
+}
+
+/**
+ * Log operation with timing
+ */
+export async function logOperation<T>(
+  logger: PluginLogger,
+  operation: string,
+  fn: () => Promise<T>,
+  context?: LogContext
+): Promise<T> {
+  const startTime = Date.now();
+  logDebug(logger, `${operation} started`, context);
+
+  try {
+    const result = await fn();
+    const duration = Date.now() - startTime;
+    logInfo(logger, `${operation} completed`, {
+      ...context,
+      duration,
+      success: true,
+    });
+    return result;
+  } catch (error: any) {
+    const duration = Date.now() - startTime;
+    logError(logger, `${operation} failed`, error, {
+      ...context,
+      duration,
+      success: false,
+    });
+    throw error;
+  }
+}