@seeed-studio/solution-cli 0.0.0-stage → 0.1.0

package/lib/detector.js

@@ -0,0 +1,321 @@
+import os from 'node:os';
+import path from 'node:path';
+import fs from 'node:fs';
+import { execFileSync } from 'node:child_process';
+import { getScHome, getEngineBinaryPath, isExecutable } from './platform.js';
+
+const MIN_COMPATIBLE_VERSION = '0.0.3';
+
+// Strict SemVer 2.0 parser (Codex Medium 4: Reject garbage, disallow leading zeros)
+const SEMVER_REGEX = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?$/;
+
+export function parseSemver(vStr) {
+  if (!vStr) return null;
+  const clean = vStr.trim().replace(/^v/, '');
+  const match = clean.match(SEMVER_REGEX);
+  if (!match) return null;
+
+  return {
+    major: parseInt(match[1], 10),
+    minor: parseInt(match[2], 10),
+    patch: parseInt(match[3], 10),
+    prerelease: match[4] || null,
+    raw: match[0]
+  };
+}
+
+export function compareSemver(v1Str, v2Str) {
+  const v1 = parseSemver(v1Str);
+  const v2 = parseSemver(v2Str);
+  if (!v1 || !v2) return 0;
+
+  if (v1.major !== v2.major) return v1.major > v2.major ? 1 : -1;
+  if (v1.minor !== v2.minor) return v1.minor > v2.minor ? 1 : -1;
+  if (v1.patch !== v2.patch) return v1.patch > v2.patch ? 1 : -1;
+
+  // SemVer 2.0: 1.0.0-alpha < 1.0.0 (normal version has higher precedence than prerelease)
+  if (v1.prerelease && !v2.prerelease) return -1;
+  if (!v1.prerelease && v2.prerelease) return 1;
+  if (!v1.prerelease && !v2.prerelease) return 0;
+
+  // Compare prerelease identifiers per SemVer 2.0 §11
+  const id1 = v1.prerelease.split('.');
+  const id2 = v2.prerelease.split('.');
+  const len = Math.max(id1.length, id2.length);
+
+  for (let i = 0; i < len; i++) {
+    if (id1[i] === undefined) return -1;
+    if (id2[i] === undefined) return 1;
+    if (id1[i] === id2[i]) continue;
+
+    const num1 = /^\d+$/.test(id1[i]) ? parseInt(id1[i], 10) : null;
+    const num2 = /^\d+$/.test(id2[i]) ? parseInt(id2[i], 10) : null;
+
+    if (num1 !== null && num2 !== null) {
+      return num1 > num2 ? 1 : -1;
+    }
+    if (num1 !== null && num2 === null) return -1; // numeric has lower precedence than non-numeric
+    if (num1 === null && num2 !== null) return 1;
+
+    return id1[i].localeCompare(id2[i]);
+  }
+
+  return 0;
+}
+
+export function verifyEngineBinary(binPath) {
+  const absPath = path.resolve(binPath);
+  if (!fs.existsSync(absPath) || !isExecutable(absPath)) {
+    return { valid: false, reason: 'Binary not found or not executable' };
+  }
+
+  try {
+    const rawOut = execFileSync(absPath, ['--version'], {
+      encoding: 'utf8',
+      timeout: 3000,
+      stdio: ['ignore', 'pipe', 'pipe']
+    }).trim();
+
+    // Extract exact version token (e.g. from "sensecraft-engine 0.0.3")
+    const tokens = rawOut.split(/\s+/);
+    let versionCandidate = null;
+    for (const t of tokens) {
+      if (parseSemver(t)) {
+        versionCandidate = t;
+        break;
+      }
+    }
+
+    if (!versionCandidate) {
+      return { valid: false, reason: `Unrecognized engine version format in "${rawOut}"` };
+    }
+
+    const sem = parseSemver(versionCandidate);
+    if (!sem) {
+      return { valid: false, reason: `Invalid SemVer in engine version "${versionCandidate}"` };
+    }
+
+    if (compareSemver(sem.raw, MIN_COMPATIBLE_VERSION) < 0) {
+      return {
+        valid: false,
+        version: sem.raw,
+        reason: `Version ${sem.raw} is below required minimum ${MIN_COMPATIBLE_VERSION}`
+      };
+    }
+
+    // Verify deployer capability via meta --json (Codex Medium 4: strict structure and string elements)
+    let deployers = [];
+    try {
+      const metaOut = execFileSync(absPath, ['meta', '--json'], {
+        encoding: 'utf8',
+        timeout: 4000,
+        stdio: ['ignore', 'pipe', 'pipe']
+      });
+      const meta = JSON.parse(metaOut);
+      if (
+        !meta ||
+        !Array.isArray(meta.deployers) ||
+        meta.deployers.length === 0 ||
+        !meta.deployers.every(d => typeof d === 'string' && d.length > 0 && /^[a-z0-9_]+$/.test(d))
+      ) {
+        return {
+          valid: false,
+          version: sem.raw,
+          reason: 'Engine meta --json returned invalid or empty deployers specification'
+        };
+      }
+      deployers = meta.deployers;
+    } catch (err) {
+      return {
+        valid: false,
+        version: sem.raw,
+        reason: `Engine capability validation failed (meta --json): ${err.message}`
+      };
+    }
+
+    return {
+      valid: true,
+      version: sem.raw,
+      deployers,
+      binPath: absPath
+    };
+  } catch (err) {
+    return { valid: false, reason: `Execution failed: ${err.message}` };
+  }
+}
+
+export function detectExistingEngine() {
+  const defaultBin = getEngineBinaryPath();
+  const candidates = [];
+
+  if (fs.existsSync(defaultBin)) {
+    const check = verifyEngineBinary(defaultBin);
+    if (check.valid) {
+      candidates.push({
+        source: 'default',
+        path: defaultBin,
+        version: check.version,
+        deployers: check.deployers
+      });
+    }
+  }
+
+  // Scan PATH candidates
+  const envPath = process.env.PATH || '';
+  const delimiter = os.platform() === 'win32' ? ';' : ':';
+  const binName = os.platform() === 'win32' ? 'sensecraft-engine.exe' : 'sensecraft-engine';
+
+  for (const dir of envPath.split(delimiter)) {
+    if (!dir.trim()) continue;
+    const fullPath = path.join(dir.trim(), binName);
+    if (fs.existsSync(fullPath) && isExecutable(fullPath)) {
+      // Exclude npm package's runner shim to prevent recursive loop (Codex P1)
+      try {
+        const real = fs.realpathSync(fullPath);
+        if (real.endsWith('bin/runner.js') || real.endsWith('bin\\runner.js')) {
+          continue;
+        }
+        const head = fs.readFileSync(fullPath, 'utf8', { flag: 'r' }).slice(0, 500);
+        if (head.includes('runEngineProxy') || (head.includes('#!/usr/bin/env node') && head.includes('runner.js'))) {
+          continue;
+        }
+      } catch {}
+
+      const check = verifyEngineBinary(fullPath);
+      if (check.valid) {
+        candidates.push({
+          source: 'path',
+          path: fullPath,
+          version: check.version,
+          deployers: check.deployers
+        });
+      }
+    }
+  }
+
+  if (candidates.length === 0) return null;
+  candidates.sort((a, b) => compareSemver(b.version, a.version));
+  return candidates[0];
+}
+
+export function detectDesktopApp() {
+  const p = os.platform();
+  const candidates = [];
+
+  // Check 1: Tauri app pointer at ~/.sensecraft/engine.json
+  const pointerFile = path.join(getScHome(), 'engine.json');
+  if (fs.existsSync(pointerFile)) {
+    try {
+      const data = JSON.parse(fs.readFileSync(pointerFile, 'utf8'));
+      if (data && data.bin && fs.existsSync(data.bin)) {
+        candidates.push({
+          source: 'pointer',
+          appVersion: data.app_version || 'unknown',
+          binPath: path.resolve(data.bin)
+        });
+      }
+    } catch {}
+  }
+
+  // Check 2: Standard OS installation locations
+  if (p === 'darwin') {
+    const appBase = '/Applications/SenseCraft Solution.app';
+    if (fs.existsSync(appBase)) {
+      candidates.push({
+        source: 'os_app',
+        appPath: appBase,
+        binPath: path.join(appBase, 'Contents', 'MacOS', 'sensecraft-engine'),
+        solutionsPath: path.join(appBase, 'Contents', 'Resources', '_up_', 'sensecraft-solutions', 'solutions'),
+        skillsPath: path.join(appBase, 'Contents', 'Resources', '_up_', 'sensecraft-solutions', 'skills', 'sensecraft')
+      });
+      const cacheBin = path.join(
+        os.homedir(),
+        'Library',
+        'Caches',
+        'com.seeedstudio.sensecraft-solution',
+        'sidecar',
+        'sensecraft-engine'
+      );
+      if (fs.existsSync(cacheBin)) {
+        candidates.push({
+          source: 'app_cache',
+          appPath: appBase,
+          binPath: cacheBin
+        });
+      }
+    }
+  } else if (p === 'win32') {
+    const localAppData = process.env.LOCALAPPDATA || path.join(os.homedir(), 'AppData', 'Local');
+    const programFiles = process.env.ProgramFiles || 'C:\\Program Files';
+    const appPaths = [
+      path.join(localAppData, 'Programs', 'SenseCraft Solution'),
+      path.join(programFiles, 'SenseCraft Solution')
+    ];
+    for (const appPath of appPaths) {
+      if (fs.existsSync(appPath)) {
+        candidates.push({
+          source: 'os_app',
+          appPath,
+          binPath: path.join(appPath, 'resources', 'bin', 'sensecraft-engine.exe'),
+          solutionsPath: path.join(appPath, 'resources', 'sensecraft-solutions', 'solutions'),
+          skillsPath: path.join(appPath, 'resources', 'sensecraft-solutions', 'skills', 'sensecraft')
+        });
+      }
+    }
+  } else if (p === 'linux') {
+    const linuxPaths = ['/opt/SenseCraft Solution', '/opt/sensecraft-solution', '/usr/lib/sensecraft-solution'];
+    for (const appPath of linuxPaths) {
+      if (fs.existsSync(appPath)) {
+        candidates.push({
+          source: 'os_app',
+          appPath,
+          binPath: path.join(appPath, 'sensecraft-engine'),
+          solutionsPath: path.join(appPath, 'sensecraft-solutions', 'solutions'),
+          skillsPath: path.join(appPath, 'skills', 'sensecraft')
+        });
+      }
+    }
+  }
+
+  const validCandidates = [];
+  const rejectedReasons = [];
+
+  for (const c of candidates) {
+    if (c.binPath && fs.existsSync(c.binPath)) {
+      const verified = verifyEngineBinary(c.binPath);
+      if (verified.valid) {
+        validCandidates.push({
+          ...c,
+          version: verified.version,
+          deployers: verified.deployers
+        });
+      } else {
+        rejectedReasons.push(`${c.binPath}: ${verified.reason}`);
+      }
+    }
+  }
+
+  if (validCandidates.length > 0) {
+    validCandidates.sort((a, b) => compareSemver(b.version, a.version));
+    const chosen = validCandidates[0];
+    return {
+      detected: true,
+      compatible: true,
+      binPath: chosen.binPath,
+      version: chosen.version,
+      appPath: chosen.appPath,
+      solutionsPath: chosen.solutionsPath && fs.existsSync(chosen.solutionsPath) ? chosen.solutionsPath : null,
+      skillsPath: chosen.skillsPath && fs.existsSync(chosen.skillsPath) ? chosen.skillsPath : null
+    };
+  }
+
+  if (rejectedReasons.length > 0) {
+    return {
+      detected: true,
+      compatible: false,
+      reason: rejectedReasons.join('; ')
+    };
+  }
+
+  return { detected: false };
+}

package/lib/doctor.js

@@ -0,0 +1,179 @@
+import os from 'node:os';
+import path from 'node:path';
+import fs from 'node:fs';
+import { execFileSync } from 'node:child_process';
+import { getPlatformInfo, getEngineBinDir, getEngineBinaryPath, getConfiguredEnginePath, getContentDir } from './platform.js';
+import { verifyEngineBinary } from './detector.js';
+import { loadLedger, computeFileHash } from './ledger.js';
+
+export function runDoctor() {
+  const platform = getPlatformInfo();
+  const checks = [];
+
+  // Check 1: Platform & Architecture
+  if (platform.supported) {
+    checks.push({
+      id: 'platform',
+      status: 'ok',
+      title: 'Host Platform & Architecture',
+      detail: `${platform.platform} (${platform.arch}) -> target ${platform.target}`
+    });
+  } else {
+    checks.push({
+      id: 'platform',
+      status: 'fail',
+      title: 'Host Platform & Architecture',
+      detail: platform.note
+    });
+  }
+
+  // Check 2: Engine Binary
+  const binPath = getConfiguredEnginePath();
+  const engineCheck = verifyEngineBinary(binPath);
+  if (engineCheck.valid) {
+    checks.push({
+      id: 'engine_binary',
+      status: 'ok',
+      title: 'SenseCraft Engine Binary',
+      detail: `v${engineCheck.version} at ${binPath} (${engineCheck.deployers?.length || 0} deployers verified)`
+    });
+  } else {
+    checks.push({
+      id: 'engine_binary',
+      status: 'warn',
+      title: 'SenseCraft Engine Binary',
+      detail: `${engineCheck.reason || 'Not installed'}. Run "sensecraft install" to provision.`
+    });
+  }
+
+  // Check 3: PATH Configuration
+  const binDir = getEngineBinDir();
+  const envPath = process.env.PATH || '';
+  const delimiter = platform.isWindows ? ';' : ':';
+  const isInPath = envPath.split(delimiter).some(p => path.resolve(p) === path.resolve(binDir));
+
+  if (isInPath) {
+    checks.push({
+      id: 'path',
+      status: 'ok',
+      title: 'Shell PATH Configuration',
+      detail: `Directory ${binDir} is present in $PATH`
+    });
+  } else {
+    const isWin = platform.isWindows;
+    const fixCmd = isWin
+      ? `[Environment]::SetEnvironmentVariable("Path", $env:Path + ";${binDir}", "User")`
+      : `export PATH="${binDir}:$PATH" (add to ~/.bashrc or ~/.zshrc)`;
+    checks.push({
+      id: 'path',
+      status: 'warn',
+      title: 'Shell PATH Configuration',
+      detail: `${binDir} is not in $PATH. Note: Skills use absolute paths, but for manual CLI use run: ${fixCmd}`
+    });
+  }
+
+  // Check 4: Solution Content Cache
+  const contentDir = getContentDir();
+  const manifestFile = path.join(contentDir, 'manifest.json');
+  const solutionsDir = path.join(contentDir, 'solutions');
+
+  if (fs.existsSync(manifestFile) && fs.existsSync(solutionsDir)) {
+    try {
+      const solutionEntries = fs.readdirSync(solutionsDir).filter(f => !f.startsWith('.'));
+      checks.push({
+        id: 'content',
+        status: 'ok',
+        title: 'IoT Solutions Catalog',
+        detail: `${solutionEntries.length} solutions cached in ${solutionsDir}`
+      });
+    } catch {
+      checks.push({
+        id: 'content',
+        status: 'warn',
+        title: 'IoT Solutions Catalog',
+        detail: 'Catalog exists but could not read solutions directory.'
+      });
+    }
+  } else {
+    checks.push({
+      id: 'content',
+      status: 'warn',
+      title: 'IoT Solutions Catalog',
+      detail: 'No local solution catalog cached. Run "sensecraft-engine content pull".'
+    });
+  }
+
+  // Check 5: Docker daemon
+  try {
+    execFileSync('docker', ['info'], { stdio: 'ignore', timeout: 3000 });
+    checks.push({
+      id: 'docker',
+      status: 'ok',
+      title: 'Docker Daemon',
+      detail: 'Docker CLI and daemon accessible for container deployments'
+    });
+  } catch {
+    checks.push({
+      id: 'docker',
+      status: 'warn',
+      title: 'Docker Daemon',
+      detail: 'Docker not running or current user lacks access. (Only needed for local Docker deployments)'
+    });
+  }
+
+  // Check 6: Linux serial permissions
+  if (platform.platform === 'linux') {
+    try {
+      const groups = execFileSync('groups', { encoding: 'utf8', timeout: 2000 }).trim();
+      const hasDialout = groups.includes('dialout') || groups.includes('uucp');
+      if (hasDialout) {
+        checks.push({
+          id: 'serial_permission',
+          status: 'ok',
+          title: 'Serial Port Permissions',
+          detail: 'User belongs to dialout/uucp group'
+        });
+      } else {
+        checks.push({
+          id: 'serial_permission',
+          status: 'warn',
+          title: 'Serial Port Permissions',
+          detail: 'User not in "dialout" group. USB serial flashing may require: sudo usermod -aG dialout $USER'
+        });
+      }
+    } catch {}
+  }
+
+  // Check 7: Skill Ledger
+  const ledger = loadLedger();
+  const installEntries = Object.entries(ledger.installations || {});
+  if (installEntries.length > 0) {
+    let allIntact = true;
+    for (const [agentId, rec] of installEntries) {
+      for (const [rel, recordedHash] of Object.entries(rec.files || {})) {
+        const full = path.join(rec.target_dir, rel);
+        if (!fs.existsSync(full) || computeFileHash(full) !== recordedHash) {
+          allIntact = false;
+          break;
+        }
+      }
+    }
+    checks.push({
+      id: 'skills_ledger',
+      status: allIntact ? 'ok' : 'warn',
+      title: 'Agent Skills Tracking',
+      detail: `${installEntries.length} agent(s) tracked. Status: ${allIntact ? 'all files intact' : 'files modified or missing'}`
+    });
+  }
+
+  const overall = checks.some(c => c.status === 'fail')
+    ? 'fail'
+    : checks.some(c => c.status === 'warn')
+      ? 'warn'
+      : 'ok';
+
+  return {
+    overall,
+    checks
+  };
+}