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

package/lib/knowledge.js

@@ -0,0 +1,327 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import https from 'node:https';
+import http from 'node:http';
+import { createCatalogDto } from './catalog-dto.js';
+import { assertCompatibility, COMPATIBILITY_STATUS } from './compatibility.js';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const DATA_FILE = path.join(__dirname, '..', 'catalog', 'knowledge-core.json');
+
+let cachedKnowledgeCore = null;
+
+/**
+ * Loads the bundled offline knowledge core file.
+ *
+ * @returns {Object} Bundled knowledge core data
+ */
+export function loadKnowledgeCore() {
+  if (cachedKnowledgeCore) return cachedKnowledgeCore;
+  if (!fs.existsSync(DATA_FILE)) {
+    throw new Error(`Knowledge core manifest not found at ${DATA_FILE}. Run "npm run build:knowledge" to generate.`);
+  }
+  const raw = fs.readFileSync(DATA_FILE, 'utf-8');
+  cachedKnowledgeCore = JSON.parse(raw);
+  return cachedKnowledgeCore;
+}
+
+/**
+ * Performs an HTTP GET request with a timeout.
+ *
+ * @param {string} urlStr
+ * @param {Object} headers
+ * @param {number} timeoutMs
+ * @returns {Promise<Object>}
+ */
+function fetchJson(urlStr, headers = {}, timeoutMs = 2500) {
+  return new Promise((resolve, reject) => {
+    const url = new URL(urlStr);
+    const client = url.protocol === 'https:' ? https : http;
+    const req = client.get(url, { headers, timeout: timeoutMs }, (res) => {
+      let body = '';
+      res.on('data', (chunk) => { body += chunk; });
+      res.on('end', () => {
+        if (res.statusCode >= 200 && res.statusCode < 300) {
+          try {
+            resolve(JSON.parse(body));
+          } catch (e) {
+            reject(new Error(`Invalid JSON from ${urlStr}: ${e.message}`));
+          }
+        } else {
+          reject(new Error(`HTTP ${res.statusCode} from ${urlStr}`));
+        }
+      });
+    });
+    req.on('timeout', () => {
+      req.destroy();
+      reject(new Error(`Timeout after ${timeoutMs}ms from ${urlStr}`));
+    });
+    req.on('error', reject);
+  });
+}
+
+/**
+ * Searches Seeed Solutions Hub scenarios and reference designs.
+ *
+ * @param {Object} options
+ * @param {string} options.query - Free text search query
+ * @param {'zh' | 'en'} [options.locale='zh'] - Language preference
+ * @param {number} [options.limit=5] - Maximum number of results
+ * @returns {Promise<Object>} Standardized Catalog DTO
+ */
+export async function searchHub({ query = '', locale = 'zh', limit = 5 } = {}) {
+  const qLower = (query || '').toLowerCase().trim();
+  const searchKey = process.env.SENSECRAFT_TYPESENSE_PURCHASE_SEARCH_KEY || process.env.TYPESENSE_SEARCH_KEY;
+  const host = process.env.TYPESENSE_HOST || 'https://rel-search.seeedstudio.com';
+
+  // Attempt online Typesense search if key is provided and not explicitly running offline
+  if (searchKey && !process.env.SENSECRAFT_OFFLINE_ONLY) {
+    try {
+      const searchUrl = `${host}/collections/Solution/documents/search?q=${encodeURIComponent(query)}&query_by=title,description,tags&per_page=${limit}`;
+      const data = await fetchJson(searchUrl, { 'X-TYPESENSE-API-KEY': searchKey }, 2500);
+      if (data && Array.isArray(data.hits)) {
+        const records = data.hits.map((hit) => {
+          const doc = hit.document || {};
+          return {
+            type: doc.doc_type || 'scenario',
+            id: doc.id || doc.slug,
+            title: doc.title,
+            summary: doc.summary || doc.description,
+            tags: doc.tags || [],
+            family_ids: doc.family_ids || [],
+            source: 'typesense',
+          };
+        });
+        return createCatalogDto({
+          source: 'typesense',
+          freshness: 'FRESH',
+          records: records.slice(0, limit),
+        });
+      }
+    } catch (err) {
+      // Graceful fallback to offline core with notice
+    }
+  }
+
+  // Offline fallback search over knowledge-core
+  const core = loadKnowledgeCore();
+  const matchedScenarios = [];
+  const matchedRefDesigns = [];
+
+  const tokens = qLower.split(/\s+/).filter(Boolean);
+
+  for (const s of core.scenarios || []) {
+    const haystack = [
+      s.id,
+      s.title?.zh,
+      s.title?.en,
+      s.subtitle?.zh,
+      s.subtitle?.en,
+      s.summary,
+      ...(s.tags || []),
+    ].join(' ').toLowerCase();
+
+    const score = tokens.reduce((acc, token) => (haystack.includes(token) ? acc + 1 : acc), 0);
+    if (tokens.length === 0 || score > 0) {
+      matchedScenarios.push({
+        type: 'scenario',
+        id: s.id,
+        title: s.title?.[locale] || s.title?.zh || s.title?.en || s.id,
+        summary: s.subtitle?.[locale] || s.subtitle?.zh || s.summary || '',
+        tags: s.tags || [],
+        family_ids: s.family_ids || [],
+        reference_designs: s.reference_designs || [],
+        score,
+      });
+    }
+  }
+
+  for (const rd of core.reference_designs || []) {
+    const haystack = [
+      rd.id,
+      rd.title?.zh,
+      rd.title?.en,
+      rd.summary?.zh,
+      rd.summary?.en,
+      ...(rd.presets || []),
+    ].join(' ').toLowerCase();
+
+    const score = tokens.reduce((acc, token) => (haystack.includes(token) ? acc + 1 : acc), 0);
+    if (tokens.length === 0 || score > 0) {
+      matchedRefDesigns.push({
+        type: 'reference_design',
+        id: rd.id,
+        title: rd.title?.[locale] || rd.title?.zh || rd.title?.en || rd.id,
+        summary: rd.summary?.[locale] || rd.summary?.zh || rd.summary?.en || '',
+        presets: rd.presets || [],
+        wiki_url: rd.wiki_url || '',
+        score,
+      });
+    }
+  }
+
+  // Sort by score descending and take top results
+  matchedScenarios.sort((a, b) => b.score - a.score);
+  matchedRefDesigns.sort((a, b) => b.score - a.score);
+
+  const combined = [...matchedScenarios, ...matchedRefDesigns].slice(0, limit);
+
+  return createCatalogDto({
+    source: 'bundled_manifest',
+    freshness: 'FRESH',
+    records: combined,
+    warnings: searchKey
+      ? ['Online Typesense request timed out; fell back to local bundled manifest.']
+      : ['No Typesense API key configured. Displaying verified local catalog.'],
+  });
+}
+
+/**
+ * Queries product family information, SKUs, and official purchase links.
+ *
+ * @param {string} familyId
+ * @param {Object} [options]
+ * @param {string} [options.locale='zh']
+ * @returns {Object} Catalog DTO with product details
+ */
+export function queryProductFamily(familyId, { locale = 'zh' } = {}) {
+  const core = loadKnowledgeCore();
+  const family = core.product_families?.[familyId];
+
+  if (!family) {
+    return createCatalogDto({
+      source: 'bundled_manifest',
+      freshness: 'FRESH',
+      records: [],
+      warnings: [`Product family "${familyId}" not found in local catalog.`],
+    });
+  }
+
+  return createCatalogDto({
+    source: 'bundled_manifest',
+    freshness: 'FRESH',
+    records: [{
+      family_id: family.id,
+      title: family.title?.[locale] || family.title?.zh || family.title?.en || family.id,
+      default_sku: family.default_sku,
+      regions: family.regions || [],
+      skus_count: (family.skus || []).length,
+      skus: (family.skus || []).slice(0, 10),
+      physical_spec: family.physical_spec || null,
+      required_accessories_count: (family.required_accessories || []).length,
+      optional_accessories_count: (family.optional_accessories || []).length,
+    }],
+  });
+}
+
+/**
+ * Queries and verifies accessories for a product family, running physical compatibility checks.
+ *
+ * @param {string} familyId
+ * @param {Object} [options]
+ * @param {string} [options.sku] - Specific host SKU
+ * @param {string} [options.locale='zh']
+ * @returns {Object} Catalog DTO with structured, verified accessories
+ */
+export function queryAccessories(familyId, { sku = null, locale = 'zh' } = {}) {
+  const core = loadKnowledgeCore();
+  const family = core.product_families?.[familyId];
+
+  if (!family) {
+    return createCatalogDto({
+      source: 'bundled_manifest',
+      freshness: 'FRESH',
+      records: [],
+      warnings: [`Product family "${familyId}" not found in local catalog.`],
+    });
+  }
+
+  const hostPhysicalSpec = family.physical_spec || null;
+
+  // Process required accessories
+  const required = (family.required_accessories || []).map((acc) => {
+    const comp = assertCompatibility(hostPhysicalSpec, acc);
+    return {
+      category: 'REQUIRED',
+      id: acc.id,
+      name: acc.name,
+      sku: acc.sku,
+      url: acc.url,
+      qty: acc.qty || 1,
+      reason: acc.reason || 'Required for standard operation',
+      applies_when: acc.applies_when || null,
+      compatibility: {
+        is_compatible: comp.isCompatible,
+        status: comp.status,
+        details: comp.dimensions,
+      },
+    };
+  });
+
+  // Process optional accessories
+  const optional = (family.optional_accessories || []).map((acc) => {
+    const comp = assertCompatibility(hostPhysicalSpec, acc);
+    return {
+      category: 'OPTIONAL',
+      id: acc.id,
+      name: acc.name,
+      sku: acc.sku,
+      url: acc.url,
+      type: acc.type || 'peripheral',
+      compatibility: {
+        is_compatible: comp.isCompatible,
+        status: comp.status,
+        details: comp.dimensions,
+      },
+    };
+  });
+
+  return createCatalogDto({
+    source: 'bundled_manifest',
+    freshness: 'FRESH',
+    records: [{
+      family_id: family.id,
+      host_title: family.title?.[locale] || family.title?.zh || family.title?.en,
+      host_sku: sku || family.default_sku,
+      physical_spec: hostPhysicalSpec,
+      accessories: {
+        required,
+        optional,
+      },
+    }],
+  });
+}
+
+/**
+ * Generates an immutable DeploymentLockfile to isolate deployment apply from external network.
+ *
+ * @param {Object} options
+ * @param {string} options.solutionId
+ * @param {string} options.solutionVersion
+ * @param {Array<string>} options.selectedHardware
+ * @param {Array<Object>} [options.verifiedCompatibility=[]]
+ * @returns {Object} DeploymentLockfile
+ */
+export function createDeploymentLockfile({
+  solutionId,
+  solutionVersion = '1.0.0',
+  selectedHardware = [],
+  verifiedCompatibility = [],
+}) {
+  return {
+    $schema: 'https://spec.seeedstudio.com/schemas/v2/deployment-lock.json',
+    solution_id: solutionId,
+    solution_version: solutionVersion,
+    locked_at: new Date().toISOString(),
+    dataset_version: '2026-10-13.1',
+    selected_hardware: selectedHardware,
+    compatibility_assertions: verifiedCompatibility,
+    unresolved_requirements: [],
+    network_policy: {
+      commercial_queries_allowed: false,
+      apply_isolated: true,
+    },
+  };
+}

package/lib/ledger.js

@@ -0,0 +1,302 @@
+import path from 'node:path';
+import fs from 'node:fs';
+import crypto from 'node:crypto';
+import { getScHome } from './platform.js';
+
+export function getLedgerPath() {
+  return path.join(getScHome(), 'skills-ledger.json');
+}
+
+export function getLockPath() {
+  return path.join(getScHome(), '.skills.lock');
+}
+
+export function withLedgerLock(fn) {
+  const lockFile = getLockPath();
+  const dir = path.dirname(lockFile);
+  fs.mkdirSync(dir, { recursive: true });
+
+  const maxAttempts = 60;
+  let attempts = 0;
+  let fd = null;
+
+  while (attempts++ < maxAttempts) {
+    try {
+      fd = fs.openSync(lockFile, 'wx');
+      // Record PID and timestamp into lock file
+      fs.writeFileSync(fd, JSON.stringify({ pid: process.pid, time: Date.now() }), 'utf8');
+      break;
+    } catch {
+      // Check if lock is stale or holder process is dead
+      try {
+        const raw = fs.readFileSync(lockFile, 'utf8');
+        const lockInfo = JSON.parse(raw);
+        let isDead = false;
+
+        if (lockInfo && lockInfo.pid) {
+          try {
+            // Check if process exists: kill(0) throws ESRCH if process is dead
+            process.kill(lockInfo.pid, 0);
+          } catch (err) {
+            if (err.code === 'ESRCH') {
+              isDead = true;
+            }
+          }
+        }
+
+        // Break stale lock only if process is dead or older than 60s
+        if (isDead || (Date.now() - lockInfo.time > 60000)) {
+          fs.unlinkSync(lockFile);
+          continue;
+        }
+      } catch {}
+
+      // Sleep 100ms synchronously
+      const end = Date.now() + 100;
+      while (Date.now() < end) {}
+    }
+  }
+
+  if (fd === null) {
+    throw new Error('Could not acquire installation lock; another SenseCraft operation may be running.');
+  }
+
+  try {
+    return fn();
+  } finally {
+    try { fs.closeSync(fd); } catch {}
+    try { fs.unlinkSync(lockFile); } catch {}
+  }
+}
+
+export function loadLedger() {
+  const ledgerPath = getLedgerPath();
+  if (!fs.existsSync(ledgerPath)) {
+    return {
+      schema_version: 1,
+      installations: {}
+    };
+  }
+  try {
+    const raw = fs.readFileSync(ledgerPath, 'utf8');
+    const parsed = JSON.parse(raw);
+    if (!parsed || typeof parsed !== 'object' || !parsed.installations) {
+      throw new Error('Malformed skills ledger JSON schema');
+    }
+    return parsed;
+  } catch (err) {
+    throw new Error(`Corrupted skills ledger at ${ledgerPath}: ${err.message}. Please inspect or backup.`);
+  }
+}
+
+export function saveLedger(ledger) {
+  const ledgerPath = getLedgerPath();
+  const dir = path.dirname(ledgerPath);
+  fs.mkdirSync(dir, { recursive: true });
+
+  const tempFile = path.join(dir, `.skills-ledger.tmp-${Date.now()}-${crypto.randomBytes(4).toString('hex')}`);
+  fs.writeFileSync(tempFile, JSON.stringify(ledger, null, 2), 'utf8');
+  fs.renameSync(tempFile, ledgerPath);
+}
+
+export function computeFileHash(filePath) {
+  if (!fs.existsSync(filePath)) return null;
+  const content = fs.readFileSync(filePath);
+  return crypto.createHash('sha256').update(content).digest('hex');
+}
+
+// Ensure target file stays strictly inside targetDir, refusing symlink escapes (Codex High 2 & P2)
+export function isSafePathInside(childPath, parentDir) {
+  try {
+    const parentReal = fs.realpathSync(parentDir);
+
+    // Codex P2: Detect symlinks even if target does not exist yet (dangling symlinks)
+    const lstat = fs.lstatSync(childPath, { throwIfNoEntry: false });
+    if (lstat && lstat.isSymbolicLink()) {
+      const linkTarget = fs.readlinkSync(childPath);
+      const resolved = path.resolve(path.dirname(childPath), linkTarget);
+      if (!fs.existsSync(resolved)) {
+        return false; // Reject dangling symlink destination
+      }
+      const targetReal = fs.realpathSync(resolved);
+      const relTarget = path.relative(parentReal, targetReal);
+      return !relTarget.startsWith('..') && !path.isAbsolute(relTarget);
+    }
+
+    // If child exists, verify its realpath
+    if (fs.existsSync(childPath)) {
+      const childReal = fs.realpathSync(childPath);
+      const rel = path.relative(parentReal, childReal);
+      return !rel.startsWith('..') && !path.isAbsolute(rel);
+    }
+    // If child doesn't exist yet, verify its nearest existing ancestor
+    let cur = path.resolve(childPath);
+    while (cur !== path.dirname(cur)) {
+      if (fs.existsSync(cur)) {
+        const curReal = fs.realpathSync(cur);
+        const rel = path.relative(parentReal, curReal);
+        return !rel.startsWith('..') && !path.isAbsolute(rel);
+      }
+      cur = path.dirname(cur);
+    }
+    return false;
+  } catch {
+    return false;
+  }
+}
+
+export function checkFileModifications(targetDir, filesMap) {
+  const modified = [];
+  const missing = [];
+  const intact = [];
+
+  for (const [relPath, recordedHash] of Object.entries(filesMap || {})) {
+    if (relPath.includes('..') || path.isAbsolute(relPath)) {
+      continue;
+    }
+    const fullPath = path.join(targetDir, relPath);
+    if (!isSafePathInside(fullPath, targetDir)) {
+      continue;
+    }
+
+    if (!fs.existsSync(fullPath)) {
+      missing.push(relPath);
+    } else {
+      const currentHash = computeFileHash(fullPath);
+      if (currentHash !== recordedHash) {
+        modified.push(relPath);
+      } else {
+        intact.push(relPath);
+      }
+    }
+  }
+
+  return { modified, missing, intact };
+}
+
+export function recordInstallation(agentId, skillsDir, targetDir, skillVersion, filesMap) {
+  const ledger = loadLedger();
+  ledger.installations = ledger.installations || {};
+
+  ledger.installations[agentId] = {
+    agent_id: agentId,
+    skills_dir: path.resolve(skillsDir),
+    target_dir: path.resolve(targetDir),
+    skill_version: skillVersion,
+    installed_at: new Date().toISOString(),
+    files: filesMap
+  };
+
+  ledger.last_updated = new Date().toISOString();
+  saveLedger(ledger);
+}
+
+export function removeInstallation(agentId, options = {}) {
+  const { force = false, dryRun = false } = options;
+  const runWithLock = dryRun ? fn => fn() : withLedgerLock;
+
+  return runWithLock(() => {
+    const ledger = loadLedger();
+
+    if (!ledger.installations || !ledger.installations[agentId]) {
+      return { success: false, reason: `No tracked installation found for agent "${agentId}".` };
+    }
+
+  const record = ledger.installations[agentId];
+  const targetDir = path.resolve(record.target_dir);
+
+  if (!fs.existsSync(targetDir)) {
+    if (!dryRun) {
+      delete ledger.installations[agentId];
+      saveLedger(ledger);
+    }
+    return { success: true, message: 'Target directory already absent. Cleaned ledger record.' };
+  }
+
+  const files = record.files || {};
+  let removedCount = 0;
+  let preservedCount = 0;
+  const actions = [];
+
+  for (const [relPath, recordedHash] of Object.entries(files)) {
+    if (relPath.includes('..') || path.isAbsolute(relPath)) {
+      continue;
+    }
+    const fullPath = path.join(targetDir, relPath);
+
+    // Verify safe path inside targetDir (Codex High 2: Prevent symlink escape)
+    if (!isSafePathInside(fullPath, targetDir)) {
+      actions.push({ file: fullPath, action: 'skip_symlink_escape' });
+      continue;
+    }
+
+    if (fs.existsSync(fullPath)) {
+      const currentHash = computeFileHash(fullPath);
+      if (currentHash === recordedHash || force) {
+        actions.push({ file: fullPath, action: 'delete' });
+        if (!dryRun) {
+          fs.unlinkSync(fullPath);
+        }
+        removedCount++;
+      } else {
+        actions.push({ file: fullPath, action: 'preserve_modified' });
+        preservedCount++;
+      }
+    }
+  }
+
+  // Remove marker file
+  const marker = path.join(targetDir, '.installed-by-sensecraft');
+  if (fs.existsSync(marker) && isSafePathInside(marker, targetDir)) {
+    actions.push({ file: marker, action: 'delete_marker' });
+    if (!dryRun) {
+      try { fs.unlinkSync(marker); } catch {}
+    }
+  }
+
+  if (!dryRun) {
+    cleanEmptyDirs(targetDir);
+    try {
+      if (fs.existsSync(targetDir) && fs.readdirSync(targetDir).length === 0) {
+        fs.rmdirSync(targetDir);
+      }
+    } catch {}
+
+    delete ledger.installations[agentId];
+    saveLedger(ledger);
+  }
+
+    return {
+      success: true,
+      removedCount,
+      preservedCount,
+      targetDir,
+      dryRun,
+      actions
+    };
+  });
+}
+
+function cleanEmptyDirs(dir) {
+  if (!fs.existsSync(dir)) return;
+  // Don't clean inside external symlinks
+  try {
+    const stat = fs.lstatSync(dir);
+    if (stat.isSymbolicLink()) return;
+  } catch {
+    return;
+  }
+
+  const entries = fs.readdirSync(dir, { withFileTypes: true });
+  for (const entry of entries) {
+    if (entry.isDirectory() && !entry.isSymbolicLink()) {
+      const sub = path.join(dir, entry.name);
+      cleanEmptyDirs(sub);
+      try {
+        if (fs.readdirSync(sub).length === 0) {
+          fs.rmdirSync(sub);
+        }
+      } catch {}
+    }
+  }
+}