@agenticmail/enterprise 0.3.2 → 0.4.0

package/.github/CODEOWNERS

@@ -0,0 +1,23 @@
+# ─── AgenticMail Enterprise Code Owners ───────────────
+#
+# These owners are automatically requested for review
+# when a PR touches matching paths.
+#
+# IMPORTANT: Enable "Require review from Code Owners" in
+# GitHub repo Settings → Branches → Branch protection rules
+# for the `main` branch to enforce this.
+
+# Core engine — requires core team review
+src/engine/     @agenticmail/core-team
+src/server.ts   @agenticmail/core-team
+src/auth/       @agenticmail/core-team
+src/admin/      @agenticmail/core-team
+
+# Community skills — ALL submissions require maintainer review
+# No community skill can be merged without explicit approval
+community-skills/   @agenticmail/skill-reviewers
+
+# CI/CD and repo config — requires admin review
+.github/        @agenticmail/core-team
+CLAUDE.md       @agenticmail/core-team
+package.json    @agenticmail/core-team

package/.github/workflows/publish-community-skills.yml

@@ -0,0 +1,121 @@
+name: Publish Community Skills
+
+# IMPORTANT: This workflow only runs AFTER code is merged into main.
+# It does NOT auto-approve or auto-merge PRs.
+# All community skill PRs must be reviewed and approved by a maintainer
+# (enforced by CODEOWNERS + branch protection rules) before this runs.
+#
+# After a maintainer-approved merge:
+# 1. Rebuilds community-skills/index.json (the registry index deployed instances fetch)
+# 2. Optionally pushes each skill to a live registry API
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'community-skills/**'
+
+permissions:
+  contents: write
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 2
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      # ── Generate index.json ─────────────────────────
+      # This is the file that deployed instances fetch to discover new skills.
+      # Every community-skills/<id>/agenticmail-skill.json gets listed here.
+
+      - name: Generate community-skills/index.json
+        run: |
+          node -e "
+            const fs = require('fs');
+            const path = require('path');
+            const dir = 'community-skills';
+            const skills = [];
+
+            for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+              if (!entry.isDirectory() || entry.name.startsWith('_') || entry.name.startsWith('.')) continue;
+              const manifestPath = path.join(dir, entry.name, 'agenticmail-skill.json');
+              try {
+                const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf-8'));
+                skills.push({
+                  id: manifest.id,
+                  name: manifest.name,
+                  version: manifest.version,
+                  author: manifest.author,
+                  category: manifest.category,
+                  risk: manifest.risk,
+                  description: manifest.description,
+                });
+              } catch (err) {
+                console.error('Skipping ' + entry.name + ': ' + err.message);
+              }
+            }
+
+            const index = {
+              generatedAt: new Date().toISOString(),
+              count: skills.length,
+              skills,
+            };
+
+            fs.writeFileSync(path.join(dir, 'index.json'), JSON.stringify(index, null, 2) + '\n');
+            console.log('Generated index.json with ' + skills.length + ' skills');
+          "
+
+      - name: Commit index.json
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git add community-skills/index.json
+          git diff --cached --quiet && echo "No changes to index.json" && exit 0
+          git commit -m "chore: update community-skills index [skip ci]"
+          git push
+
+      # ── Publish to live registry (optional) ─────────
+      # If ENTERPRISE_REGISTRY_URL is configured, also push directly to a live server.
+
+      - name: Find changed skill directories
+        id: changed
+        run: |
+          CHANGED=$(git diff --name-only HEAD~1 HEAD -- community-skills/ || true)
+          DIRS=$(echo "$CHANGED" | grep -oP 'community-skills/[^/]+' | sort -u | grep -v '_template' || true)
+          echo "dirs<<EOF" >> $GITHUB_OUTPUT
+          echo "$DIRS" >> $GITHUB_OUTPUT
+          echo "EOF" >> $GITHUB_OUTPUT
+          COUNT=$(echo "$DIRS" | grep -c '.' || echo "0")
+          echo "count=$COUNT" >> $GITHUB_OUTPUT
+
+      - name: Publish to live registry
+        if: steps.changed.outputs.count != '0' && env.REGISTRY_URL != ''
+        env:
+          REGISTRY_URL: ${{ secrets.ENTERPRISE_REGISTRY_URL }}
+          REGISTRY_TOKEN: ${{ secrets.ENTERPRISE_API_KEY }}
+        run: |
+          while IFS= read -r dir; do
+            [ -z "$dir" ] && continue
+            SKILL_ID=$(basename "$dir")
+            MANIFEST="$dir/agenticmail-skill.json"
+            [ ! -f "$MANIFEST" ] && continue
+
+            echo "Publishing $SKILL_ID..."
+            HTTP_CODE=$(curl -s -o /tmp/response.json -w "%{http_code}" \
+              -X POST "${REGISTRY_URL}/api/engine/community/skills/publish" \
+              -H "Content-Type: application/json" \
+              -H "Authorization: Bearer ${REGISTRY_TOKEN}" \
+              -d @"$MANIFEST")
+
+            if [ "$HTTP_CODE" -ge 200 ] && [ "$HTTP_CODE" -lt 300 ]; then
+              echo "Published $SKILL_ID (HTTP $HTTP_CODE)"
+            else
+              echo "::warning::Failed to publish $SKILL_ID (HTTP $HTTP_CODE)"
+            fi
+          done <<< "${{ steps.changed.outputs.dirs }}"

package/.github/workflows/validate-community-skills.yml

@@ -0,0 +1,172 @@
+name: Validate Community Skills
+
+on:
+  pull_request:
+    paths:
+      - 'community-skills/**'
+    types: [opened, synchronize, reopened]
+
+permissions:
+  contents: read
+  pull-requests: write
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'npm'
+
+      - run: npm ci
+
+      - run: npm run build
+
+      - name: Find changed skill directories
+        id: changed
+        run: |
+          CHANGED=$(git diff --name-only ${{ github.event.pull_request.base.sha }} HEAD -- community-skills/ || true)
+          DIRS=$(echo "$CHANGED" | grep -oP 'community-skills/[^/]+' | sort -u | grep -v '_template' || true)
+          echo "dirs<<EOF" >> $GITHUB_OUTPUT
+          echo "$DIRS" >> $GITHUB_OUTPUT
+          echo "EOF" >> $GITHUB_OUTPUT
+          COUNT=$(echo "$DIRS" | grep -c '.' || echo "0")
+          echo "count=$COUNT" >> $GITHUB_OUTPUT
+
+      - name: Validate each skill
+        id: validate
+        if: steps.changed.outputs.count != '0'
+        run: |
+          FAILED=0
+          RESULTS=""
+          while IFS= read -r dir; do
+            [ -z "$dir" ] && continue
+            SKILL_ID=$(basename "$dir")
+            echo "::group::Validating $SKILL_ID"
+            if [ -f "$dir/agenticmail-skill.json" ]; then
+              OUTPUT=$(node dist/cli.js validate "$dir" --json 2>&1)
+              echo "$OUTPUT"
+              VALID=$(echo "$OUTPUT" | node -e "const d=require('fs').readFileSync('/dev/stdin','utf-8'); try{const j=JSON.parse(d); console.log(j.results?.[0]?.valid ? 'true':'false')}catch{console.log('false')}")
+              if [ "$VALID" = "true" ]; then
+                RESULTS="${RESULTS}| \`${SKILL_ID}\` | ✅ Passed | — |\n"
+              else
+                ERRORS=$(echo "$OUTPUT" | node -e "const d=require('fs').readFileSync('/dev/stdin','utf-8'); try{const j=JSON.parse(d); console.log((j.results?.[0]?.errors||[]).join(', '))}catch{console.log('parse error')}")
+                RESULTS="${RESULTS}| \`${SKILL_ID}\` | ❌ Failed | ${ERRORS} |\n"
+                FAILED=1
+              fi
+            else
+              echo "::error::Missing agenticmail-skill.json in $dir"
+              RESULTS="${RESULTS}| \`${SKILL_ID}\` | ❌ Failed | Missing agenticmail-skill.json |\n"
+              FAILED=1
+            fi
+            echo "::endgroup::"
+          done <<< "${{ steps.changed.outputs.dirs }}"
+          echo "results<<EOF" >> $GITHUB_OUTPUT
+          echo -e "$RESULTS" >> $GITHUB_OUTPUT
+          echo "EOF" >> $GITHUB_OUTPUT
+          echo "failed=$FAILED" >> $GITHUB_OUTPUT
+          exit $FAILED
+
+      - name: Check for README
+        if: steps.changed.outputs.count != '0'
+        id: readme
+        run: |
+          MISSING=""
+          while IFS= read -r dir; do
+            [ -z "$dir" ] && continue
+            if [ ! -f "$dir/README.md" ]; then
+              MISSING="${MISSING}$(basename $dir), "
+            fi
+          done <<< "${{ steps.changed.outputs.dirs }}"
+          echo "missing=$MISSING" >> $GITHUB_OUTPUT
+
+      - name: Label PR
+        if: always() && steps.changed.outputs.count != '0'
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const labels = ['community-skill', 'needs-maintainer-review'];
+            if ('${{ steps.validate.outputs.failed }}' === '0') {
+              labels.push('validated');
+            } else {
+              labels.push('validation-failed');
+            }
+            await github.rest.issues.addLabels({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              issue_number: context.issue.number,
+              labels,
+            });
+
+      - name: Post review checklist
+        if: always() && steps.changed.outputs.count != '0'
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const passed = '${{ steps.validate.outputs.failed }}' === '0';
+            const validationStatus = passed ? '✅ All checks passed' : '❌ Validation failed — see errors below';
+            const missingReadme = '${{ steps.readme.outputs.missing }}'.trim();
+
+            const body = `### Community Skill Review
+
+            **Automated Validation:** ${validationStatus}
+            **Skills checked:** ${{ steps.changed.outputs.count }}
+
+            #### Validation Results
+
+            | Skill | Status | Errors |
+            |-------|--------|--------|
+            ${{ steps.validate.outputs.results }}
+
+            ${missingReadme ? `⚠️ **Missing README.md:** ${missingReadme}\n` : ''}
+
+            ---
+
+            #### Maintainer Review Checklist
+
+            > **This PR requires manual review from a maintainer before merging.**
+            > Automated validation only checks the manifest format — a human must
+            > review the actual skill design, tool definitions, and risk assessment.
+
+            - [ ] **Tool IDs are sensibly named** and follow the \`prefix_action\` convention
+            - [ ] **Descriptions are accurate** and clearly explain what each tool does
+            - [ ] **Risk levels are appropriate** — destructive tools should be \`high\`/\`critical\`
+            - [ ] **Side effects are correctly declared** (sends-email, deletes-data, etc.)
+            - [ ] **Category is correct** for the application type
+            - [ ] **No malicious or deceptive tool definitions** hiding behind legitimate names
+            - [ ] **Config schema is reasonable** — no unnecessary secrets or permissions
+            - [ ] **README documents** all tools, configuration, and usage
+            - [ ] **License is appropriate** for community contribution
+
+            ---
+            *Automated by [AgenticMail Enterprise CI](https://github.com/agenticmail/enterprise) — maintainer approval required to merge*`;
+
+            const comments = await github.rest.issues.listComments({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              issue_number: context.issue.number,
+            });
+            const existing = comments.data.find(c =>
+              c.body?.includes('Community Skill Review') && c.user?.type === 'Bot'
+            );
+
+            if (existing) {
+              await github.rest.issues.updateComment({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                comment_id: existing.id,
+                body,
+              });
+            } else {
+              await github.rest.issues.createComment({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                issue_number: context.issue.number,
+                body,
+              });
+            }