check-plugin-structure.yml

name: Check Plugin Structure

on:
  pull_request:
    branches: [staged]
    paths:
      - "plugins/**"

permissions:
  contents: read
  pull-requests: write

jobs:
  check-materialized-files:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1

      - name: Check for materialized files in plugin directories
        uses: actions/github-script@f28e40c7f34bde8b3046d885e986cb6290c5673b # v7.1.0
        with:
          script: |
            const { execSync } = require('child_process');
            const fs = require('fs');
            const path = require('path');

            const pluginsDir = 'plugins';
            const errors = [];

            if (!fs.existsSync(pluginsDir)) {
              console.log('No plugins directory found');
              return;
            }

            const pluginDirs = fs.readdirSync(pluginsDir, { withFileTypes: true })
              .filter(d => d.isDirectory())
              .map(d => d.name);

            for (const plugin of pluginDirs) {
              const pluginPath = path.join(pluginsDir, plugin);

              // Check for materialized agent/command/skill files
              for (const subdir of ['agents', 'commands', 'skills']) {
                const subdirPath = path.join(pluginPath, subdir);
                if (!fs.existsSync(subdirPath)) continue;

                const stat = fs.lstatSync(subdirPath);
                if (stat.isSymbolicLink()) {
                  errors.push(`${pluginPath}/${subdir} is a symlink — symlinks should not exist in plugin directories`);
                  continue;
                }

                if (stat.isDirectory()) {
                  const files = fs.readdirSync(subdirPath);
                  if (files.length > 0) {
                    errors.push(
                      `${pluginPath}/${subdir}/ contains ${files.length} file(s): ${files.join(', ')}. ` +
                      `Plugin directories on staged should only contain .github/plugin/plugin.json and README.md. ` +
                      `Agent, command, and skill files are materialized automatically during publish to main.`
                    );
                  }
                }
              }

              // Check for symlinks anywhere in the plugin directory
              try {
                const allFiles = execSync(`find "${pluginPath}" -type l`, { encoding: 'utf-8' }).trim();
                if (allFiles) {
                  errors.push(`${pluginPath} contains symlinks:\n${allFiles}`);
                }
              } catch (e) {
                // find returns non-zero if no matches, ignore
              }
            }

            if (errors.length > 0) {
              const prBranch = context.payload.pull_request.head.ref;
              const prRepo = context.payload.pull_request.head.repo.full_name;
              const isFork = context.payload.pull_request.head.repo.fork;

              const body = [
                '⚠️ **Materialized files or symlinks detected in plugin directories**',
                '',
                'Plugin directories on the `staged` branch should only contain:',
                '- `.github/plugin/plugin.json` (metadata)',
                '- `README.md`',
                '',
                'Agent, command, and skill files are copied in automatically when publishing to `main`.',
                '',
                '**Issues found:**',
                ...errors.map(e => `- ${e}`),
                '',
                '---',
                '',
                '### How to fix',
                '',
                'It looks like your branch may be based on `main` (which contains materialized files). Here are two options:',
                '',
                '**Option 1: Rebase onto `staged`** (recommended if you have few commits)',
                '```bash',
                `git fetch origin staged`,
                `git rebase --onto origin/staged origin/main ${prBranch}`,
                `git push --force-with-lease`,
                '```',
                '',
                '**Option 2: Remove the extra files manually**',
                '```bash',
                '# Remove materialized files from plugin directories',
                'find plugins/ -mindepth 2 -maxdepth 2 -type d \\( -name agents -o -name commands -o -name skills \\) -exec rm -rf {} +',
                '# Remove any symlinks',
                'find plugins/ -type l -delete',
                'git add -A && git commit -m "fix: remove materialized plugin files"',
                'git push',
                '```',
              ].join('\n');

              await github.rest.pulls.createReview({
                owner: context.repo.owner,
                repo: context.repo.repo,
                pull_number: context.issue.number,
                event: 'REQUEST_CHANGES',
                body
              });

              core.setFailed('Plugin directories contain materialized files or symlinks that should not be on staged');
            } else {
              console.log('✅ All plugin directories are clean');
            }