@agenticmail/enterprise 0.3.2 → 0.4.0

package/src/engine/cli-build-skill.ts

@@ -0,0 +1,285 @@
+/**
+ * CLI: agenticmail-enterprise build-skill
+ *
+ * Interactive AI-assisted skill scaffolding. Prompts for the target
+ * application/service, generates a valid agenticmail-skill.json manifest,
+ * validates it, and writes it to disk.
+ *
+ * If an agent runtime is running locally, uses it for AI generation.
+ * Otherwise, falls back to template-based generation.
+ */
+
+import { validateSkillManifest, VALID_CATEGORIES, VALID_RISK_LEVELS } from './skill-validator.js';
+
+export async function runBuildSkill(_args: string[]) {
+  const chalk = (await import('chalk')).default;
+  const ora = (await import('ora')).default;
+  const inquirer = (await import('inquirer')).default;
+  const fs = await import('fs/promises');
+  const path = await import('path');
+
+  console.log('');
+  console.log(chalk.bold('\uD83D\uDEE0\uFE0F  AgenticMail Community Skill Builder'));
+  console.log(chalk.dim('  Generate a valid agenticmail-skill.json for any application'));
+  console.log('');
+
+  // ── Gather inputs ─────────────────────────────────
+
+  const answers = await inquirer.prompt([
+    {
+      type: 'input',
+      name: 'application',
+      message: 'What application or service should this skill integrate with?',
+      validate: (v: string) => v.trim().length > 0 || 'Application name is required',
+    },
+    {
+      type: 'input',
+      name: 'operations',
+      message: 'What operations should it support? (comma-separated)',
+      default: 'read, create, update, delete, list',
+    },
+    {
+      type: 'list',
+      name: 'category',
+      message: 'Category:',
+      choices: [...VALID_CATEGORIES],
+      default: 'productivity',
+    },
+    {
+      type: 'list',
+      name: 'risk',
+      message: 'Risk level:',
+      choices: [...VALID_RISK_LEVELS],
+      default: 'medium',
+    },
+    {
+      type: 'input',
+      name: 'author',
+      message: 'Your GitHub username:',
+      validate: (v: string) => /^[a-zA-Z0-9_-]+$/.test(v.trim()) || 'Must be a valid GitHub username',
+    },
+    {
+      type: 'input',
+      name: 'outputDir',
+      message: 'Output directory:',
+      default: (a: any) => `./community-skills/${a.application.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '')}`,
+    },
+  ]);
+
+  const appSlug = answers.application.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '');
+  const toolPrefix = appSlug.replace(/-/g, '_');
+  const operations = answers.operations.split(',').map((s: string) => s.trim()).filter(Boolean);
+
+  // ── Try AI generation via local agent runtime ─────
+
+  let manifest: any = null;
+  const spinner = ora('Generating skill manifest...').start();
+
+  try {
+    // Check if agent runtime is running locally
+    const res = await fetch('http://localhost:3000/health', { signal: AbortSignal.timeout(2000) });
+    if (res.ok) {
+      spinner.text = 'Agent runtime detected — using AI to generate manifest...';
+      const aiRes = await fetch('http://localhost:3000/api/chat', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+          message: buildAIPrompt(answers.application, operations, answers.category, answers.risk, answers.author, appSlug, toolPrefix),
+          system: 'You are a skill manifest generator. Respond with ONLY valid JSON, no markdown, no explanation.',
+        }),
+        signal: AbortSignal.timeout(30000),
+      });
+      if (aiRes.ok) {
+        const aiData = await aiRes.json();
+        const content = aiData.response || aiData.message || '';
+        const jsonMatch = content.match(/\{[\s\S]*\}/);
+        if (jsonMatch) {
+          manifest = JSON.parse(jsonMatch[0]);
+        }
+      }
+    }
+  } catch {
+    // Agent runtime not available — fall back to template
+  }
+
+  // ── Fallback: template-based generation ───────────
+
+  if (!manifest) {
+    spinner.text = 'Generating from template...';
+    manifest = generateFromTemplate(answers.application, operations, answers.category, answers.risk, answers.author, appSlug, toolPrefix);
+  }
+
+  spinner.succeed('Manifest generated');
+
+  // ── Validate ──────────────────────────────────────
+
+  const validation = validateSkillManifest(manifest);
+  if (!validation.valid) {
+    console.log(chalk.yellow('\n  Validation warnings (auto-fixing)...'));
+    // Try to fix common issues
+    if (!manifest.category) manifest.category = answers.category;
+    if (!manifest.risk) manifest.risk = answers.risk;
+    if (!manifest.license) manifest.license = 'MIT';
+    if (!manifest.description || manifest.description.length < 20) {
+      manifest.description = `Integrates with ${answers.application} to ${operations.slice(0, 3).join(', ')} and more.`;
+    }
+  }
+
+  // ── Write files ───────────────────────────────────
+
+  const outDir = path.resolve(answers.outputDir);
+  await fs.mkdir(outDir, { recursive: true });
+
+  const manifestPath = path.join(outDir, 'agenticmail-skill.json');
+  await fs.writeFile(manifestPath, JSON.stringify(manifest, null, 2) + '\n');
+  console.log(chalk.green('  \u2714') + ` Written: ${manifestPath}`);
+
+  const readmePath = path.join(outDir, 'README.md');
+  await fs.writeFile(readmePath, generateReadme(manifest));
+  console.log(chalk.green('  \u2714') + ` Written: ${readmePath}`);
+
+  // Final validation
+  const finalCheck = validateSkillManifest(manifest);
+  if (finalCheck.valid) {
+    console.log(chalk.green('\n  \u2714 Manifest is valid!'));
+  } else {
+    console.log(chalk.yellow('\n  \u26A0 Manifest has issues:'));
+    for (const err of finalCheck.errors) console.log(chalk.red('    ' + err));
+  }
+  for (const warn of finalCheck.warnings) console.log(chalk.yellow('    \u26A0 ' + warn));
+
+  // ── Offer submission ──────────────────────────────
+
+  console.log('');
+  const { submit } = await inquirer.prompt([{
+    type: 'confirm',
+    name: 'submit',
+    message: 'Submit this skill as a PR to agenticmail/enterprise?',
+    default: false,
+  }]);
+
+  if (submit) {
+    const { runSubmitSkill } = await import('./cli-submit-skill.js');
+    await runSubmitSkill([outDir]);
+  } else {
+    console.log(chalk.dim('\n  To submit later: agenticmail-enterprise submit-skill ' + answers.outputDir));
+  }
+}
+
+// ─── Template Generator ──────────────────────────────
+
+function generateFromTemplate(
+  app: string, operations: string[], category: string, risk: string,
+  author: string, slug: string, prefix: string,
+) {
+  const tools = operations.map(op => {
+    const opSlug = op.toLowerCase().replace(/[^a-z0-9]+/g, '_').replace(/^_|_$/g, '');
+    const isRead = ['read', 'get', 'list', 'search', 'fetch', 'view', 'query'].some(r => opSlug.includes(r));
+    const isDelete = ['delete', 'remove', 'destroy'].some(r => opSlug.includes(r));
+    const toolCategory = isDelete ? 'destroy' : isRead ? 'read' : 'write';
+    const toolRisk = isDelete ? 'high' : isRead ? 'low' : 'medium';
+    const sideEffects: string[] = [];
+    if (!isRead) sideEffects.push('network-request');
+    if (isDelete) sideEffects.push('deletes-data');
+
+    return {
+      id: `${prefix}_${opSlug}`,
+      name: op.charAt(0).toUpperCase() + op.slice(1),
+      description: `${op.charAt(0).toUpperCase() + op.slice(1)} in ${app}`,
+      category: toolCategory,
+      riskLevel: toolRisk,
+      sideEffects,
+      parameters: {},
+    };
+  });
+
+  return {
+    id: slug,
+    name: app,
+    description: `Integrates with ${app} to ${operations.slice(0, 3).join(', ')}${operations.length > 3 ? ' and more' : ''}. Community-contributed skill for AgenticMail agents.`,
+    version: '1.0.0',
+    author,
+    repository: `https://github.com/${author}/${slug}`,
+    license: 'MIT',
+    category,
+    risk,
+    tags: [slug, category],
+    tools,
+    configSchema: {
+      apiKey: { type: 'secret', label: 'API Key', description: `Your ${app} API key`, required: true },
+    },
+    minEngineVersion: '0.3.0',
+    homepage: `https://github.com/${author}/${slug}`,
+  };
+}
+
+// ─── AI Prompt ────────────────────────────────────────
+
+function buildAIPrompt(
+  app: string, operations: string[], category: string, risk: string,
+  author: string, slug: string, prefix: string,
+): string {
+  return `Generate a valid agenticmail-skill.json manifest for "${app}".
+
+Requirements:
+- id: "${slug}"
+- name: "${app}"
+- Operations: ${operations.join(', ')}
+- category: "${category}"
+- risk: "${risk}"
+- author: "${author}"
+- repository: "https://github.com/${author}/${slug}"
+- license: "MIT"
+- Each tool needs: id (${prefix}_<action>), name, description, category (read/write/execute/communicate/destroy), riskLevel (low/medium/high/critical), sideEffects array
+- Valid sideEffects: sends-email, sends-message, sends-sms, posts-social, runs-code, modifies-files, deletes-data, network-request, controls-device, accesses-secrets, financial
+- Include a configSchema with any API keys or settings needed
+- version: "1.0.0"
+- minEngineVersion: "0.3.0"
+- description must be 20-500 chars
+
+Output ONLY the JSON object, no explanation.`;
+}
+
+// ─── README Generator ────────────────────────────────
+
+function generateReadme(manifest: any): string {
+  const tools = (manifest.tools || []).map((t: any) =>
+    `| \`${t.id}\` | ${t.name} | ${t.description} | ${t.riskLevel || 'medium'} |`
+  ).join('\n');
+
+  return `# ${manifest.name}
+
+${manifest.description}
+
+## Tools
+
+| ID | Name | Description | Risk |
+|----|------|-------------|------|
+${tools}
+
+## Configuration
+
+${manifest.configSchema ? Object.entries(manifest.configSchema).map(([k, v]: [string, any]) =>
+    `- **${k}** (${v.type || 'string'}): ${v.description || k}${v.required ? ' *(required)*' : ''}`
+  ).join('\n') : 'No configuration required.'}
+
+## Installation
+
+Install this skill from the AgenticMail Enterprise dashboard:
+
+1. Go to **Community Skills** in the sidebar
+2. Search for "${manifest.name}"
+3. Click **Install**
+
+Or via the API:
+\`\`\`bash
+curl -X POST /api/engine/community/skills/${manifest.id}/install \\
+  -H "Content-Type: application/json" \\
+  -d '{"orgId": "your-org-id"}'
+\`\`\`
+
+## License
+
+${manifest.license || 'MIT'}
+`;
+}

package/src/engine/cli-submit-skill.ts

@@ -0,0 +1,200 @@
+/**
+ * CLI: agenticmail-enterprise submit-skill <path>
+ *
+ * Automates the GitHub PR submission flow for a community skill.
+ * Uses the `gh` CLI to fork, branch, commit, push, and open a PR.
+ */
+
+import { validateSkillManifest } from './skill-validator.js';
+
+const UPSTREAM_REPO = 'agenticmail/enterprise';
+
+export async function runSubmitSkill(args: string[]) {
+  const chalk = (await import('chalk')).default;
+  const ora = (await import('ora')).default;
+  const { execSync } = await import('child_process');
+  const fs = await import('fs/promises');
+  const path = await import('path');
+
+  const target = args.filter(a => !a.startsWith('--'))[0];
+  if (!target) {
+    console.log(`${chalk.bold('Usage:')} agenticmail-enterprise submit-skill <path-to-skill-dir>`);
+    process.exit(1);
+    return;
+  }
+
+  const skillDir = path.resolve(target);
+
+  console.log('');
+  console.log(chalk.bold('\uD83D\uDE80 Submit Community Skill'));
+  console.log('');
+
+  // ── Step 1: Check gh CLI ──────────────────────────
+
+  const spinner = ora('Checking prerequisites...').start();
+  try {
+    execSync('gh --version', { stdio: 'pipe' });
+  } catch {
+    spinner.fail('GitHub CLI (gh) is not installed');
+    console.log('');
+    console.log(chalk.dim('  Install it from: https://cli.github.com/'));
+    console.log(chalk.dim('  Then run: gh auth login'));
+    process.exit(1);
+    return;
+  }
+
+  // Check gh auth
+  try {
+    execSync('gh auth status', { stdio: 'pipe' });
+  } catch {
+    spinner.fail('Not authenticated with GitHub CLI');
+    console.log(chalk.dim('  Run: gh auth login'));
+    process.exit(1);
+    return;
+  }
+  spinner.succeed('GitHub CLI authenticated');
+
+  // ── Step 2: Validate the skill ────────────────────
+
+  const validateSpinner = ora('Validating skill manifest...').start();
+  const manifestPath = path.join(skillDir, 'agenticmail-skill.json');
+
+  let manifest: any;
+  try {
+    const raw = await fs.readFile(manifestPath, 'utf-8');
+    manifest = JSON.parse(raw);
+  } catch (err: any) {
+    validateSpinner.fail(`Cannot read manifest: ${err.message}`);
+    process.exit(1);
+    return;
+  }
+
+  const validation = validateSkillManifest(manifest);
+  if (!validation.valid) {
+    validateSpinner.fail('Manifest validation failed');
+    for (const err of validation.errors) {
+      console.log(chalk.red('  \u2502 ' + err));
+    }
+    console.log(chalk.dim('\n  Fix the errors above and try again.'));
+    process.exit(1);
+    return;
+  }
+  validateSpinner.succeed(`Manifest valid: ${manifest.name} v${manifest.version}`);
+
+  const skillId = manifest.id;
+  const branchName = `community/add-${skillId}`;
+
+  // ── Step 3: Fork the repo ─────────────────────────
+
+  const forkSpinner = ora('Forking repository...').start();
+  try {
+    execSync(`gh repo fork ${UPSTREAM_REPO} --clone=false 2>&1 || true`, { stdio: 'pipe' });
+    forkSpinner.succeed('Repository forked (or already exists)');
+  } catch {
+    forkSpinner.succeed('Fork exists');
+  }
+
+  // Get the fork URL
+  let forkUrl: string;
+  try {
+    const ghUser = execSync('gh api user --jq .login', { encoding: 'utf-8' }).trim();
+    forkUrl = `https://github.com/${ghUser}/enterprise.git`;
+  } catch {
+    forkSpinner.fail('Cannot determine GitHub username');
+    process.exit(1);
+    return;
+  }
+
+  // ── Step 4: Clone, branch, copy, commit, push ─────
+
+  const tmpDir = path.join(process.env.TMPDIR || '/tmp', `agenticmail-submit-${Date.now()}`);
+  const pushSpinner = ora('Cloning fork...').start();
+
+  try {
+    execSync(`git clone --depth 1 ${forkUrl} "${tmpDir}"`, { stdio: 'pipe' });
+    pushSpinner.text = 'Creating branch...';
+
+    const run = (cmd: string) => execSync(cmd, { cwd: tmpDir, stdio: 'pipe', encoding: 'utf-8' });
+
+    // Add upstream remote and fetch
+    run(`git remote add upstream https://github.com/${UPSTREAM_REPO}.git`);
+    run('git fetch upstream main --depth 1');
+    run(`git checkout -b ${branchName} upstream/main`);
+
+    // Copy skill directory
+    pushSpinner.text = 'Copying skill files...';
+    const destDir = path.join(tmpDir, 'community-skills', skillId);
+    await fs.mkdir(destDir, { recursive: true });
+    const files = await fs.readdir(skillDir);
+    for (const file of files) {
+      await fs.copyFile(path.join(skillDir, file), path.join(destDir, file));
+    }
+
+    // Commit
+    pushSpinner.text = 'Committing...';
+    run(`git add community-skills/${skillId}/`);
+    run(`git commit -m "Add community skill: ${manifest.name}"`);
+
+    // Push
+    pushSpinner.text = 'Pushing to fork...';
+    run(`git push origin ${branchName} --force`);
+    pushSpinner.succeed('Pushed to fork');
+  } catch (err: any) {
+    pushSpinner.fail(`Git operation failed: ${err.message}`);
+    process.exit(1);
+    return;
+  }
+
+  // ── Step 5: Open PR ───────────────────────────────
+
+  const prSpinner = ora('Opening pull request...').start();
+
+  const toolsList = (manifest.tools || []).map((t: any) =>
+    `- \`${t.id}\` — ${t.name}: ${t.description}`
+  ).join('\n');
+
+  const prBody = `## Community Skill Submission
+
+**Skill ID:** \`${manifest.id}\`
+**Application:** ${manifest.name}
+**Category:** ${manifest.category}
+**Risk Level:** ${manifest.risk}
+**Author:** @${manifest.author}
+**License:** ${manifest.license}
+
+### Description
+
+${manifest.description}
+
+### Tools Provided
+
+${toolsList}
+
+### Validation
+
+- [x] Manifest passes \`agenticmail-enterprise validate\`
+- [x] All required fields present
+- [x] No duplicate tool IDs
+${manifest.tags ? `\n**Tags:** ${manifest.tags.join(', ')}` : ''}`;
+
+  try {
+    const prUrl = execSync(
+      `gh pr create --repo ${UPSTREAM_REPO} --head ${branchName} --title "Add community skill: ${manifest.name}" --body "${prBody.replace(/"/g, '\\"')}"`,
+      { cwd: tmpDir, encoding: 'utf-8', stdio: 'pipe' },
+    ).trim();
+    prSpinner.succeed('Pull request opened!');
+    console.log(chalk.green(`\n  ${prUrl}\n`));
+  } catch (err: any) {
+    // PR might already exist
+    if (err.stderr?.includes('already exists')) {
+      prSpinner.warn('A PR for this skill already exists');
+    } else {
+      prSpinner.fail(`Could not open PR: ${err.message}`);
+    }
+  }
+
+  // Cleanup
+  try {
+    await fs.rm(tmpDir, { recursive: true, force: true });
+  } catch { /* ignore */ }
+}

package/src/engine/cli-validate.ts

@@ -0,0 +1,188 @@
+/**
+ * CLI: agenticmail-enterprise validate <path>
+ *
+ * Validates an agenticmail-skill.json manifest against the full spec.
+ * Checks for duplicate tool IDs against the builtin catalog and
+ * other community skills.
+ *
+ * Flags:
+ *   --all   Validate all skills in community-skills/
+ *   --json  Machine-readable JSON output (for CI)
+ */
+
+import { validateSkillManifest, collectCommunityToolIds } from './skill-validator.js';
+import { ALL_TOOLS } from './tool-catalog.js';
+
+interface ValidationReport {
+  path: string;
+  skillId: string;
+  valid: boolean;
+  errors: string[];
+  warnings: string[];
+}
+
+export async function runValidate(args: string[]) {
+  const chalk = (await import('chalk')).default;
+  const fs = await import('fs/promises');
+  const path = await import('path');
+
+  const jsonMode = args.includes('--json');
+  const allMode = args.includes('--all');
+  const pathArgs = args.filter(a => !a.startsWith('--'));
+
+  // Build the set of builtin tool IDs
+  const builtinIds = new Set(ALL_TOOLS.map(t => t.id));
+
+  // Resolve community-skills/ directory
+  const communityDir = path.resolve(process.cwd(), 'community-skills');
+
+  const reports: ValidationReport[] = [];
+
+  if (allMode) {
+    // Validate all skills in community-skills/
+    let entries: import('fs').Dirent[];
+    try {
+      entries = await fs.readdir(communityDir, { withFileTypes: true });
+    } catch {
+      if (jsonMode) {
+        console.log(JSON.stringify({ error: 'community-skills/ directory not found' }));
+      } else {
+        console.error(chalk.red('Error: community-skills/ directory not found'));
+      }
+      process.exit(1);
+      return;
+    }
+
+    for (const entry of entries) {
+      if (!entry.isDirectory() || entry.name.startsWith('_') || entry.name.startsWith('.')) continue;
+      const skillDir = path.join(communityDir, entry.name);
+      const report = await validatePath(skillDir, builtinIds, communityDir);
+      reports.push(report);
+    }
+  } else {
+    // Validate specific path(s)
+    const target = pathArgs[0];
+    if (!target) {
+      if (jsonMode) {
+        console.log(JSON.stringify({ error: 'No path specified. Usage: agenticmail-enterprise validate <path> [--all] [--json]' }));
+      } else {
+        console.log(`${chalk.bold('Usage:')} agenticmail-enterprise validate <path>`);
+        console.log('');
+        console.log('  <path>    Path to a skill directory or agenticmail-skill.json file');
+        console.log('  --all     Validate all skills in community-skills/');
+        console.log('  --json    Machine-readable JSON output');
+      }
+      process.exit(1);
+      return;
+    }
+
+    const report = await validatePath(path.resolve(target), builtinIds, communityDir);
+    reports.push(report);
+  }
+
+  // Output results
+  if (jsonMode) {
+    console.log(JSON.stringify({ results: reports, totalErrors: reports.reduce((s, r) => s + r.errors.length, 0) }, null, 2));
+  } else {
+    console.log('');
+    for (const report of reports) {
+      if (report.valid) {
+        console.log(chalk.green('  \u2714') + ' ' + chalk.bold(report.skillId) + chalk.dim(` (${report.path})`));
+      } else {
+        console.log(chalk.red('  \u2718') + ' ' + chalk.bold(report.skillId) + chalk.dim(` (${report.path})`));
+        for (const err of report.errors) {
+          console.log(chalk.red('    \u2502 ') + err);
+        }
+      }
+      for (const warn of report.warnings) {
+        console.log(chalk.yellow('    \u26A0 ') + warn);
+      }
+    }
+
+    console.log('');
+    const passed = reports.filter(r => r.valid).length;
+    const failed = reports.filter(r => !r.valid).length;
+    if (failed > 0) {
+      console.log(chalk.red(`  ${failed} failed`) + chalk.dim(`, ${passed} passed, ${reports.length} total`));
+    } else {
+      console.log(chalk.green(`  ${passed} passed`) + chalk.dim(`, ${reports.length} total`));
+    }
+    console.log('');
+  }
+
+  // Exit with error code if any failed
+  if (reports.some(r => !r.valid)) {
+    process.exit(1);
+  }
+}
+
+async function validatePath(
+  targetPath: string,
+  builtinIds: Set<string>,
+  communityDir: string,
+): Promise<ValidationReport> {
+  const fs = await import('fs/promises');
+  const path = await import('path');
+
+  let manifestPath: string;
+
+  // Determine if path is a directory or a JSON file
+  try {
+    const stat = await fs.stat(targetPath);
+    if (stat.isDirectory()) {
+      manifestPath = path.join(targetPath, 'agenticmail-skill.json');
+    } else {
+      manifestPath = targetPath;
+    }
+  } catch {
+    return {
+      path: targetPath,
+      skillId: path.basename(targetPath),
+      valid: false,
+      errors: [`Path not found: ${targetPath}`],
+      warnings: [],
+    };
+  }
+
+  // Read and parse
+  let raw: string;
+  try {
+    raw = await fs.readFile(manifestPath, 'utf-8');
+  } catch {
+    return {
+      path: manifestPath,
+      skillId: path.basename(path.dirname(manifestPath)),
+      valid: false,
+      errors: [`Cannot read: ${manifestPath}`],
+      warnings: [],
+    };
+  }
+
+  let manifest: any;
+  try {
+    manifest = JSON.parse(raw);
+  } catch (err: any) {
+    return {
+      path: manifestPath,
+      skillId: path.basename(path.dirname(manifestPath)),
+      valid: false,
+      errors: [`Invalid JSON: ${err.message}`],
+      warnings: [],
+    };
+  }
+
+  // Collect community tool IDs (excluding self)
+  const communityIds = await collectCommunityToolIds(communityDir, manifest.id);
+  const allExistingIds = new Set([...builtinIds, ...communityIds]);
+
+  // Validate
+  const result = validateSkillManifest(manifest, { existingToolIds: allExistingIds });
+
+  return {
+    path: manifestPath,
+    skillId: manifest.id || path.basename(path.dirname(manifestPath)),
+    valid: result.valid,
+    errors: result.errors,
+    warnings: result.warnings,
+  };
+}