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

package/lib/agent.js

@@ -0,0 +1,160 @@
+import os from 'node:os';
+import path from 'node:path';
+import fs from 'node:fs';
+import readline from 'node:readline';
+
+export function getKnownAgents() {
+  const home = os.homedir();
+
+  return [
+    {
+      id: 'workbuddy',
+      name: 'Work Buddy / Workbody',
+      homeDirs: [path.join(home, '.workbuddy'), path.join(home, '.workbody')],
+      getSkillsDir: () => {
+        // Check where an existing installation might already be
+        const p1 = path.join(home, '.workbuddy', 'skills');
+        const p2 = path.join(home, '.workbody', 'skills');
+        if (fs.existsSync(path.join(p1, 'sensecraft', 'SKILL.md'))) return p1;
+        if (fs.existsSync(path.join(p2, 'sensecraft', 'SKILL.md'))) return p2;
+        if (fs.existsSync(path.join(home, '.workbuddy'))) return p1;
+        if (fs.existsSync(path.join(home, '.workbody'))) return p2;
+        return p1;
+      }
+    },
+    {
+      id: 'claude',
+      name: 'Claude Code',
+      homeDirs: [path.join(home, '.claude')],
+      getSkillsDir: () => path.join(home, '.claude', 'skills')
+    },
+    {
+      id: 'codex',
+      name: 'Codex',
+      homeDirs: [path.join(home, '.agents'), path.join(home, '.codex')],
+      getSkillsDir: () => {
+        // Honor existing installation first to avoid path drift (Codex Medium 13)
+        const pAgents = path.join(home, '.agents', 'skills');
+        const pCodex = path.join(home, '.codex', 'skills');
+        if (fs.existsSync(path.join(pAgents, 'sensecraft', 'SKILL.md'))) return pAgents;
+        if (fs.existsSync(path.join(pCodex, 'sensecraft', 'SKILL.md'))) return pCodex;
+        // Default to .agents/skills if .agents exists, otherwise .codex/skills if .codex exists
+        if (fs.existsSync(path.join(home, '.agents'))) return pAgents;
+        if (fs.existsSync(path.join(home, '.codex'))) return pCodex;
+        return pAgents;
+      }
+    },
+    {
+      id: 'codebuddy',
+      name: 'CodeBuddy',
+      homeDirs: [path.join(home, '.codebuddy')],
+      getSkillsDir: () => {
+        if (process.env.CODEBUDDY_SKILL_DIR) {
+          return path.resolve(process.env.CODEBUDDY_SKILL_DIR);
+        }
+        return path.join(home, '.codebuddy', 'skills');
+      }
+    }
+  ];
+}
+
+export function scanLocalAgents() {
+  const agents = getKnownAgents();
+  return agents.map(a => {
+    const skillsDir = a.getSkillsDir();
+    const detected = a.homeDirs.some(dir => fs.existsSync(dir)) || fs.existsSync(skillsDir);
+    const installed = fs.existsSync(path.join(skillsDir, 'sensecraft', 'SKILL.md'));
+    return {
+      ...a,
+      detected,
+      installed,
+      skillsDir
+    };
+  });
+}
+
+export async function promptAgentSelection(scannedAgents, cliArg, autoYes = false) {
+  // If explicitly specified in CLI flags
+  if (cliArg) {
+    if (cliArg.toLowerCase() === 'all') {
+      return scannedAgents;
+    }
+    const requested = cliArg.split(',').map(s => s.trim().toLowerCase());
+    const matched = scannedAgents.filter(a => requested.includes(a.id));
+    if (matched.length === 0) {
+      throw new Error(`No matching agents for: "${cliArg}". Available: ${scannedAgents.map(a => a.id).join(', ')}`);
+    }
+    return matched;
+  }
+
+  // Non-interactive check (CI / piped / daemon)
+  const isInteractive = Boolean(process.stdin.isTTY && process.stdout.isTTY);
+
+  if (!isInteractive) {
+    if (autoYes) {
+      const detectedOnly = scannedAgents.filter(a => a.detected);
+      return detectedOnly.length > 0 ? detectedOnly : scannedAgents.slice(0, 1);
+    }
+    throw new Error('Non-interactive environment detected. Please specify --agent <workbuddy|claude|codex|codebuddy|all> or pass -y.');
+  }
+
+  if (autoYes) {
+    const detectedOnly = scannedAgents.filter(a => a.detected);
+    return detectedOnly.length > 0 ? detectedOnly : scannedAgents;
+  }
+
+  // Interactive CLI Selection using Readline
+  console.log('\n🤖 Available AI Agent targets:');
+  scannedAgents.forEach((a, idx) => {
+    const tag = a.detected ? '\x1b[32m[Detected]\x1b[0m' : '\x1b[90m[Not Detected]\x1b[0m';
+    const status = a.installed ? ' \x1b[36m(Already installed)\x1b[0m' : '';
+    console.log(`  ${idx + 1}. ${a.name} ${tag}${status}`);
+    console.log(`     Path: ${a.skillsDir}`);
+  });
+
+  const defaultChoices = scannedAgents
+    .map((a, idx) => (a.detected ? idx + 1 : null))
+    .filter(Boolean);
+
+  const defaultPromptStr = defaultChoices.length > 0 ? defaultChoices.join(',') : 'all';
+
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout
+  });
+
+  return new Promise((resolve) => {
+    rl.question(`\nSelect agents to install skill into (e.g. 1,2 or "all") [default: ${defaultPromptStr}]: `, answer => {
+      rl.close();
+      const input = (answer || '').trim();
+
+      if (!input) {
+        if (defaultChoices.length > 0) {
+          resolve(scannedAgents.filter((_, idx) => defaultChoices.includes(idx + 1)));
+          return;
+        }
+        resolve(scannedAgents);
+        return;
+      }
+
+      if (input.toLowerCase() === 'all') {
+        resolve(scannedAgents);
+        return;
+      }
+
+      const indices = input
+        .split(/[,\s]+/)
+        .map(x => parseInt(x, 10))
+        .filter(n => !isNaN(n) && n >= 1 && n <= scannedAgents.length);
+
+      if (indices.length === 0) {
+        console.log('No valid selection. Nothing to install.');
+        resolve([]);
+        return;
+      }
+
+      const selected = scannedAgents.filter((_, idx) => indices.includes(idx + 1));
+      resolve(selected);
+    });
+  });
+}

package/lib/catalog-dto.js

@@ -0,0 +1,69 @@
+/**
+ * Unified Catalog DTO definition and validator conforming to v2 schema.
+ */
+
+export const SCHEMA_VERSION = '2.0';
+export const SCHEMA_URL = 'https://spec.seeedstudio.com/schemas/v2/catalog-dto.json';
+
+/**
+ * Creates a standardized Catalog DTO response.
+ *
+ * @param {Object} options
+ * @param {'typesense' | 'bundled_manifest'} options.source
+ * @param {'FRESH' | 'STALE' | 'UNKNOWN'} [options.freshness='FRESH']
+ * @param {string} [options.datasetVersion='2026-10-13.1']
+ * @param {Array} options.records
+ * @param {Object} [options.fieldCompleteness]
+ * @param {Array<string>} [options.warnings=[]]
+ * @returns {Object} Validated Catalog DTO
+ */
+export function createCatalogDto({
+  source = 'bundled_manifest',
+  freshness = 'FRESH',
+  datasetVersion = '2026-10-13.1',
+  records = [],
+  fieldCompleteness = { spec: true, compatibility: true, offer: source === 'typesense' },
+  warnings = [],
+}) {
+  return {
+    $schema: SCHEMA_URL,
+    schema_version: SCHEMA_VERSION,
+    dataset_version: datasetVersion,
+    generated_at: new Date().toISOString(),
+    source,
+    freshness,
+    field_completeness: fieldCompleteness,
+    record_count: Array.isArray(records) ? records.length : 0,
+    records: Array.isArray(records) ? records : [],
+    warnings: Array.isArray(warnings) ? warnings : [],
+  };
+}
+
+/**
+ * Validates whether an object complies with the v2 Catalog DTO structure.
+ *
+ * @param {any} dto
+ * @returns {{ valid: boolean, errors: Array<string> }}
+ */
+export function validateCatalogDto(dto) {
+  const errors = [];
+  if (!dto || typeof dto !== 'object') {
+    return { valid: false, errors: ['DTO must be an object'] };
+  }
+  if (dto.schema_version !== SCHEMA_VERSION) {
+    errors.push(`Invalid schema_version: expected ${SCHEMA_VERSION}, got ${dto.schema_version}`);
+  }
+  if (!['typesense', 'bundled_manifest'].includes(dto.source)) {
+    errors.push(`Invalid source: ${dto.source}`);
+  }
+  if (!['FRESH', 'STALE', 'UNKNOWN'].includes(dto.freshness)) {
+    errors.push(`Invalid freshness: ${dto.freshness}`);
+  }
+  if (!Array.isArray(dto.records)) {
+    errors.push('records must be an array');
+  }
+  return {
+    valid: errors.length === 0,
+    errors,
+  };
+}

package/lib/compatibility.js

@@ -0,0 +1,312 @@
+/**
+ * Deterministic Machine Compatibility Evaluator for IoT Hardware and Accessories.
+ *
+ * Implements machine-evaluable compatibility assertions across 6 physical dimensions:
+ * 1. power_supply: Voltage, tolerance, min current/watts, plug dimensions, polarity, USB-C PD profiles
+ * 2. rf_antenna: RF connector gender (N-Type, SMA, RP-SMA), impedance, frequency bands
+ * 3. m2_storage: Key-M vs Key-E, form factor (2242 vs 2280), PCIe/NVMe vs SATA
+ * 4. poe: 802.3af (15.4W) vs 802.3at (30W) vs 802.3bt
+ * 5. usb: Port generation, bandwidth, and host power output
+ * 6. os_firmware: Kernel / JetPack / firmware version constraints
+ */
+
+export const COMPATIBILITY_STATUS = {
+  VERIFIED: 'VERIFIED',
+  REQUIRES_ADAPTER: 'REQUIRES_ADAPTER',
+  INCOMPATIBLE: 'INCOMPATIBLE',
+  UNKNOWN: 'UNKNOWN',
+  CONFLICT: 'CONFLICT',
+};
+
+/**
+ * Evaluates power supply compatibility between a host device and an adapter/cable.
+ *
+ * @param {Object} hostSpec - Host physical power requirements
+ * @param {Object} accessorySpec - Power accessory specifications
+ * @returns {{ status: string, dimension: string, reason: string, details: Object }}
+ */
+export function evaluatePowerCompatibility(hostSpec, accessorySpec) {
+  if (!hostSpec || !accessorySpec) {
+    return {
+      status: COMPATIBILITY_STATUS.UNKNOWN,
+      dimension: 'power_supply',
+      reason: 'Missing power specifications for host or accessory',
+      details: {},
+    };
+  }
+
+  // 1. USB-C Power Delivery checks
+  if (hostSpec.connector === 'usb_c' || accessorySpec.connector === 'usb_c') {
+    if (hostSpec.connector !== accessorySpec.connector) {
+      return {
+        status: COMPATIBILITY_STATUS.INCOMPATIBLE,
+        dimension: 'power_supply',
+        reason: `Connector mismatch: host requires ${hostSpec.connector}, accessory provides ${accessorySpec.connector}`,
+        details: { hostConnector: hostSpec.connector, accessoryConnector: accessorySpec.connector },
+      };
+    }
+    const hostMinWatts = hostSpec.min_watts || ((hostSpec.voltage_v || 5.0) * (hostSpec.min_current_a || 2.0));
+    const accWatts = accessorySpec.watts || ((accessorySpec.voltage_v || 5.0) * (accessorySpec.max_current_a || 3.0));
+    if (accWatts < hostMinWatts) {
+      return {
+        status: COMPATIBILITY_STATUS.INCOMPATIBLE,
+        dimension: 'power_supply',
+        reason: `Insufficient wattage: host requires at least ${hostMinWatts}W, accessory provides ${accWatts}W`,
+        details: { requiredWatts: hostMinWatts, providedWatts: accWatts },
+      };
+    }
+    return {
+      status: COMPATIBILITY_STATUS.VERIFIED,
+      dimension: 'power_supply',
+      reason: `Verified USB-C power delivery: ${accWatts}W meets or exceeds required ${hostMinWatts}W`,
+      details: { requiredWatts: hostMinWatts, providedWatts: accWatts },
+    };
+  }
+
+  // 2. DC Barrel Jack checks (Voltage, Current, Plug Dimensions, Polarity)
+  const hostV = hostSpec.voltage_v;
+  const accV = accessorySpec.voltage_v;
+  if (hostV && accV) {
+    const tolerance = hostSpec.tolerance_percent || 5.0;
+    const diffPercent = Math.abs(hostV - accV) / hostV * 100;
+    if (diffPercent > tolerance) {
+      return {
+        status: COMPATIBILITY_STATUS.INCOMPATIBLE,
+        dimension: 'power_supply',
+        reason: `Voltage mismatch: host requires ${hostV}V (±${tolerance}%), accessory supplies ${accV}V`,
+        details: { requiredVoltage: hostV, suppliedVoltage: accV },
+      };
+    }
+  }
+
+  if (hostSpec.min_current_a && accessorySpec.max_current_a) {
+    if (accessorySpec.max_current_a < hostSpec.min_current_a) {
+      return {
+        status: COMPATIBILITY_STATUS.INCOMPATIBLE,
+        dimension: 'power_supply',
+        reason: `Current capacity too low: host requires at least ${hostSpec.min_current_a}A, adapter rated for ${accessorySpec.max_current_a}A`,
+        details: { requiredCurrent: hostSpec.min_current_a, providedCurrent: accessorySpec.max_current_a },
+      };
+    }
+  }
+
+  // Plug dimension check (e.g. 5.5x2.5mm vs 5.5x2.1mm)
+  if (hostSpec.connector && accessorySpec.connector) {
+    if (hostSpec.connector !== accessorySpec.connector) {
+      return {
+        status: COMPATIBILITY_STATUS.REQUIRES_ADAPTER,
+        dimension: 'power_supply',
+        reason: `DC Barrel plug mismatch: host requires ${hostSpec.connector}, accessory has ${accessorySpec.connector}. Requires a barrel converter adapter.`,
+        details: { hostConnector: hostSpec.connector, accessoryConnector: accessorySpec.connector },
+      };
+    }
+  }
+
+  // Polarity check (center_positive vs center_negative)
+  if (hostSpec.polarity && accessorySpec.polarity) {
+    if (hostSpec.polarity !== accessorySpec.polarity) {
+      return {
+        status: COMPATIBILITY_STATUS.INCOMPATIBLE,
+        dimension: 'power_supply',
+        reason: `Polarity inversion danger: host requires ${hostSpec.polarity}, accessory is ${accessorySpec.polarity}`,
+        details: { hostPolarity: hostSpec.polarity, accessoryPolarity: accessorySpec.polarity },
+      };
+    }
+  }
+
+  return {
+    status: COMPATIBILITY_STATUS.VERIFIED,
+    dimension: 'power_supply',
+    reason: `Power supply verified: ${accV || hostV}V @ ${accessorySpec.max_current_a || hostSpec.min_current_a}A matches requirements`,
+    details: { voltage: accV || hostV, current: accessorySpec.max_current_a || hostSpec.min_current_a },
+  };
+}
+
+/**
+ * Evaluates RF Antenna compatibility between a host device and an antenna.
+ *
+ * @param {Object} hostSpec
+ * @param {Object} antennaSpec
+ * @returns {{ status: string, dimension: string, reason: string, details: Object }}
+ */
+export function evaluateRfCompatibility(hostSpec, antennaSpec) {
+  if (!hostSpec?.rf_antenna || !antennaSpec) {
+    return {
+      status: COMPATIBILITY_STATUS.UNKNOWN,
+      dimension: 'rf_antenna',
+      reason: 'Missing RF or antenna specifications',
+      details: {},
+    };
+  }
+
+  const hostRf = hostSpec.rf_antenna;
+  const hostConn = (hostRf.connector || '').toLowerCase();
+  const antConn = (antennaSpec.connector || '').toLowerCase();
+
+  // 1. Connector compatibility
+  if (hostConn.includes('n-type female')) {
+    if (antConn.includes('n-type male') || antConn.includes('n-male')) {
+      // Direct mate
+    } else if (antConn.includes('sma')) {
+      return {
+        status: COMPATIBILITY_STATUS.REQUIRES_ADAPTER,
+        dimension: 'rf_antenna',
+        reason: 'Host has N-Type Female connector, antenna has SMA connector. Requires N-Male to SMA pigtail cable / adapter.',
+        details: { hostConnector: hostRf.connector, antennaConnector: antennaSpec.connector },
+      };
+    } else if (!antConn) {
+      return {
+        status: COMPATIBILITY_STATUS.UNKNOWN,
+        dimension: 'rf_antenna',
+        reason: 'Antenna connector type not specified',
+        details: { hostConnector: hostRf.connector },
+      };
+    } else {
+      return {
+        status: COMPATIBILITY_STATUS.INCOMPATIBLE,
+        dimension: 'rf_antenna',
+        reason: `Incompatible antenna connector: host has ${hostRf.connector}, antenna has ${antennaSpec.connector}`,
+        details: { hostConnector: hostRf.connector, antennaConnector: antennaSpec.connector },
+      };
+    }
+  }
+
+  // 2. Frequency band check (e.g. EU868, US915, 2.4GHz)
+  if (hostRf.frequency_bands && antennaSpec.frequency_band) {
+    const antBand = antennaSpec.frequency_band.toUpperCase();
+    const match = hostRf.frequency_bands.some((b) => b.toUpperCase().includes(antBand) || antBand.includes(b.toUpperCase()));
+    if (!match) {
+      return {
+        status: COMPATIBILITY_STATUS.INCOMPATIBLE,
+        dimension: 'rf_antenna',
+        reason: `Frequency band mismatch: host operating bands [${hostRf.frequency_bands.join(', ')}], antenna tuned for ${antennaSpec.frequency_band}`,
+        details: { supportedBands: hostRf.frequency_bands, antennaBand: antennaSpec.frequency_band },
+      };
+    }
+  }
+
+  return {
+    status: COMPATIBILITY_STATUS.VERIFIED,
+    dimension: 'rf_antenna',
+    reason: `Antenna verified: connector ${antennaSpec.connector || hostConn} and frequency band match host`,
+    details: { connector: antennaSpec.connector || hostConn },
+  };
+}
+
+/**
+ * Evaluates M.2 expansion slot compatibility (Key-M vs Key-E, form factor 2280 vs 2242).
+ *
+ * @param {Object} hostSpec
+ * @param {Object} moduleSpec
+ * @returns {{ status: string, dimension: string, reason: string, details: Object }}
+ */
+export function evaluateM2Compatibility(hostSpec, moduleSpec) {
+  if (!hostSpec?.m2_slots || !moduleSpec) {
+    return {
+      status: COMPATIBILITY_STATUS.UNKNOWN,
+      dimension: 'm2_storage',
+      reason: 'No M.2 slot or module specification available',
+      details: {},
+    };
+  }
+
+  const modKey = (moduleSpec.key || '').toUpperCase(); // 'M' or 'E'
+  const modSize = moduleSpec.size || '2280';
+
+  const matchingSlot = hostSpec.m2_slots.find((slot) => {
+    return slot.key.toUpperCase() === modKey;
+  });
+
+  if (!matchingSlot) {
+    return {
+      status: COMPATIBILITY_STATUS.INCOMPATIBLE,
+      dimension: 'm2_storage',
+      reason: `M.2 Key mismatch: module requires Key-${modKey}, but host only provides [${hostSpec.m2_slots.map((s) => 'Key-' + s.key).join(', ')}]`,
+      details: { requiredKey: modKey, availableSlots: hostSpec.m2_slots },
+    };
+  }
+
+  if (matchingSlot.size && matchingSlot.size !== modSize) {
+    return {
+      status: COMPATIBILITY_STATUS.REQUIRES_ADAPTER,
+      dimension: 'm2_storage',
+      reason: `Form factor mismatch: module is ${modSize}, slot designed for ${matchingSlot.size}. May require mounting bracket / standoff.`,
+      details: { moduleSize: modSize, slotSize: matchingSlot.size },
+    };
+  }
+
+  return {
+    status: COMPATIBILITY_STATUS.VERIFIED,
+    dimension: 'm2_storage',
+    reason: `M.2 slot verified: Key-${modKey} (${modSize}) matches slot ${matchingSlot.key}`,
+    details: { key: modKey, size: modSize, interface: matchingSlot.interface },
+  };
+}
+
+/**
+ * Master compatibility assertion runner evaluating all relevant physical dimensions.
+ *
+ * @param {Object} hostPhysicalSpec - Host physical specifications
+ * @param {Object} accessoryItem - Accessory object with specs and kind
+ * @returns {{ isCompatible: boolean, status: string, dimensions: Array<Object> }}
+ */
+export function assertCompatibility(hostPhysicalSpec, accessoryItem) {
+  if (!hostPhysicalSpec || !accessoryItem) {
+    return {
+      isCompatible: false,
+      status: COMPATIBILITY_STATUS.UNKNOWN,
+      dimensions: [{ dimension: 'general', status: COMPATIBILITY_STATUS.UNKNOWN, reason: 'Insufficient specification data' }],
+    };
+  }
+
+  const evaluations = [];
+
+  // Check Power
+  if (accessoryItem.power_spec || accessoryItem.type?.includes('power') || accessoryItem.id?.includes('power')) {
+    evaluations.push(evaluatePowerCompatibility(hostPhysicalSpec.power_input, accessoryItem.power_spec || {
+      connector: hostPhysicalSpec.power_input?.connector,
+      voltage_v: hostPhysicalSpec.power_input?.voltage_v,
+      max_current_a: hostPhysicalSpec.power_input?.min_current_a,
+    }));
+  }
+
+  // Check RF / Antenna
+  if (accessoryItem.rf_spec || accessoryItem.type?.includes('antenna') || accessoryItem.id?.includes('antenna')) {
+    evaluations.push(evaluateRfCompatibility(hostPhysicalSpec, accessoryItem.rf_spec || {
+      connector: hostPhysicalSpec.rf_antenna?.required_antenna_connector || 'SMA-J (Male)',
+    }));
+  }
+
+  // Check M.2 Storage / Wireless
+  if (accessoryItem.m2_spec || accessoryItem.type?.includes('ssd') || accessoryItem.type?.includes('m2')) {
+    evaluations.push(evaluateM2Compatibility(hostPhysicalSpec, accessoryItem.m2_spec || {
+      key: 'M',
+      size: '2280',
+    }));
+  }
+
+  if (evaluations.length === 0) {
+    return {
+      isCompatible: true,
+      status: COMPATIBILITY_STATUS.VERIFIED,
+      dimensions: [{ dimension: 'generic', status: COMPATIBILITY_STATUS.VERIFIED, reason: 'General peripheral without physical slot constraint' }],
+    };
+  }
+
+  const hasIncompatible = evaluations.some((e) => e.status === COMPATIBILITY_STATUS.INCOMPATIBLE);
+  const hasConflict = evaluations.some((e) => e.status === COMPATIBILITY_STATUS.CONFLICT);
+  const hasAdapter = evaluations.some((e) => e.status === COMPATIBILITY_STATUS.REQUIRES_ADAPTER);
+  const hasUnknown = evaluations.some((e) => e.status === COMPATIBILITY_STATUS.UNKNOWN);
+
+  let overallStatus = COMPATIBILITY_STATUS.VERIFIED;
+  if (hasIncompatible) overallStatus = COMPATIBILITY_STATUS.INCOMPATIBLE;
+  else if (hasConflict) overallStatus = COMPATIBILITY_STATUS.CONFLICT;
+  else if (hasAdapter) overallStatus = COMPATIBILITY_STATUS.REQUIRES_ADAPTER;
+  else if (hasUnknown) overallStatus = COMPATIBILITY_STATUS.UNKNOWN;
+
+  return {
+    isCompatible: overallStatus === COMPATIBILITY_STATUS.VERIFIED || overallStatus === COMPATIBILITY_STATUS.REQUIRES_ADAPTER,
+    status: overallStatus,
+    dimensions: evaluations,
+  };
+}