Merge branch 'staged' into feat/md-to-docx-plus-equation-support

Author: George-Chia

.github/ISSUE_TEMPLATE/external-plugin.yml

@@ -14,7 +14,7 @@ body:
         Before you continue:
         - Public submissions are **GitHub-only** in v1.
         - The plugin must live in a **public GitHub repository**.
-        - Use an **immutable ref** for review: a release tag or full 40-character commit SHA.
+        - Provide an immutable **ref**, **sha**, or both for review.
         - Do **not** open a PR that edits `plugins/external.json` directly.
   - type: input
     id: plugin-name
@@ -51,11 +51,19 @@ body:
   - type: input
     id: immutable-ref
     attributes:
-      label: Immutable ref to review
-      description: Release tag or full 40-character commit SHA.
-      placeholder: refs/tags/v1.2.3 or 0123456789abcdef0123456789abcdef01234567
+      label: Ref to review
+      description: Optional release tag or tag ref. Submit this, a commit SHA, or both.
+      placeholder: v1.2.3
     validations:
-      required: true
+      required: false
+  - type: input
+    id: immutable-sha
+    attributes:
+      label: Commit SHA to review
+      description: Optional full 40-character commit SHA. Submit this, a ref, or both.
+      placeholder: 0123456789abcdef0123456789abcdef01234567
+    validations:
+      required: false
   - type: input
     id: version
     attributes:
@@ -119,7 +127,7 @@ body:
       options:
         - label: The plugin lives in a public GitHub repository.
           required: true
-        - label: The ref I provided is an immutable release tag or full 40-character commit SHA, not a branch.
+        - label: The ref and/or sha I provided is immutable (release tag and/or full 40-character commit SHA), not a branch.
           required: true
         - label: This submission follows this repository's contribution, security, and responsible AI policies.
           required: true

.github/workflows/external-plugin-approval-command.yml

@@ -118,7 +118,7 @@ jobs:
               '',
               '### Required fixes',
               '',
-              ...(errors.length > 0 ? errors.map((error) => `- ${error}`) : ['- Re-run intake validation by updating the issue details.'])
+              ...(errors.length > 0 ? errors.map((error) => `- ${error}`) : ['- Edit the issue details and let intake rerun automatically, or comment `/rerun-intake` to trigger it again on demand.'])
             ].join('\n');
 
             const { data: comments } = await github.rest.issues.listComments({
@@ -493,7 +493,7 @@ jobs:
               '',
               reason,
               '',
-              'If you address the feedback, open a new external plugin submission issue with the updated details.'
+              'If you address the feedback, edit this issue with the updated details and have the issue author or a maintainer comment `/rerun-intake` to re-run automated intake.'
             ].join('\n');
 
             const { data: comments } = await github.rest.issues.listComments({

.github/workflows/external-plugin-intake.yml

@@ -4,6 +4,10 @@ on:
   issues:
     types: [opened, edited, reopened]
 
+concurrency:
+  group: external-plugin-intake-${{ github.event.issue.number }}
+  cancel-in-progress: true
+
 permissions:
   contents: read
   issues: write
@@ -36,81 +40,10 @@ jobs:
           RESULT_JSON: ${{ steps.evaluation.outputs.result }}
         with:
           script: |
-            const managedLabels = {
-              'external-plugin': {
-                color: 'FEF2C0',
-                description: 'Public external plugin submission'
-              },
-              'awaiting-review': {
-                color: 'FBCA04',
-                description: 'Submission is waiting for automated intake validation'
-              },
-              'ready-for-review': {
-                color: '0E8A16',
-                description: 'Submission passed intake validation and is ready for maintainer review'
-              },
-              'approved': {
-                color: '1D76DB',
-                description: 'Submission was approved by a maintainer'
-              },
-              'rejected': {
-                color: 'B60205',
-                description: 'Submission was rejected or failed intake validation'
-              }
-            };
-
-            async function ensureLabel(name, config) {
-              try {
-                await github.rest.issues.createLabel({
-                  owner: context.repo.owner,
-                  repo: context.repo.repo,
-                  name,
-                  color: config.color,
-                  description: config.description
-                });
-              } catch (error) {
-                if (error.status !== 422) {
-                  throw error;
-                }
-              }
-            }
-
-            async function syncManagedLabels(issueNumber, desiredLabels) {
-              await Promise.all(Object.entries(managedLabels).map(([name, config]) => ensureLabel(name, config)));
+            const path = require('path');
+            const { pathToFileURL } = require('url');
 
-              const managedForSync = ['external-plugin', 'awaiting-review', 'ready-for-review', 'rejected'];
-              const currentLabels = await github.paginate(github.rest.issues.listLabelsOnIssue, {
-                owner: context.repo.owner,
-                repo: context.repo.repo,
-                issue_number: issueNumber,
-                per_page: 100
-              });
-
-              const currentManagedLabels = currentLabels
-                .map((label) => label.name)
-                .filter((name) => managedForSync.includes(name));
-
-              const labelsToAdd = [...desiredLabels].filter((name) => !currentManagedLabels.includes(name));
-              const labelsToRemove = currentManagedLabels.filter((name) => !desiredLabels.has(name));
-
-              if (labelsToAdd.length > 0) {
-                await github.rest.issues.addLabels({
-                  owner: context.repo.owner,
-                  repo: context.repo.repo,
-                  issue_number: issueNumber,
-                  labels: labelsToAdd
-                });
-              }
-
-              for (const name of labelsToRemove) {
-                await github.rest.issues.removeLabel({
-                  owner: context.repo.owner,
-                  repo: context.repo.repo,
-                  issue_number: issueNumber,
-                  name
-                });
-              }
-            }
+            const intakeState = await import(pathToFileURL(path.join(process.env.GITHUB_WORKSPACE, 'eng', 'external-plugin-intake-state.mjs')).href);
 
             const result = JSON.parse(process.env.RESULT_JSON);
             const issueNumber = context.issue.number;
@@ -128,40 +61,14 @@ jobs:
               return;
             }
 
-            const desiredLabels = result.valid
-              ? new Set(['external-plugin', 'ready-for-review'])
-              : new Set(['external-plugin', 'rejected']);
-
-            await syncManagedLabels(issueNumber, desiredLabels);
-
-            const { data: comments } = await github.rest.issues.listComments({
+            await intakeState.applyExternalPluginIntakeEvaluation({
+              github,
               owner: context.repo.owner,
               repo: context.repo.repo,
-              issue_number: issueNumber,
-              per_page: 100
+              issueNumber,
+              evaluation: result
             });
 
-            const existingComment = comments.find((comment) =>
-              comment.user?.login === 'github-actions[bot]' &&
-              comment.body?.includes(result.commentMarker)
-            );
-
-            if (existingComment) {
-              await github.rest.issues.updateComment({
-                owner: context.repo.owner,
-                repo: context.repo.repo,
-                comment_id: existingComment.id,
-                body: result.commentBody
-              });
-            } else {
-              await github.rest.issues.createComment({
-                owner: context.repo.owner,
-                repo: context.repo.repo,
-                issue_number: issueNumber,
-                body: result.commentBody
-              });
-            }
-
             if (!result.valid && issueState === 'open') {
               await github.rest.issues.update({
                 owner: context.repo.owner,

.github/workflows/external-plugin-rerun-intake-command.yml

@@ -0,0 +1,124 @@
+name: External Plugin Rerun Intake Commands
+
+on:
+  issue_comment:
+    types: [created]
+
+concurrency:
+  group: external-plugin-intake-${{ github.event.issue.number }}
+  cancel-in-progress: false
+
+permissions:
+  contents: read
+  issues: write
+
+jobs:
+  handle-command:
+    runs-on: ubuntu-latest
+    if: >-
+      !github.event.issue.pull_request &&
+      startsWith(github.event.comment.body, '/rerun-intake')
+    steps:
+      - name: Checkout staged branch
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
+        with:
+          ref: staged
+
+      - name: Re-run external plugin intake
+        uses: actions/github-script@f28e40c7f34bde8b3046d885e986cb6290c5673b # v7.1.0
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        with:
+          script: |
+            const path = require('path');
+            const { pathToFileURL } = require('url');
+
+            const intake = await import(pathToFileURL(path.join(process.env.GITHUB_WORKSPACE, 'eng', 'external-plugin-intake.mjs')).href);
+            const intakeState = await import(pathToFileURL(path.join(process.env.GITHUB_WORKSPACE, 'eng', 'external-plugin-intake-state.mjs')).href);
+
+            const commentAuthor = context.payload.comment.user?.login;
+            if (!commentAuthor || context.payload.comment.user?.type === 'Bot' || commentAuthor === 'github-actions[bot]') {
+              core.info('Ignoring /rerun-intake from a bot or unknown actor.');
+              return;
+            }
+
+            if (!intake.parseRerunIntakeCommand(context.payload.comment.body)) {
+              core.info('No supported /rerun-intake command was found.');
+              return;
+            }
+
+            const { data: currentIssue } = await github.rest.issues.get({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              issue_number: context.issue.number
+            });
+
+            const labelNames = new Set((currentIssue.labels || []).map((label) => label.name));
+            const isExternalPluginIssue =
+              labelNames.has('external-plugin') ||
+              String(currentIssue.body || '').includes(intake.ISSUE_FORM_MARKER);
+            if (!isExternalPluginIssue) {
+              core.info('Ignoring /rerun-intake because the issue is not an external plugin submission.');
+              return;
+            }
+
+            if (labelNames.has('approved') || labelNames.has('re-review-due') || labelNames.has('re-review-follow-up')) {
+              core.info('Ignoring /rerun-intake because the issue is already approved or in the six-month re-review flow.');
+              return;
+            }
+
+            const issueAuthor = currentIssue.user?.login;
+            const isIssueAuthor = Boolean(issueAuthor && commentAuthor === issueAuthor);
+
+            let hasWriteAccess = false;
+            if (!isIssueAuthor) {
+              const permission = await github.rest.repos.getCollaboratorPermissionLevel({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                username: commentAuthor
+              });
+              hasWriteAccess = ['admin', 'write', 'maintain'].includes(permission.data.permission);
+            }
+
+            if (!isIssueAuthor && !hasWriteAccess) {
+              core.info(`Ignoring /rerun-intake because ${commentAuthor} is neither the issue author nor a maintainer.`);
+              return;
+            }
+
+            const canRerunFromCurrentState = currentIssue.state === 'open' || labelNames.has('rejected');
+            if (!canRerunFromCurrentState) {
+              core.info('Ignoring /rerun-intake because the issue is closed outside the intake/rejection flow.');
+              return;
+            }
+
+            const evaluation = await intake.evaluateExternalPluginIssue({
+              issue: currentIssue,
+              token: process.env.GITHUB_TOKEN
+            });
+
+            await intakeState.applyExternalPluginIntakeEvaluation({
+              github,
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              issueNumber: context.issue.number,
+              evaluation
+            });
+
+            if (evaluation.valid && currentIssue.state === 'closed' && labelNames.has('rejected')) {
+              await github.rest.issues.update({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                issue_number: context.issue.number,
+                state: 'open'
+              });
+              return;
+            }
+
+            if (!evaluation.valid && currentIssue.state === 'open') {
+              await github.rest.issues.update({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                issue_number: context.issue.number,
+                state: 'closed'
+              });
+            }

AGENTS.md

@@ -164,13 +164,14 @@ When adding a new agent, instruction, skill, hook, workflow, or plugin:
 
 1. Do not open a direct PR that edits `plugins/external.json` for a public third-party plugin submission
 2. Public external plugin submissions use the external plugin issue workflow documented in [CONTRIBUTING.md](CONTRIBUTING.md#adding-external-plugins)
-3. In v1, only GitHub-hosted plugins are accepted for public submission, using a public repo plus an immutable `ref`
+3. In v1, only GitHub-hosted plugins are accepted for public submission, using a public repo plus an immutable `ref`, `sha`, or both
 4. The shared validator in `eng/external-plugin-validation.mjs` is the canonical source of truth for external plugin data rules; reuse it instead of duplicating checks in scripts or workflows
 5. Submission issues move through `external-plugin` + `awaiting-review` -> `ready-for-review` -> `approved` or `rejected`
-6. Maintainers make the decision with `/approve` or `/reject <reason>` issue comments; approved issues are closed and used as the six-month re-review anchor
-7. Approval automation creates or updates the PR against `staged`, updates `plugins/external.json`, and regenerates marketplace outputs
-8. Nightly re-review automation finds closed `external-plugin` + `approved` issues that are at least six months old, applies `re-review-due`, and opens or updates a tracking issue for maintainers
-9. Maintainers complete re-review on the original approved submission issue with `/re-review-keep`, `/re-review-needs-changes`, or `/re-review-remove`; keep resets the issue `closed_at`, and remove opens a PR against `staged`
+6. After issue edits, the issue author or a maintainer can comment `/rerun-intake` to re-run automated intake without opening a new submission issue
+7. Maintainers make the decision with `/approve` or `/reject <reason>` issue comments; approved issues are closed and used as the six-month re-review anchor
+8. Approval automation creates or updates the PR against `staged`, updates `plugins/external.json`, and regenerates marketplace outputs
+9. Nightly re-review automation finds closed `external-plugin` + `approved` issues that are at least six months old, applies `re-review-due`, and opens or updates a tracking issue for maintainers
+10. Maintainers complete re-review on the original approved submission issue with `/re-review-keep`, `/re-review-needs-changes`, or `/re-review-remove`; keep resets the issue `closed_at`, and remove opens a PR against `staged`
 
 ### Testing Instructions