@seeed-studio/solution-cli 0.3.0 → 0.3.2

package/README.md

@@ -10,26 +10,46 @@ Compatible with **Claude Code, Codex, Google Antigravity (AGY), Work Buddy, and
 
 ## 1. Quick Start & Agent Installation
 
-Install the underlying engine and configure the AI Agent Skill with a single command:
+Install the underlying engine and configure the AI Agent Skill with one command:
 
 ```bash
-# Interactive mode (auto-scans local agent environments and prompts for selection)
-npx @seeed-studio/solution-cli install
+npx -y @seeed-studio/solution-cli@latest install --agent workbuddy -y
+```
 
-# Non-interactive mode (e.g. install to Claude Code and Antigravity)
-npx @seeed-studio/solution-cli install --agent claude,antigravity -y
+This example targets WorkBuddy explicitly. Replace `workbuddy` with the current
+Agent ID for another host. Use `npx -y @seeed-studio/solution-cli@latest install`
+for the interactive form: when one or more Agents are detected, pressing Enter
+selects all detected Agents, while entering the corresponding number selects one
+host. In non-interactive mode, `install -y` without `--agent` also selects all
+detected Agents when any are detected. If none are detected, these defaults still
+use the CLI's default target set; pass `--agent <agent-id>` to control the scope
+explicitly.
+
+The same command is safe to repeat. It checks the signed stable Engine release,
+reuses an equal or newer local Engine, and upgrades an older one. Existing
+modified or unregistered skills and protected symlinks are preserved. Use
+`--agent claude,antigravity` to select agents, or `--engine-path <path>` to pin
+a valid Engine binary. `--force` re-downloads an equal or older Engine and
+overwrites existing skill files, including user modifications; use it only when
+that overwrite is intended. Protected external symlinks are not followed, and
+it never downgrades a newer discovered Engine.
+
+Automatic reuse/upgrade rules start with publicly published solution-cli 0.3.1.
+A latest release or signature failure stops before changing the
+Engine or skills; an offline host must use a valid explicit local Engine path.
+
+The interactive form remains available when prompts are wanted:
 
-# Install globally
-npm install -g @seeed-studio/solution-cli
-solution-cli install -y
+```bash
+npx -y @seeed-studio/solution-cli@latest install
 ```
 
 ### Supported AI Agent Harnesses
-- **Claude Code**: `~/.claude/skills/sensecraft`
-- **Codex / OpenAI**: `~/.agents/skills/sensecraft` or `~/.codex/skills/sensecraft`
-- **Google Antigravity (AGY)**: `~/.gemini/config/skills/sensecraft`
-- **Work Buddy / Workbody**: `~/.workbuddy/skills/sensecraft`
-- **CodeBuddy**: `~/.codebuddy/skills/sensecraft`
+- **Claude Code**: `~/.claude/skills/solution-cli`
+- **Codex / OpenAI**: `~/.agents/skills/solution-cli` or `~/.codex/skills/solution-cli`
+- **Google Antigravity (AGY)**: `~/.gemini/config/skills/solution-cli`
+- **Work Buddy / Workbody**: `~/.workbuddy/skills/solution-cli`
+- **CodeBuddy**: `~/.codebuddy/skills/solution-cli`
 
 ---
 
@@ -45,7 +65,7 @@ The `solution-cli` provides unified commands for discovery, BOM calculation, dev
 | `solution-cli install [--agent <agents>] [-y]` | Inspect host environment, download/verify engine, and install Agent skills. |
 | `solution-cli status` | Inspect installed engine binary, content cache, and configured agent skills. |
 | `solution-cli doctor` | Run pre-flight diagnostics (OS, Docker daemon, serial permissions, PATH, ledger). |
-| `solution-cli uninstall [--agent <agents>]` | Cleanly remove SenseCraft skills using the installation ledger. |
+| `solution-cli uninstall [--agent <agents>]` | Cleanly remove Solution CLI skills using the installation ledger. |
 | `sensecraft-engine <subcommand>` | Direct proxy to the underlying high-performance Rust execution engine. |
 
 ---
@@ -110,7 +130,7 @@ Once installed, your AI Agent gains deep domain knowledge as an Edge IoT Solutio
 > 1. 提供方案对应的官方 GitHub 开源仓库地址；
 > 2. 指导用户克隆到本地工作区；
 > 3. 指导通过 TensorRT `trtexec` 完成端侧引擎转换，并在 `docker-compose.override.yml` 中挂载自定义模型；
-> 4. 使用 `sensecraft-engine deploy --solutions-dir ./solutions` 进行本地快速调测。
+> 4. 使用 `sensecraft-engine deploy <id> --solutions-dir ./solutions` 进行本地快速调测。
 
 ---
 

package/bin/cli.js

@@ -15,18 +15,17 @@ const command = args[0] || 'install';
 
 function printHelp() {
   console.log(`
-SenseCraft Solution CLI & Skill Toolset (${pkg.name})
+Solution CLI & Agent 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)
+  uninstall   Cleanly remove Solution CLI 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
@@ -42,7 +41,7 @@ Options:
   -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
+  --force              Re-download equal/older stable Engine and overwrite existing skill files, including local modifications; never downgrade a newer local Engine
   --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)
@@ -58,7 +57,15 @@ Examples:
 `);
 }
 
+class CliArgumentError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'CliArgumentError';
+  }
+}
+
 function parseFlags(rawArgs) {
+  const usedFlags = new Set();
   const flags = {
     agent: null,
     yes: false,
@@ -75,62 +82,121 @@ function parseFlags(rawArgs) {
     solution: null,
     version: '1.0.0',
     hardware: null,
+    positionals: [],
+    usedFlags,
   };
 
   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];
+    const valueFlag = (name, setter) => {
+      const inlinePrefix = `${name}=`;
+      if (a.startsWith(inlinePrefix)) {
+        const value = a.slice(inlinePrefix.length);
+        if (!value) throw new CliArgumentError(`${name} requires a value`);
+        usedFlags.add(name);
+        setter(value);
+        return true;
+      }
+      if (a === name) {
+        const value = rawArgs[i + 1];
+        if (!value || value.startsWith('-')) {
+          throw new CliArgumentError(`${name} requires a value`);
+        }
+        usedFlags.add(name);
+        setter(value);
+        i += 1;
+        return true;
+      }
+      return false;
+    };
+
+    if (valueFlag('--agent', value => { flags.agent = value; })) {
     } else if (a === '-y' || a === '--yes') {
+      usedFlags.add('--yes');
       flags.yes = true;
     } else if (a === '--dry-run') {
+      usedFlags.add('--dry-run');
       flags.dryRun = true;
     } else if (a === '--skip-content') {
+      usedFlags.add('--skip-content');
       flags.skipContent = true;
     } else if (a === '--force') {
+      usedFlags.add('--force');
       flags.force = true;
     } else if (a === '--json') {
+      usedFlags.add('--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];
+    } else if (valueFlag('--engine-path', value => { flags.enginePath = value; })) {
+    } else if (valueFlag('--limit', value => {
+      if (!/^[1-9]\d*$/.test(value)) throw new CliArgumentError('--limit requires a positive integer');
+      const limit = Number(value);
+      if (!Number.isSafeInteger(limit)) throw new CliArgumentError('--limit is too large');
+      flags.limit = limit;
+    })) {
+    } else if (valueFlag('--locale', value => { flags.locale = value; })) {
+    } else if (valueFlag('--sku', value => { flags.sku = value; })) {
+    } else if (valueFlag('--host', value => { flags.host = value; })) {
+    } else if (valueFlag('--accessory', value => { flags.accessory = value; })) {
+    } else if (valueFlag('--solution', value => { flags.solution = value; })) {
+    } else if (valueFlag('--version', value => { flags.version = value; })) {
+    } else if (valueFlag('--hardware', value => { flags.hardware = value; })) {
+    } else if (a.startsWith('-')) {
+      throw new CliArgumentError(`Unknown option "${a}"`);
+    } else {
+      flags.positionals.push(a);
     }
   }
 
   return flags;
 }
 
-async function main() {
-  const flags = parseFlags(args.slice(1));
+function validatePositionals(command, positionals) {
+  if (['install', 'uninstall', 'status', 'doctor'].includes(command) && positionals.length > 0) {
+    throw new CliArgumentError(`${command} does not accept positional arguments`);
+  }
+}
 
-  if (command === 'help' || command === '--help' || command === '-h') {
+function validateCommandFlags(command, flags) {
+  const allowed = {
+    install: ['--agent', '--yes', '--dry-run', '--skip-content', '--force', '--engine-path'],
+    uninstall: ['--agent', '--dry-run', '--force'],
+    status: ['--json'],
+    doctor: ['--json'],
+    hub: ['--json', '--locale', '--limit'],
+    product: ['--json', '--locale', '--sku', '--host', '--accessory'],
+    lockfile: ['--json', '--solution', '--version', '--hardware'],
+    help: [],
+  };
+  const supported = allowed[command];
+  if (!supported) return;
+  for (const flag of flags.usedFlags) {
+    if (!supported.includes(flag)) {
+      throw new CliArgumentError(`${flag} is not supported for ${command}`);
+    }
+  }
+}
+
+async function main() {
+  if (args.some(a => a === '--help' || a === '-h')) {
     printHelp();
-    process.exit(0);
+    return;
   }
 
   if (command === '--version' || command === '-v') {
     console.log(pkg.version);
-    process.exit(0);
+    return;
   }
 
   try {
+    const flags = parseFlags(args.slice(1));
+    validatePositionals(command, flags.positionals);
+    validateCommandFlags(command, flags);
+
+    if (command === 'help') {
+      printHelp();
+      return;
+    }
+
     switch (command) {
       case 'install':
         await runInstall(flags);
@@ -145,7 +211,7 @@ async function main() {
         if (flags.json) {
           console.log(JSON.stringify(report, null, 2));
         } else {
-          console.log('\n🩺 SenseCraft Doctor Environment Report:\n');
+          console.log('\n🩺 Solution CLI 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}`);
@@ -161,12 +227,12 @@ async function main() {
         break;
 
       case 'hub': {
-        const sub = args[1] || 'search';
+        const sub = flags.positionals[0] || '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 query = flags.positionals.slice(1).join(' ');
         const dto = await searchHub({ query, locale: flags.locale, limit: flags.limit });
         if (flags.json) {
           console.log(JSON.stringify(dto, null, 2));
@@ -200,8 +266,8 @@ async function main() {
       }
 
       case 'product': {
-        const sub = args[1] || 'query';
-        const familyId = args.slice(2).find((a) => !a.startsWith('-')) || flags.host;
+        const sub = flags.positionals[0] || 'query';
+        const familyId = flags.positionals[1] || flags.host;
 
         if (sub === 'query') {
           if (!familyId) {
@@ -296,7 +362,7 @@ async function main() {
       }
 
       case 'lockfile': {
-        const sub = args[1] || 'create';
+        const sub = flags.positionals[0] || 'create';
         if (sub !== 'create') {
           console.error(`Unknown lockfile action "${sub}". Supported: "solution-cli lockfile create"`);
           process.exit(1);
@@ -326,7 +392,7 @@ async function main() {
     }
   } catch (err) {
     console.error(`\n\x1b[31mError:\x1b[0m ${err.message}\n`);
-    process.exit(1);
+    process.exitCode = err instanceof CliArgumentError ? 2 : 1;
   }
 }
 

package/bin/runner.js

@@ -8,7 +8,7 @@ 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');
+  console.error('Please run "npx -y --package=@seeed-studio/solution-cli@latest solution-cli install --agent <agent-id>" first to provision the engine.\n');
   process.exit(1);
 }