voyageai-cli 1.28.0 → 1.30.0

package/src/commands/workflow.js

@@ -1,8 +1,22 @@
 'use strict';
 
+const path = require('path');
 const pc = require('picocolors');
 const ui = require('../lib/ui');
 
+/**
+ * Try to get the git user name for default author.
+ * @returns {string}
+ */
+function getGitAuthor() {
+  try {
+    const { execSync } = require('child_process');
+    return execSync('git config user.name', { encoding: 'utf8' }).trim();
+  } catch {
+    return '';
+  }
+}
+
 /**
  * Parse repeatable --input key=value options into an object.
  * Used as Commander's option reducer.
@@ -84,11 +98,31 @@ function registerWorkflow(program) {
     .option('--verbose', 'Show step details', false)
     .option('--no-interactive', 'Disable interactive input prompting')
     .action(async (file, opts) => {
-      const { loadWorkflow, executeWorkflow, buildExecutionPlan, validateWorkflow } = require('../lib/workflow');
+      const { executeWorkflow, buildExecutionPlan, validateWorkflow } = require('../lib/workflow');
+      const { resolveWorkflow } = require('../lib/workflow-registry');
 
       let definition;
       try {
-        definition = loadWorkflow(file);
+        const resolved = resolveWorkflow(file);
+        definition = resolved.definition;
+
+        // Show workflow source notice
+        if ((resolved.source === 'community' || resolved.source === 'official') && !opts.quiet) {
+          const pkg = resolved.metadata?.package;
+          const author = typeof pkg?.author === 'string' ? pkg.author : pkg?.author?.name || 'unknown';
+          const tools = (pkg?.vai?.tools || []).join(', ');
+          const isOfficial = resolved.source === 'official';
+          const label = isOfficial ? 'official catalog workflow' : 'community workflow';
+          console.error(`${pc.dim('ℹ')} Running ${label}: ${pc.cyan(pkg?.name || file)} ${pc.dim(`v${pkg?.version || '?'}`)}`);
+          console.error(`  ${pc.dim(`by ${author}`)}${tools ? pc.dim(` | Tools: ${tools}`) : ''}`);
+          if (!isOfficial) {
+            console.error(`  ${pc.dim('This is a community-contributed workflow, not maintained by the vai project.')}`);
+          }
+          console.error();
+          for (const w of resolved.metadata?.warnings || []) {
+            console.error(`  ${pc.yellow('⚠')} ${w}`);
+          }
+        }
       } catch (err) {
         console.error(ui.error(err.message));
         process.exit(1);
@@ -154,6 +188,12 @@ function registerWorkflow(program) {
       }
 
       // Execute workflow
+      const telemetry = require('../lib/telemetry');
+      const wfDone = telemetry.timer('cli_workflow_run', {
+        workflowName,
+        stepCount: definition.steps?.length || 0,
+        isBuiltin: !!(definition._source === 'builtin'),
+      });
       try {
         const result = await executeWorkflow(definition, {
           inputs: opts.input,
@@ -190,6 +230,8 @@ function registerWorkflow(program) {
           console.error();
         }
 
+        wfDone();
+
         // Output
         if (opts.json) {
           console.log(JSON.stringify(result.output, null, 2));
@@ -227,6 +269,269 @@ function registerWorkflow(program) {
       }
     });
 
+  // ── workflow check <path> ──
+  wfCmd
+    .command('check <path>')
+    .description('Run validation, security, and quality checks on a workflow package')
+    .option('--security', 'Run security checks only', false)
+    .option('--quality', 'Run quality checks only', false)
+    .option('--all', 'Run all check tiers', false)
+    .option('--json', 'Output machine-readable JSON', false)
+    .option('--ci', 'Output CI-optimized JSON with summary metadata', false)
+    .action((pkgPath, opts) => {
+      const { validateSchemaEnhanced, loadWorkflow } = require('../lib/workflow');
+      const { securityAudit, extractCapabilities } = require('../lib/security-audit');
+      const { qualityAudit } = require('../lib/quality-audit');
+      const fs = require('fs');
+
+      const resolvedPath = path.resolve(pkgPath);
+      const runAll = opts.all || (!opts.security && !opts.quality);
+
+      // Load workflow definition
+      let definition;
+      let pkg = {};
+      let workflowFile;
+
+      try {
+        // Check if it's a directory (package) or a single file
+        const stat = fs.statSync(resolvedPath);
+        if (stat.isDirectory()) {
+          // Package directory
+          const pkgJsonPath = path.join(resolvedPath, 'package.json');
+          if (fs.existsSync(pkgJsonPath)) {
+            pkg = JSON.parse(fs.readFileSync(pkgJsonPath, 'utf8'));
+          }
+          // Find workflow file
+          workflowFile = pkg.main || 'workflow.json';
+          const wfPath = path.join(resolvedPath, workflowFile);
+          if (fs.existsSync(wfPath)) {
+            definition = JSON.parse(fs.readFileSync(wfPath, 'utf8'));
+          } else {
+            console.error(ui.error(`Workflow file not found: ${wfPath}`));
+            process.exit(1);
+          }
+        } else {
+          // Single file
+          definition = loadWorkflow(resolvedPath);
+        }
+      } catch (err) {
+        console.error(ui.error(err.message));
+        process.exit(1);
+      }
+
+      const results = { schema: [], security: [], quality: [], capabilities: [] };
+
+      // L1: Schema validation (always runs)
+      if (runAll || (!opts.security && !opts.quality)) {
+        results.schema = validateSchemaEnhanced(definition);
+      }
+
+      // L2: Security
+      if (runAll || opts.security) {
+        const packageDir = fs.statSync(resolvedPath).isDirectory() ? resolvedPath : null;
+        results.security = securityAudit(definition, packageDir);
+        results.capabilities = [...extractCapabilities(definition)];
+      }
+
+      // L3: Quality
+      if (runAll || opts.quality) {
+        const packageDir = fs.statSync(resolvedPath).isDirectory() ? resolvedPath : null;
+        results.quality = qualityAudit(definition, pkg, packageDir);
+      }
+
+      // CI output (machine-readable JSON with summary metadata)
+      if (opts.ci) {
+        const criticalCount = results.security.filter(f => f.severity === 'critical').length;
+        const highCount = results.security.filter(f => f.severity === 'high').length;
+        const schemaPass = results.schema.length === 0;
+        const securityPass = criticalCount === 0 && highCount === 0;
+        const qualityPass = results.quality.filter(i => i.level === 'error').length === 0;
+        const ciOutput = {
+          schema: { pass: schemaPass, errors: results.schema },
+          security: { pass: securityPass, findings: results.security },
+          quality: { pass: qualityPass, issues: results.quality },
+          capabilities: results.capabilities,
+          summary: {
+            passAll: schemaPass && securityPass && qualityPass,
+            criticalCount,
+            highCount,
+          },
+        };
+        console.log(JSON.stringify(ciOutput, null, 2));
+        if (criticalCount > 0) process.exit(2);
+        if (highCount > 0) process.exit(1);
+        return;
+      }
+
+      // JSON output
+      if (opts.json) {
+        console.log(JSON.stringify(results, null, 2));
+        // Exit code 1 if critical/high security findings
+        const hasCritical = results.security.some(f => f.severity === 'critical' || f.severity === 'high');
+        if (hasCritical) process.exit(1);
+        return;
+      }
+
+      // Pretty output
+      console.log();
+      console.log(pc.bold(`Workflow Check: ${definition.name || pkgPath}`));
+      console.log(pc.dim('═'.repeat(50)));
+
+      // Schema
+      if (results.schema.length > 0) {
+        console.log();
+        console.log(pc.bold('Schema Validation:'));
+        for (const e of results.schema) {
+          console.log(`  ${pc.red('✗')} ${e}`);
+        }
+      } else if (runAll || (!opts.security && !opts.quality)) {
+        console.log();
+        console.log(`${pc.bold('Schema Validation:')} ${pc.green('✔ passed')}`);
+      }
+
+      // Security
+      if (runAll || opts.security) {
+        console.log();
+        console.log(pc.bold('Security Audit:'));
+        if (results.security.length === 0) {
+          console.log(`  ${pc.green('✔')} No security issues found`);
+        } else {
+          for (const f of results.security) {
+            const color = f.severity === 'critical' ? pc.red :
+                          f.severity === 'high' ? pc.red :
+                          f.severity === 'medium' ? pc.yellow : pc.dim;
+            const icon = f.severity === 'critical' || f.severity === 'high' ? '✗' : '⚠';
+            console.log(`  ${color(icon)} [${f.severity.toUpperCase()}] ${f.message}`);
+          }
+        }
+
+        // Capability flags
+        if (results.capabilities.length > 0) {
+          console.log();
+          console.log(pc.bold('Capabilities:'));
+          const capIcons = { NETWORK: '🌐', WRITE_DB: '💾', LLM: '🤖', LOOP: '🔄', READ_DB: '📊' };
+          for (const cap of results.capabilities) {
+            console.log(`  ${capIcons[cap] || '•'} ${cap}`);
+          }
+        }
+      }
+
+      // Quality
+      if (runAll || opts.quality) {
+        console.log();
+        console.log(pc.bold('Quality Audit:'));
+        if (results.quality.length === 0) {
+          console.log(`  ${pc.green('✔')} No quality issues found`);
+        } else {
+          for (const issue of results.quality) {
+            const color = issue.level === 'error' ? pc.red :
+                          issue.level === 'warning' ? pc.yellow : pc.dim;
+            const icon = issue.level === 'error' ? '✗' : issue.level === 'warning' ? '⚠' : 'ℹ';
+            console.log(`  ${color(icon)} [${issue.level.toUpperCase()}] ${issue.message}`);
+          }
+        }
+      }
+
+      console.log();
+
+      // Exit code 1 if critical/high security findings
+      const hasCritical = results.security.some(f => f.severity === 'critical' || f.severity === 'high');
+      if (hasCritical) process.exit(1);
+    });
+
+  // ── workflow test <path> ──
+  wfCmd
+    .command('test <path>')
+    .description('Run test fixtures for a workflow package')
+    .option('--test <name>', 'Run a specific test case by name')
+    .option('--json', 'Output machine-readable JSON', false)
+    .action(async (pkgPath, opts) => {
+      const { loadWorkflow } = require('../lib/workflow');
+      const { runAllTests, loadTestCases } = require('../lib/workflow-test-runner');
+      const fs = require('fs');
+
+      const resolvedPath = path.resolve(pkgPath);
+
+      // Load workflow definition
+      let definition;
+      try {
+        const stat = fs.statSync(resolvedPath);
+        if (stat.isDirectory()) {
+          const wfPath = path.join(resolvedPath, 'workflow.json');
+          if (fs.existsSync(wfPath)) {
+            definition = JSON.parse(fs.readFileSync(wfPath, 'utf8'));
+          } else {
+            console.error(ui.error(`Workflow file not found: ${wfPath}`));
+            process.exit(1);
+          }
+        } else {
+          console.error(ui.error('Path must be a workflow package directory'));
+          process.exit(1);
+        }
+      } catch (err) {
+        console.error(ui.error(err.message));
+        process.exit(1);
+      }
+
+      // Check for tests directory
+      const testsDir = path.join(resolvedPath, 'tests');
+      if (!fs.existsSync(testsDir)) {
+        console.error(ui.error('No tests/ directory found in package'));
+        process.exit(1);
+      }
+
+      const testCases = loadTestCases(resolvedPath);
+      if (testCases.length === 0) {
+        console.error(ui.error('No *.test.json files found in tests/'));
+        process.exit(1);
+      }
+
+      try {
+        const aggregate = await runAllTests(definition, resolvedPath, {
+          testName: opts.test,
+        });
+
+        if (opts.json) {
+          console.log(JSON.stringify(aggregate, null, 2));
+          if (aggregate.failed > 0) process.exit(1);
+          return;
+        }
+
+        // Pretty output
+        console.log();
+        console.log(pc.bold(`Workflow Tests: ${definition.name || pkgPath}`));
+        console.log(pc.dim('═'.repeat(50)));
+        console.log();
+
+        for (const result of aggregate.results) {
+          const icon = result.passed ? pc.green('✔') : pc.red('✗');
+          console.log(`${icon} ${result.name || result.file}`);
+
+          if (result.error) {
+            console.log(`  ${pc.red(result.error)}`);
+          }
+
+          for (const assertion of result.assertions) {
+            const aIcon = assertion.pass ? pc.green('  ✔') : pc.red('  ✗');
+            console.log(`${aIcon} ${assertion.message}`);
+          }
+
+          for (const err of (result.errors || [])) {
+            console.log(`  ${pc.red('Error:')} ${err}`);
+          }
+        }
+
+        console.log();
+        console.log(`${pc.bold('Summary:')} ${pc.green(`${aggregate.passed} passed`)}, ${aggregate.failed > 0 ? pc.red(`${aggregate.failed} failed`) : `${aggregate.failed} failed`}`);
+        console.log();
+
+        if (aggregate.failed > 0) process.exit(1);
+      } catch (err) {
+        console.error(ui.error(err.message));
+        process.exit(1);
+      }
+    });
+
   // ── workflow validate <file> ──
   wfCmd
     .command('validate <file>')
@@ -265,27 +570,411 @@ function registerWorkflow(program) {
   // ── workflow list ──
   wfCmd
     .command('list')
-    .description('List built-in workflow templates')
-    .action(() => {
-      const { listBuiltinWorkflows } = require('../lib/workflow');
+    .description('List available workflows (built-in + official + community)')
+    .option('--built-in', 'Show only built-in workflows', false)
+    .option('--official', 'Show only official @vaicli workflows', false)
+    .option('--community', 'Show only community workflows', false)
+    .option('--category <name>', 'Filter by category')
+    .option('--tag <name>', 'Filter by tag')
+    .option('--json', 'Output JSON', false)
+    .action((opts) => {
+      const { getRegistry } = require('../lib/workflow-registry');
+      const registry = getRegistry({ force: true });
+
+      const showBuiltIn = !opts.community && !opts.official;
+      const showOfficial = !opts.builtIn && !opts.community;
+      const showCommunity = !opts.builtIn && !opts.official;
 
-      const workflows = listBuiltinWorkflows();
-      if (workflows.length === 0) {
-        console.log(pc.dim('No built-in workflows found.'));
+      if (opts.json) {
+        const out = {};
+        if (showBuiltIn) out.builtIn = registry.builtIn;
+        if (showOfficial) out.official = registry.official.filter(c => c.errors.length === 0);
+        if (showCommunity) out.community = registry.community.filter(c => c.errors.length === 0);
+        console.log(JSON.stringify(out, null, 2));
         return;
       }
 
-      console.log();
-      console.log(pc.bold('Built-in workflow templates:'));
-      console.log();
-      for (const wf of workflows) {
-        console.log(`  ${pc.cyan(wf.name.padEnd(28))} ${wf.description}`);
+      /**
+       * Display a list of package-based workflows (official or community).
+       */
+      function displayPackageList(items, label, emptyHint) {
+        let filtered = items.filter(c => c.errors.length === 0);
+        if (opts.category) {
+          filtered = filtered.filter(c => (c.pkg?.vai?.category || 'utility') === opts.category);
+        }
+        if (opts.tag) {
+          filtered = filtered.filter(c => (c.pkg?.vai?.tags || []).includes(opts.tag));
+        }
+
+        console.log();
+        console.log(pc.bold(`${label} (${filtered.length})`));
+        if (filtered.length === 0) {
+          console.log(pc.dim(`  (${emptyHint})`));
+        } else {
+          for (const wf of filtered) {
+            const pkg = wf.pkg || {};
+            const author = typeof pkg.author === 'string' ? pkg.author : pkg.author?.name || '';
+            const tags = (pkg.vai?.tags || []).join(' · ');
+            console.log(`  ${pc.cyan(wf.name.padEnd(42))} ${pkg.description || ''}`);
+            if (author || tags) {
+              console.log(`    ${pc.dim(`by ${author}`)}${pkg.version ? pc.dim(` | v${pkg.version}`) : ''}${tags ? pc.dim(` | ${tags}`) : ''}`);
+            }
+          }
+        }
+
+        // Show invalid packages as warnings
+        const invalid = items.filter(c => c.errors.length > 0);
+        if (invalid.length > 0) {
+          console.log();
+          for (const inv of invalid) {
+            console.error(`  ${pc.yellow('⚠')} ${inv.name}: ${inv.errors[0]}`);
+          }
+        }
       }
+
+      // Built-in
+      if (showBuiltIn) {
+        console.log();
+        console.log(pc.bold(`Built-in Workflows (${registry.builtIn.length})`));
+        if (registry.builtIn.length === 0) {
+          console.log(pc.dim('  (none)'));
+        } else {
+          for (const wf of registry.builtIn) {
+            console.log(`  ${pc.cyan(wf.name.padEnd(28))} ${wf.description}`);
+          }
+        }
+      }
+
+      // Official Catalog (@vaicli)
+      if (showOfficial) {
+        displayPackageList(registry.official, 'Official Catalog (@vaicli)', 'none installed');
+      }
+
+      // Community
+      if (showCommunity) {
+        displayPackageList(registry.community, 'Community Workflows', 'none installed — install with: vai workflow install <package-name>');
+      }
+
       console.log();
       console.log(pc.dim('Run with: vai workflow run <name> --input key=value'));
       console.log();
     });
 
+  // ── workflow install ──
+  wfCmd
+    .command('install <package>')
+    .description('Install a workflow from npm')
+    .option('--global', 'Install globally', false)
+    .option('--json', 'Output JSON', false)
+    .action(async (packageName, opts) => {
+      const { installPackage, WORKFLOW_PREFIX, isWorkflowPackage, isOfficialPackage } = require('../lib/npm-utils');
+      const { validatePackage, clearRegistryCache } = require('../lib/workflow-registry');
+
+      // Auto-prefix if needed (but not for scoped packages)
+      if (!packageName.startsWith('@') && !packageName.startsWith(WORKFLOW_PREFIX)) {
+        packageName = WORKFLOW_PREFIX + packageName;
+      }
+
+      const telemetry = require('../lib/telemetry');
+      console.log(`Installing ${pc.cyan(packageName)}...`);
+
+      try {
+        telemetry.send('cli_workflow_install', { packageName });
+        const result = installPackage(packageName, { global: opts.global });
+        console.log(`${pc.green('✔')} Downloaded ${pc.cyan(packageName)}@${result.version}`);
+
+        // Validate
+        if (result.path) {
+          const validation = validatePackage(result.path);
+          if (validation.errors.length === 0) {
+            const steps = validation.definition?.steps?.length || 0;
+            const tools = (validation.pkg?.vai?.tools || []).join(', ');
+            console.log(`${pc.green('✔')} Validated workflow definition (${steps} steps${tools ? `, tools: ${tools}` : ''})`);
+
+            // Display capability flags
+            if (validation.definition) {
+              const { extractCapabilities } = require('../lib/security-audit');
+              const caps = extractCapabilities(validation.definition);
+              if (caps.size > 0) {
+                const capIcons = { NETWORK: '🌐', WRITE_DB: '💾', LLM: '🤖', LOOP: '🔄', READ_DB: '📊' };
+                const capList = [...caps].map(c => `${capIcons[c] || '•'} ${c}`).join('  ');
+                console.log(`${pc.dim('Capabilities:')} ${capList}`);
+              }
+            }
+          } else {
+            console.log(`${pc.yellow('⚠')} Validation issues:`);
+            for (const e of validation.errors) {
+              console.log(`  ${pc.yellow('-')} ${e}`);
+            }
+            console.log();
+            console.log(pc.dim('The package was installed but the workflow may not execute correctly.'));
+          }
+          for (const w of validation.warnings) {
+            console.log(`${pc.yellow('⚠')} ${w}`);
+          }
+        }
+
+        clearRegistryCache();
+
+        if (opts.json) {
+          console.log(JSON.stringify(result, null, 2));
+        } else {
+          console.log();
+          console.log(`Installed. Run with:`);
+          console.log(`  ${pc.cyan(`vai workflow run ${packageName}`)} --input key=value`);
+        }
+      } catch (err) {
+        console.error(ui.error(err.message));
+        process.exit(1);
+      }
+    });
+
+  // ── workflow uninstall ──
+  wfCmd
+    .command('uninstall <package>')
+    .description('Remove a workflow package')
+    .option('--global', 'Uninstall globally', false)
+    .action((packageName, opts) => {
+      const { uninstallPackage, WORKFLOW_PREFIX } = require('../lib/npm-utils');
+      const { clearRegistryCache } = require('../lib/workflow-registry');
+
+      if (!packageName.startsWith('@') && !packageName.startsWith(WORKFLOW_PREFIX)) {
+        packageName = WORKFLOW_PREFIX + packageName;
+      }
+
+      console.log(`Uninstalling ${pc.cyan(packageName)}...`);
+
+      try {
+        uninstallPackage(packageName, { global: opts.global });
+        clearRegistryCache();
+        console.log(`${pc.green('✔')} Removed ${packageName}`);
+      } catch (err) {
+        console.error(ui.error(err.message));
+        process.exit(1);
+      }
+    });
+
+  // ── workflow search ──
+  wfCmd
+    .command('search <query>')
+    .description('Search npm for community workflows')
+    .option('--limit <n>', 'Maximum results', '10')
+    .option('--json', 'Output JSON', false)
+    .action(async (query, opts) => {
+      const { searchNpm } = require('../lib/npm-utils');
+
+      const telemetry = require('../lib/telemetry');
+      console.log(`Searching npm for vai-workflow packages matching "${query}"...`);
+      console.log();
+
+      try {
+        const results = await searchNpm(query, { limit: parseInt(opts.limit, 10) });
+        telemetry.send('cli_workflow_search', { query: query.slice(0, 50), resultCount: results.length });
+
+        if (opts.json) {
+          console.log(JSON.stringify(results, null, 2));
+          return;
+        }
+
+        if (results.length === 0) {
+          console.log(pc.dim('  No matching workflow packages found.'));
+          console.log();
+          return;
+        }
+
+        for (const r of results) {
+          const badge = r.official ? `  ${pc.green('[OFFICIAL]')}` : '';
+          console.log(`  ${pc.cyan(r.name)}  ${pc.dim(`v${r.version}`)}${badge}`);
+          if (r.description) console.log(`    ${r.description}`);
+          console.log(`    ${pc.dim(`by ${r.author}`)}${r.keywords.length ? pc.dim(` | ${r.keywords.slice(0, 5).join(', ')}`) : ''}`);
+          console.log();
+        }
+
+        console.log(pc.dim(`Install: vai workflow install <package-name>`));
+        console.log();
+      } catch (err) {
+        console.error(ui.error(err.message));
+        process.exit(1);
+      }
+    });
+
+  // ── workflow info ──
+  wfCmd
+    .command('info <name>')
+    .description('Show detailed info about an installed workflow')
+    .option('--json', 'Output JSON', false)
+    .action((name, opts) => {
+      const { resolveWorkflow, getRegistry } = require('../lib/workflow-registry');
+      const { WORKFLOW_PREFIX } = require('../lib/npm-utils');
+
+      try {
+        const resolved = resolveWorkflow(name);
+
+        if (opts.json) {
+          console.log(JSON.stringify({ source: resolved.source, definition: resolved.definition, metadata: resolved.metadata }, null, 2));
+          return;
+        }
+
+        const def = resolved.definition;
+        console.log();
+
+        if (resolved.source === 'community' || resolved.source === 'official') {
+          const pkg = resolved.metadata?.package || {};
+          const author = typeof pkg.author === 'string' ? pkg.author : pkg.author?.name || 'unknown';
+          const vai = pkg.vai || {};
+
+          console.log(`${pc.bold(pc.cyan(pkg.name || name))} ${pc.dim(`v${pkg.version || '?'}`)}`);
+          console.log(`  ${pkg.description || def.description || ''}`);
+          console.log();
+          console.log(`  ${pc.dim('Author:')}     ${author}`);
+          console.log(`  ${pc.dim('License:')}    ${pkg.license || 'unknown'}`);
+          console.log(`  ${pc.dim('Category:')}   ${vai.category || 'utility'}`);
+          if (vai.tags?.length) console.log(`  ${pc.dim('Tags:')}       ${vai.tags.join(', ')}`);
+          if (vai.minVaiVersion) console.log(`  ${pc.dim('Min vai:')}    v${vai.minVaiVersion}`);
+          if (vai.tools?.length) console.log(`  ${pc.dim('Tools:')}      ${vai.tools.join(', ')}`);
+          console.log(`  ${pc.dim('Steps:')}      ${def.steps?.length || 0}`);
+          console.log(`  ${pc.dim('Source:')}     ${resolved.metadata?.path || 'unknown'}`);
+          if (pkg.name) console.log(`  ${pc.dim('npm:')}        https://www.npmjs.com/package/${pkg.name}`);
+        } else {
+          console.log(`${pc.bold(pc.cyan(def.name || name))} ${pc.dim(`[${resolved.source}]`)}`);
+          console.log(`  ${def.description || ''}`);
+          console.log(`  ${pc.dim('Steps:')} ${def.steps?.length || 0}`);
+        }
+
+        // Show inputs
+        if (def.inputs && Object.keys(def.inputs).length > 0) {
+          console.log();
+          console.log(`  ${pc.bold('Inputs:')}`);
+          for (const [key, schema] of Object.entries(def.inputs)) {
+            const req = schema.required ? pc.red('(required)') : pc.dim(`(default: ${schema.default ?? 'none'})`);
+            const desc = schema.description || '';
+            console.log(`    ${pc.cyan(key.padEnd(16))} ${(schema.type || 'string').padEnd(8)} ${req}  ${pc.dim(desc)}`);
+          }
+        }
+
+        console.log();
+      } catch (err) {
+        console.error(ui.error(err.message));
+        process.exit(1);
+      }
+    });
+
+  // ── workflow create ──
+  wfCmd
+    .command('create')
+    .description('Scaffold a publish-ready npm package from a workflow')
+    .option('--from <file>', 'Existing workflow JSON to package')
+    .option('--name <name>', 'Package name (without vai-workflow- prefix)')
+    .option('--author <name>', 'Author name')
+    .option('--description <desc>', 'Package description')
+    .option('--category <cat>', 'Category (retrieval, analysis, ingestion, domain-specific, utility, integration)')
+    .option('--scope <scope>', 'Package scope (e.g. "vaicli" for @vaicli/vai-workflow-*)')
+    .option('--output <dir>', 'Output directory')
+    .action(async (opts) => {
+      const { scaffoldPackage, toPackageName, CATEGORIES, emptyWorkflowTemplate } = require('../lib/workflow-scaffold');
+      const { loadWorkflow } = require('../lib/workflow');
+
+      let definition;
+      let name = opts.name;
+      let author = opts.author;
+      let description = opts.description;
+      let category = opts.category;
+
+      if (opts.from) {
+        // Package an existing workflow
+        try {
+          definition = loadWorkflow(opts.from);
+        } catch (err) {
+          console.error(ui.error(err.message));
+          process.exit(1);
+        }
+        if (!name) {
+          name = definition.name || path.basename(opts.from, '.json').replace('.vai-workflow', '');
+        }
+        if (!description) {
+          description = definition.description;
+        }
+      } else if (process.stdin.isTTY) {
+        // Interactive mode
+        try {
+          const p = require('@clack/prompts');
+          p.intro(pc.bold('Create a new workflow package'));
+
+          const answers = await p.group({
+            name: () => p.text({ message: 'Workflow name', placeholder: 'my-workflow', validate: v => v ? undefined : 'Required' }),
+            description: () => p.text({ message: 'Description', placeholder: 'A brief description of what this workflow does' }),
+            category: () => p.select({
+              message: 'Category',
+              options: CATEGORIES.map(c => ({ value: c, label: c })),
+            }),
+            author: () => p.text({ message: 'Author', placeholder: 'Your Name', defaultValue: getGitAuthor() }),
+          });
+
+          if (p.isCancel(answers)) {
+            p.cancel('Cancelled.');
+            process.exit(0);
+          }
+
+          name = answers.name;
+          description = answers.description;
+          category = answers.category;
+          author = answers.author;
+          definition = emptyWorkflowTemplate();
+          definition.name = name;
+          definition.description = description || '';
+          // Add a placeholder step so validation passes
+          definition.steps = [{
+            id: 'search',
+            tool: 'query',
+            name: 'Search',
+            inputs: { query: '{{ inputs.query }}' },
+          }];
+          definition.inputs = {
+            query: { type: 'string', required: true, description: 'Search query' },
+          };
+        } catch (err) {
+          console.error(ui.error(`Interactive mode failed: ${err.message}`));
+          process.exit(1);
+        }
+      } else {
+        console.error(ui.error('Provide --from <file> or run interactively (TTY required).'));
+        process.exit(1);
+      }
+
+      if (!name) {
+        console.error(ui.error('Workflow name is required. Use --name <name>.'));
+        process.exit(1);
+      }
+
+      try {
+        const result = scaffoldPackage({
+          definition,
+          name,
+          author,
+          description,
+          category,
+          scope: opts.scope,
+          outputDir: opts.output,
+        });
+
+        const pkgName = toPackageName(name, { scope: opts.scope });
+        console.log();
+        console.log(`${pc.green('✔')} Created ${pc.cyan(pkgName)}/`);
+        for (const f of result.files) {
+          console.log(`  ${pc.dim('├──')} ${f}`);
+        }
+        console.log();
+        console.log('Next steps:');
+        console.log(`  1. ${opts.from ? '' : pc.dim('Edit workflow.json with your workflow definition')}${opts.from ? 'Review README.md' : ''}`);
+        console.log(`  2. cd ${pkgName}`);
+        console.log(`  3. npm publish`);
+        console.log();
+      } catch (err) {
+        console.error(ui.error(err.message));
+        process.exit(1);
+      }
+    });
+
   // ── workflow init ──
   wfCmd
     .command('init')