voyageai-cli 1.28.0 → 1.29.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);
@@ -265,27 +299,396 @@ function registerWorkflow(program) {
   // ── workflow list ──
   wfCmd
     .command('list')
-    .description('List built-in workflow templates')
-    .action(() => {
-      const { listBuiltinWorkflows } = require('../lib/workflow');
-
-      const workflows = listBuiltinWorkflows();
-      if (workflows.length === 0) {
-        console.log(pc.dim('No built-in workflows found.'));
+    .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;
+
+      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;
+      }
+
+      console.log(`Installing ${pc.cyan(packageName)}...`);
+
+      try {
+        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}` : ''})`);
+          } 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');
+
+      console.log(`Searching npm for vai-workflow packages matching "${query}"...`);
+      console.log();
+
+      try {
+        const results = await searchNpm(query, { limit: parseInt(opts.limit, 10) });
+
+        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')

package/src/lib/explanations.js

@@ -1478,6 +1478,87 @@ const concepts = {
       'vai workflow run multi-collection-search --input query="test" --dry-run',
     ],
   },
+
+  'workflow-publishing': {
+    title: 'Publishing vai Workflows to npm',
+    summary: 'Share workflows as npm packages using the vai-workflow-* convention',
+    content: [
+      `${pc.bold('WHAT IS A WORKFLOW PACKAGE?')}`,
+      ``,
+      `A vai workflow package is an npm package containing a reusable workflow`,
+      `definition. It follows the naming convention ${pc.cyan('vai-workflow-<name>')} and contains:`,
+      ``,
+      `  • ${pc.cyan('workflow.json')}  — The workflow definition (same format as any vai workflow)`,
+      `  • ${pc.cyan('package.json')}   — npm metadata + vai-specific fields`,
+      `  • ${pc.cyan('README.md')}      — Usage instructions`,
+      ``,
+      `No JavaScript, no build step, no dependencies.`,
+      ``,
+      `${pc.bold('HOW TO PUBLISH')}`,
+      ``,
+      `Option 1: Package an existing workflow`,
+      ``,
+      `  ${pc.cyan('vai workflow create --from my-workflow.json --name my-workflow')}`,
+      ``,
+      `  This creates a ${pc.cyan('vai-workflow-my-workflow/')} directory with everything needed.`,
+      `  Review it, then:`,
+      ``,
+      `  ${pc.cyan('cd vai-workflow-my-workflow')}`,
+      `  ${pc.cyan('npm publish')}`,
+      ``,
+      `Option 2: Start from scratch`,
+      ``,
+      `  ${pc.cyan('vai workflow create --name my-workflow')}`,
+      ``,
+      `  This creates an interactive template you can fill in.`,
+      ``,
+      `${pc.bold('PACKAGE.JSON REQUIREMENTS')}`,
+      ``,
+      `Your package.json needs a ${pc.cyan('"vai"')} field with:`,
+      ``,
+      `  {`,
+      `    "vai": {`,
+      `      "workflowVersion": "1.0",`,
+      `      "tools": ["query", "rerank"],`,
+      `      "category": "retrieval"`,
+      `    }`,
+      `  }`,
+      ``,
+      `${pc.cyan('vai workflow create')} fills this in automatically.`,
+      ``,
+      `${pc.bold('NAMING')}`,
+      ``,
+      `Package names must start with ${pc.cyan('vai-workflow-')} followed by a lowercase, hyphenated name:`,
+      ``,
+      `  ${pc.green('✓')} vai-workflow-legal-research`,
+      `  ${pc.green('✓')} vai-workflow-code-review`,
+      `  ${pc.red('✗')} vai-legal-workflow  (wrong prefix)`,
+      ``,
+      `${pc.bold('CATEGORIES')}`,
+      ``,
+      `  ${pc.cyan('retrieval')}        — Search and retrieval pipelines`,
+      `  ${pc.cyan('analysis')}         — Comparison, consistency checking`,
+      `  ${pc.cyan('ingestion')}        — Document processing and storage`,
+      `  ${pc.cyan('domain-specific')}  — Industry-focused (legal, clinical, etc.)`,
+      `  ${pc.cyan('utility')}          — Cost estimation, benchmarking`,
+      `  ${pc.cyan('integration')}      — Multi-system workflows`,
+      ``,
+      `${pc.bold('TESTING BEFORE PUBLISHING')}`,
+      ``,
+      `  ${pc.cyan('vai workflow validate ./vai-workflow-my-workflow/workflow.json')}`,
+      `  ${pc.cyan('npm install ./vai-workflow-my-workflow')}`,
+      `  ${pc.cyan('vai workflow run vai-workflow-my-workflow --dry-run')}`,
+    ].join('\n'),
+    links: [
+      'https://github.com/mrlynn/voyageai-cli',
+    ],
+    tryIt: [
+      'vai workflow create --from my-pipeline.json --name my-pipeline',
+      'vai workflow create',
+      'vai workflow search legal',
+      'vai workflow install vai-workflow-legal-research',
+    ],
+  },
 };
 
 /**
@@ -1651,6 +1732,13 @@ const aliases = {
   'vai-workflow': 'workflows',
   pipeline: 'workflows',
   dag: 'workflows',
+  // Workflow publishing aliases
+  'workflow-publishing': 'workflow-publishing',
+  'publish-workflow': 'workflow-publishing',
+  'workflow-registry': 'workflow-publishing',
+  'community-workflows': 'workflow-publishing',
+  'share-workflow': 'workflow-publishing',
+  'npm-workflow': 'workflow-publishing',
 };
 
 /**