learningcircuit--local-deep-research/.github/workflows/welcome-first-time.yml

name: Welcome first-time contributors

# Posts a single welcome comment on a contributor's FIRST PR (filtered per
# user). Uses pull_request_target so forked PRs receive a writable token;
# the script reads only sender.login (operator-trusted via GitHub) and
# never executes fork-controlled content — no checkout, no shell.
#
# We do NOT use actions/first-interaction: its isFirstPullRequest check
# has no author filter (lists all repo PRs and matches only on the lowest
# PR number), so it would never fire on a repo with prior history.

on:
  # zizmor: ignore[dangerous-triggers] — pull_request_target is required so
  # fork PRs receive a writable token to post the welcome comment. The job
  # never checks out PR content, never runs fork-controlled scripts, and
  # only reads `sender.login` (operator-trusted GitHub event metadata). The
  # comment body is a static template with no PR-controlled interpolation.
  pull_request_target:
    types: [opened]

permissions: {}  # Minimal top-level for OSSF Scorecard Token-Permissions

jobs:
  welcome:
    runs-on: ubuntu-latest
    timeout-minutes: 5
    permissions:
      # createComment on a PR returns 403 with only `issues: write` —
      # GitHub requires `pull-requests: write` when the issue resource
      # is actually a PR (Accepted-Permissions header lists both).
      issues: write
      pull-requests: write
    steps:
      - name: Harden the runner (Audit all outbound calls)
        uses: step-security/harden-runner@9af89fc71515a100421586dfdb3dc9c984fbf411 # v2.19.4
        with:
          egress-policy: audit

      - name: Welcome first-time contributor
        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
        with:
          script: |
            // Iterative pattern from actions/github-script@v9.0.0 README:
            // skip the just-opened PR by number and return early if ANY
            // other PR by this author exists. Robust to GitHub's eventual
            // consistency on listForRepo (the just-opened PR may not yet
            // be indexed). Using sender.login (canonical) — for `opened`
            // it equals pull_request.user.login.
            const sender = context.payload.sender;

            // Skip bots. user.type === 'Bot' is the canonical signal;
            // also belt-and-suspenders the [bot]-suffix check (consistent
            // with the PR triage workflow's KNOWN_BOTS handling).
            if (sender.type === 'Bot' || sender.login.endsWith('[bot]')) {
              console.log(`Sender ${sender.login} is a bot. Skipping.`);
              return;
            }

            const opts = github.rest.issues.listForRepo.endpoint.merge({
              ...context.issue,
              creator: sender.login,
              state: 'all',
            });
            const items = await github.paginate(opts);

            for (const item of items) {
              if (item.number === context.issue.number) continue;
              if (item.pull_request) {
                console.log(
                  `Sender ${sender.login} already has PR #${item.number}. Skipping.`,
                );
                return;
              }
            }

            const body = [
              `Welcome to local-deep-research — and thank you for your contribution. We genuinely appreciate the time you're putting in.`,
              ``,
              `Here's a starter pack to help your PR move smoothly:`,
              ``,
              `**Get set up locally**`,
              `- [Installation guide](https://github.com/LearningCircuit/local-deep-research/blob/main/docs/installation.md) — running LDR`,
              `- [Developer guide](https://github.com/LearningCircuit/local-deep-research/blob/main/docs/developing.md) — setting up a dev environment`,
              `- Install our pre-commit hooks (one-time, [details in CONTRIBUTING.md](https://github.com/LearningCircuit/local-deep-research/blob/main/CONTRIBUTING.md#-quick-start)):`,
              `  \`\`\``,
              `  pre-commit install`,
              `  pre-commit install-hooks`,
              `  \`\`\``,
              ``,
              `**Understand the codebase**`,
              `- [Architecture overview](https://github.com/LearningCircuit/local-deep-research/blob/main/docs/architecture.md) — how the pieces fit together`,
              `- [Tests README](https://github.com/LearningCircuit/local-deep-research/blob/main/tests/README.md) — how to run the test suite locally`,
              `- [FAQ](https://github.com/LearningCircuit/local-deep-research/blob/main/docs/faq.md) and [Troubleshooting](https://github.com/LearningCircuit/local-deep-research/blob/main/docs/troubleshooting.md) — common setup, config, and operational issues`,
              `- Found a security issue? See [SECURITY.md](https://github.com/LearningCircuit/local-deep-research/blob/main/SECURITY.md) for the responsible-disclosure process — please don't open a public PR for it.`,
              ``,
              `**Before you ask for review**`,
              `- Open PRs against \`main\` unless a maintainer says otherwise.`,
              `- Confirm your PR has a single clear purpose ([PR process](https://github.com/LearningCircuit/local-deep-research/blob/main/CONTRIBUTING.md#-pull-request-process)).`,
              `- Describe in your PR body what you tested by hand — "CI is green" alone isn't enough.`,
              `- Drop by [Discord](https://discord.gg/ttcqQeFcJ3) if you'd like to chat with maintainers or other contributors.`,
              ``,
              `A maintainer will take a look — if you don't hear back within 7 days, feel free to ping.`,
            ].join('\n');

            await github.rest.issues.createComment({
              owner: context.repo.owner,
              repo: context.repo.repo,
              issue_number: context.payload.pull_request.number,
              body,
            });