@seeed-studio/solution-cli 0.1.0 → 0.2.0

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,
+  };
+}