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

package/README.md

@@ -1,3 +1,78 @@
-# Temporary Holding Version
+# @seeed-studio/solution-cli
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Zero-friction installer and CLI runner for **SenseCraft Engine** and AI Agent Skills (Work Buddy, Claude Code, Codex, CodeBuddy).
+
+## Quick Start (One-line Execution)
+
+Install the engine and configure your AI Agent skills in one command:
+
+```bash
+# Interactive mode (scans local agents and prompts for target selection)
+npx @seeed-studio/solution-cli install
+
+# Non-interactive mode for a specific agent (e.g. Work Buddy)
+npx @seeed-studio/solution-cli install --agent workbuddy
+
+# Install to multiple agents non-interactively
+npx @seeed-studio/solution-cli install --agent workbuddy,claude -y
+```
+
+Or install globally:
+
+```bash
+npm install -g @seeed-studio/solution-cli
+solution-cli install
+```
+
+---
+
+## Features
+
+1. **Smart Environment Inspection & Reuse**:
+   - Detects if you already have the SenseCraft Desktop App installed.
+   - Reuses the App's built-in engine binary and bundled solution assets without re-downloading (~30 MB saved, <0.5s execution).
+   - If no App exists, automatically downloads the standalone engine binary from Seeed CDN and verifies cryptographic SHA256 integrity.
+
+2. **Selective Agent Integration**:
+   - Supports **Work Buddy / Workbody**, **Claude Code**, **Codex**, and **CodeBuddy**.
+   - Interactive prompt lets you choose which agent(s) to adapt without touching unselected directories.
+
+3. **Deterministic Absolute Path Execution**:
+   - Injects explicit, verified binary paths directly into `SKILL.md`, ensuring that desktop Agent GUI processes can invoke `sensecraft-engine` even if shell `$PATH` is not inherited.
+
+4. **Installation Ledger & Clean Lifecycle**:
+   - Tracks all installed files in `~/.sensecraft/skills-ledger.json`.
+   - Prevents overwriting user modifications.
+   - Supports clean uninstallation via `solution-cli uninstall`.
+
+---
+
+## Command Reference
+
+| Command | Description |
+|---|---|
+| `solution-cli install` | Inspect environment, verify/download engine, and configure Agent skills |
+| `solution-cli status` | Display current engine binary, solution cache, and installed skills |
+| `solution-cli doctor` | Diagnose environment (OS, Docker, serial permissions, PATH, ledger) |
+| `solution-cli uninstall` | Cleanly remove SenseCraft skills from specified agent(s) |
+| `sensecraft-engine <cmd>` | Direct proxy to the underlying Rust engine CLI |
+
+---
+
+## AI Agent Usage Example
+
+Once installed, open Work Buddy, Claude Code, or Codex and say:
+
+> "帮我把边缘安全方案 (edge_security) 部署到我的 Jetson 设备 (IP: 192.168.1.120，用户名 harvest)"
+
+The Agent will automatically:
+1. Match the `sensecraft` Skill;
+2. Query solution parameters via `sensecraft-engine deploy-info edge_security --lang zh`;
+3. Generate or fill in required parameters;
+4. Execute deployment and stream real-time progress via `sensecraft-engine deploy ...`.
+
+---
+
+## License
+
+Apache-2.0 © Seeed Studio

package/bin/cli.js

@@ -0,0 +1,327 @@
+#!/usr/bin/env node
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { runInstall, runStatus, runUninstall } from '../lib/installer.js';
+import { runDoctor } from '../lib/doctor.js';
+import { searchHub, queryProductFamily, queryAccessories, createDeploymentLockfile } from '../lib/knowledge.js';
+import { assertCompatibility } from '../lib/compatibility.js';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const pkg = JSON.parse(fs.readFileSync(path.resolve(__dirname, '../package.json'), 'utf8'));
+
+const args = process.argv.slice(2);
+const command = args[0] || 'install';
+
+function printHelp() {
+  console.log(`
+SenseCraft Solution CLI & Skill Toolset (${pkg.name})
+
+Usage:
+  npx @seeed-studio/solution-cli [command] [options]
+  solution-cli [command] [options]
+  sensecraft-solution-cli [command] [options]
+
+Commands:
+  install     Inspect environment, verify/download engine, and configure AI Agent skills (default)
+  status      Display current engine, solution content, and agent skills status
+  doctor      Diagnose environment (platform, permissions, docker, PATH, ledger)
+  uninstall   Cleanly remove SenseCraft skills from specified agent(s)
+  hub         Search scenarios and reference designs from Seeed Solution Hub
+              Usage: solution-cli hub search <keyword> [--limit 5] [--locale zh|en] [--json]
+  product     Query product families, SKUs, and verified accessories
+              Usage: solution-cli product query <family_id> [--locale zh|en] [--json]
+                     solution-cli product accessories <family_id> [--sku <sku>] [--json]
+                     solution-cli product verify-compatibility --host <family_id> [--json]
+  lockfile    Create an immutable DeploymentLockfile to isolate deployment execution
+              Usage: solution-cli lockfile create --solution <id> [--version <v>] [--hardware <fams>] [--json]
+  help        Show this help message
+
+Options:
+  --agent <name|all>   Target agent(s): workbuddy, claude, codex, codebuddy, or all
+  -y, --yes            Accept default detected selections non-interactively
+  --dry-run            Simulate operations without making changes to filesystem
+  --skip-content       Skip pulling IoT solution packages from CDN
+  --force              Force re-download or re-link even if already installed
+  --json               Output machine-readable JSON (supported by all query/diagnostic commands)
+  --locale <zh|en>     Language for hub and product results (default: zh)
+  --limit <num>        Maximum results for search (default: 5)
+  --engine-path <path> Use custom engine executable path
+
+Examples:
+  npx @seeed-studio/solution-cli install
+  solution-cli hub search "跌倒"
+  solution-cli product accessories recomputer_j40
+  solution-cli product query sensecap_watcher --json
+  solution-cli status
+  solution-cli doctor
+`);
+}
+
+function parseFlags(rawArgs) {
+  const flags = {
+    agent: null,
+    yes: false,
+    dryRun: false,
+    skipContent: false,
+    force: false,
+    json: false,
+    enginePath: null,
+    limit: 5,
+    locale: 'zh',
+    sku: null,
+    host: null,
+    accessory: null,
+    solution: null,
+    version: '1.0.0',
+    hardware: null,
+  };
+
+  for (let i = 0; i < rawArgs.length; i++) {
+    const a = rawArgs[i];
+    if (a === '--agent' && rawArgs[i + 1]) {
+      flags.agent = rawArgs[++i];
+    } else if (a.startsWith('--agent=')) {
+      flags.agent = a.split('=')[1];
+    } else if (a === '-y' || a === '--yes') {
+      flags.yes = true;
+    } else if (a === '--dry-run') {
+      flags.dryRun = true;
+    } else if (a === '--skip-content') {
+      flags.skipContent = true;
+    } else if (a === '--force') {
+      flags.force = true;
+    } else if (a === '--json') {
+      flags.json = true;
+    } else if (a === '--engine-path' && rawArgs[i + 1]) {
+      flags.enginePath = rawArgs[++i];
+    } else if (a === '--limit' && rawArgs[i + 1]) {
+      flags.limit = parseInt(rawArgs[++i], 10) || 5;
+    } else if (a === '--locale' && rawArgs[i + 1]) {
+      flags.locale = rawArgs[++i];
+    } else if (a === '--sku' && rawArgs[i + 1]) {
+      flags.sku = rawArgs[++i];
+    } else if (a === '--host' && rawArgs[i + 1]) {
+      flags.host = rawArgs[++i];
+    } else if (a === '--accessory' && rawArgs[i + 1]) {
+      flags.accessory = rawArgs[++i];
+    } else if (a === '--solution' && rawArgs[i + 1]) {
+      flags.solution = rawArgs[++i];
+    } else if (a === '--version' && rawArgs[i + 1]) {
+      flags.version = rawArgs[++i];
+    } else if (a === '--hardware' && rawArgs[i + 1]) {
+      flags.hardware = rawArgs[++i];
+    }
+  }
+
+  return flags;
+}
+
+async function main() {
+  const flags = parseFlags(args.slice(1));
+
+  if (command === 'help' || command === '--help' || command === '-h') {
+    printHelp();
+    process.exit(0);
+  }
+
+  if (command === '--version' || command === '-v') {
+    console.log(pkg.version);
+    process.exit(0);
+  }
+
+  try {
+    switch (command) {
+      case 'install':
+        await runInstall(flags);
+        break;
+
+      case 'status':
+        runStatus(flags);
+        break;
+
+      case 'doctor': {
+        const report = runDoctor();
+        if (flags.json) {
+          console.log(JSON.stringify(report, null, 2));
+        } else {
+          console.log('\n🩺 SenseCraft Doctor Environment Report:\n');
+          report.checks.forEach(c => {
+            const symbol = c.status === 'ok' ? '\x1b[32m✔\x1b[0m' : c.status === 'warn' ? '\x1b[33m⚠️\x1b[0m' : '\x1b[31m✖\x1b[0m';
+            console.log(`  ${symbol} ${c.title}`);
+            console.log(`     ${c.detail}`);
+          });
+          console.log(`\nOverall Health: ${report.overall.toUpperCase()}\n`);
+        }
+        break;
+      }
+
+      case 'uninstall':
+        runUninstall(flags);
+        break;
+
+      case 'hub': {
+        const sub = args[1] || 'search';
+        if (sub !== 'search') {
+          console.error(`Unknown hub action "${sub}". Supported: "solution-cli hub search <keyword>"`);
+          process.exit(1);
+        }
+        const query = args.slice(2).filter((a) => !a.startsWith('-')).join(' ');
+        const dto = await searchHub({ query, locale: flags.locale, limit: flags.limit });
+        if (flags.json) {
+          console.log(JSON.stringify(dto, null, 2));
+        } else {
+          console.log(`\n🔍 Solutions Hub Search Results for "${query}" (${dto.source}):\n`);
+          if (dto.records.length === 0) {
+            console.log('  No matching scenarios or reference designs found.');
+          } else {
+            dto.records.forEach((r, idx) => {
+              const tag = r.type === 'scenario' ? '\x1b[36m[Scenario]\x1b[0m' : '\x1b[35m[Reference Design]\x1b[0m';
+              console.log(`  ${idx + 1}. ${tag} \x1b[1m${r.title}\x1b[0m (${r.id})`);
+              if (r.summary) console.log(`     ${r.summary}`);
+              if (r.reference_designs?.length) console.log(`     对应参考设计: ${r.reference_designs.join(', ')}`);
+              if (r.family_ids?.length) console.log(`     推荐硬件族: ${r.family_ids.join(', ')}`);
+              if (r.presets?.length) console.log(`     预设模式: ${r.presets.join(', ')}`);
+              if (r.wiki_url) console.log(`     开发 Wiki: ${r.wiki_url}`);
+              console.log('');
+            });
+          }
+          if (dto.warnings.length) {
+            dto.warnings.forEach((w) => console.log(`\x1b[33mNote:\x1b[0m ${w}`));
+          }
+        }
+        break;
+      }
+
+      case 'product': {
+        const sub = args[1] || 'query';
+        const familyId = args.slice(2).find((a) => !a.startsWith('-')) || flags.host;
+
+        if (sub === 'query') {
+          if (!familyId) {
+            console.error('Please specify a product family ID (e.g. "solution-cli product query recomputer_j40")');
+            process.exit(1);
+          }
+          const dto = queryProductFamily(familyId, { locale: flags.locale });
+          if (flags.json) {
+            console.log(JSON.stringify(dto, null, 2));
+          } else {
+            const fam = dto.records[0];
+            if (!fam) {
+              console.log(`Product family "${familyId}" not found.`);
+            } else {
+              console.log(`\n📦 Product Family: \x1b[1m${fam.title}\x1b[0m (${fam.family_id})`);
+              console.log(`  Default SKU: ${fam.default_sku || 'N/A'}`);
+              console.log(`  Regions: ${(fam.regions || []).join(', ') || 'Global'}`);
+              console.log(`  SKUs Available: ${fam.skus_count}`);
+              if (fam.physical_spec?.power_input) {
+                const p = fam.physical_spec.power_input;
+                console.log(`  Power Spec: ${p.voltage_v || ''}V ${p.min_current_a || ''}A (${p.connector}) ${p.polarity || ''}`);
+              }
+              console.log(`  Required Accessories: ${fam.required_accessories_count}`);
+              console.log(`  Optional Accessories: ${fam.optional_accessories_count}`);
+            }
+          }
+        } else if (sub === 'accessories') {
+          if (!familyId) {
+            console.error('Please specify a product family ID (e.g. "solution-cli product accessories recomputer_j40")');
+            process.exit(1);
+          }
+          const dto = queryAccessories(familyId, { sku: flags.sku, locale: flags.locale });
+          if (flags.json) {
+            console.log(JSON.stringify(dto, null, 2));
+          } else {
+            const record = dto.records[0];
+            if (!record) {
+              console.log(`Product family "${familyId}" not found.`);
+            } else {
+              console.log(`\n📦 Verified Accessories for \x1b[1m${record.host_title}\x1b[0m (${record.family_id}):`);
+              console.log(`  Host Default SKU: ${record.host_sku}`);
+              if (record.physical_spec?.power_input) {
+                const p = record.physical_spec.power_input;
+                console.log(`  Host Power Spec: ${p.voltage_v || ''}V ${p.min_current_a || ''}A (${p.connector || ''})`);
+              }
+
+              console.log('\n  \x1b[33m[REQUIRED (必需配件)]\x1b[0m');
+              if (record.accessories.required.length === 0) {
+                console.log('    (无强制单独采购的配件)');
+              } else {
+                record.accessories.required.forEach((acc) => {
+                  const stat = acc.compatibility.is_compatible ? '\x1b[32m✔\x1b[0m' : '\x1b[31m✖\x1b[0m';
+                  console.log(`    ${stat} \x1b[1m${acc.name}\x1b[0m (SKU: ${acc.sku || 'N/A'}, Qty: ${acc.qty})`);
+                  if (acc.reason) console.log(`      原因: ${acc.reason}`);
+                  if (acc.url) console.log(`      购买链接: ${acc.url}`);
+                });
+              }
+
+              console.log('\n  \x1b[36m[OPTIONAL (推荐选配)]\x1b[0m');
+              if (record.accessories.optional.length === 0) {
+                console.log('    (无选配项)');
+              } else {
+                record.accessories.optional.slice(0, 10).forEach((acc) => {
+                  const stat = acc.compatibility.is_compatible ? '\x1b[32m✔\x1b[0m' : '\x1b[31m✖\x1b[0m';
+                  console.log(`    ${stat} ${acc.name} (SKU: ${acc.sku || 'N/A'})`);
+                  if (acc.url) console.log(`      购买链接: ${acc.url}`);
+                });
+              }
+              console.log('');
+            }
+          }
+        } else if (sub === 'verify-compatibility') {
+          const comp = assertCompatibility(null, {
+            id: flags.accessory || 'custom_accessory',
+            name: flags.accessory || 'Custom Accessory',
+          });
+          if (flags.json) {
+            console.log(JSON.stringify(comp, null, 2));
+          } else {
+            const sym = comp.isCompatible ? '\x1b[32m✔\x1b[0m' : '\x1b[31m✖\x1b[0m';
+            console.log(`\n${sym} Physical Compatibility Status: ${comp.status}\n`);
+            comp.dimensions.forEach((d) => {
+              console.log(`  - [${d.dimension}] ${d.status}: ${d.reason}`);
+            });
+            console.log('');
+          }
+        } else {
+          console.error(`Unknown product action "${sub}". Supported: query, accessories, verify-compatibility`);
+          process.exit(1);
+        }
+        break;
+      }
+
+      case 'lockfile': {
+        const sub = args[1] || 'create';
+        if (sub !== 'create') {
+          console.error(`Unknown lockfile action "${sub}". Supported: "solution-cli lockfile create"`);
+          process.exit(1);
+        }
+        const solutionId = flags.solution || 'unspecified_solution';
+        const hardware = (flags.hardware || '').split(',').map((h) => h.trim()).filter(Boolean);
+        const lockfile = createDeploymentLockfile({
+          solutionId,
+          solutionVersion: flags.version,
+          selectedHardware: hardware,
+        });
+        if (flags.json) {
+          console.log(JSON.stringify(lockfile, null, 2));
+        } else {
+          console.log('\n🔒 Generated DeploymentLockfile:');
+          console.log(`  Solution: ${lockfile.solution_id}@${lockfile.solution_version}`);
+          console.log(`  Dataset: ${lockfile.dataset_version}`);
+          console.log(`  Network Isolation: Commercial queries DENIED during apply`);
+          console.log(`  Selected Hardware: ${lockfile.selected_hardware.join(', ') || 'Local Host'}\n`);
+        }
+        break;
+      }
+
+      default:
+        console.error(`Unknown command: "${command}". Run "solution-cli help" for usage.`);
+        process.exit(1);
+    }
+  } catch (err) {
+    console.error(`\n\x1b[31mError:\x1b[0m ${err.message}\n`);
+    process.exit(1);
+  }
+}
+
+main();

package/bin/runner.js

@@ -0,0 +1,39 @@
+#!/usr/bin/env node
+import fs from 'node:fs';
+import os from 'node:os';
+import { spawn } from 'node:child_process';
+import { getConfiguredEnginePath, isExecutable } from '../lib/platform.js';
+
+const binPath = getConfiguredEnginePath();
+
+if (!fs.existsSync(binPath) || !isExecutable(binPath)) {
+  console.error(`\x1b[31mError:\x1b[0m SenseCraft Engine binary not found at "${binPath}".`);
+  console.error('Please run "npx @sensecraft/cli install" first to provision the engine.\n');
+  process.exit(1);
+}
+
+const child = spawn(binPath, process.argv.slice(2), {
+  stdio: 'inherit'
+});
+
+const forwardSignal = sig => {
+  if (!child.killed) {
+    try { child.kill(sig); } catch {}
+  }
+};
+process.on('SIGINT', () => forwardSignal('SIGINT'));
+process.on('SIGTERM', () => forwardSignal('SIGTERM'));
+
+child.on('error', err => {
+  console.error(`Failed to launch engine binary: ${err.message}`);
+  process.exit(1);
+});
+
+child.on('exit', (code, signal) => {
+  if (signal) {
+    // POSIX standard: 128 + signal number (Codex Medium 14)
+    const sigNum = os.constants.signals[signal] || 1;
+    process.exit(128 + sigNum);
+  }
+  process.exit(code ?? 0);
+});