@seeed-studio/solution-cli 0.0.0-stage → 0.1.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,136 @@
+#!/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';
+
+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)
+  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 status and doctor)
+  --engine-path <path> Use custom engine executable path
+
+Examples:
+  npx @seeed-studio/solution-cli install
+  npx @seeed-studio/solution-cli install --agent workbuddy
+  npx @seeed-studio/solution-cli install --agent workbuddy,claude -y
+  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
+  };
+
+  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];
+    }
+  }
+
+  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;
+
+      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);
+});

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