---
name: github-repo-setup
description: |
  Reusable scaffold for public TypeScript/Node.js repositories under
  a target organization. Use when creating a new GitHub repository to generate all
  community standards, CI/CD, config files, labels, and topics in one pass.
---

# GitHub Repository Setup

Scaffold a new public TypeScript/Node.js repo with community standards, CI, and strict tooling.

## Prerequisites

- Git CLI with SSH (`~/.ssh/id_ed25519`)
- GitHub CLI (`gh`) authenticated as `{{ORG_NAME}}`
- Node.js 24+
- Default branch: `main`
- Credentials: Load from a secure environment file (e.g., `{{SECRETS_ENV_PATH}}`) or OS credential stores. **CRITICAL: NEVER hardcode this path in shared templates or commit `.env` files.**

## Parameters

Replace these placeholders throughout:

| Placeholder            | Example                  |
| ---------------------- | ------------------------ |
| `{{ORG_NAME}}`         | `neverinfamous`          |
| `{{REPO_NAME}}`        | `my-mcp-server`          |
| `{{DESCRIPTION}}`      | `MCP server for X`       |
| `{{YEAR}}`             | `2026`                   |
| `{{SECRETS_ENV_PATH}}` | `C:\path\to\secrets.env` |

---

## 1. Create Files (~28 total)

Read the reference file listed in the **Template Source** column for exact file contents. Files marked _inline_ are defined directly below the table.

### File Manifest

| File                                          | Purpose                             | Template Source                                             |
| --------------------------------------------- | ----------------------------------- | ----------------------------------------------------------- |
| **Community Standards**                       |                                     |                                                             |
| `LICENSE`                                     | MIT license                         | _inline_                                                    |
| `README.md`                                   | Badges, quick start, TOC, examples  | Adapt from reference repos                                  |
| `CONTRIBUTING.md`                             | Fork → Clone → Branch → PR workflow | [community-standards.md](references/community-standards.md) |
| `CODE_OF_CONDUCT.md`                          | Contributor Covenant 2.1            | [community-standards.md](references/community-standards.md) |
| `SECURITY.md`                                 | Vulnerability reporting process     | [community-standards.md](references/community-standards.md) |
| `CHANGELOG.md`                                | Keep a Changelog format (empty)     | _inline_                                                    |
| `UNRELEASED.md`                               | SSoT for unreleased changes         | _inline_                                                    |
| **GitHub Automation**                         |                                     |                                                             |
| `.github/workflows/codeql.yml`                | CodeQL static analysis              | [github-automation.md](references/github-automation.md)     |
| `.github/workflows/lint-and-test.yml`         | CI: lint, typecheck, build, test    | [github-automation.md](references/github-automation.md)     |
| `.github/workflows/secrets-scanning.yml`      | TruffleHog + Gitleaks               | [github-automation.md](references/github-automation.md)     |
| `.github/workflows/dependabot-auto-merge.yml` | Auto-squash patch/minor PRs         | [github-automation.md](references/github-automation.md)     |
| `.github/workflows/e2e.yml`                   | Playwright E2E tests                | [github-automation.md](references/github-automation.md)     |
| `.github/dependabot.yml`                      | Grouped dependency updates          | [github-automation.md](references/github-automation.md)     |
| `.github/ISSUE_TEMPLATE/bug_report.md`        | Rich bug report template            | [github-automation.md](references/github-automation.md)     |
| `.github/ISSUE_TEMPLATE/feature_request.md`   | Feature request template            | [github-automation.md](references/github-automation.md)     |
| `.github/ISSUE_TEMPLATE/config.yml`           | Blank issue redirect                | [github-automation.md](references/github-automation.md)     |
| `.github/pull_request_template.md`            | Comprehensive PR checklist          | [github-automation.md](references/github-automation.md)     |
| **Project Config**                            |                                     |                                                             |
| `.gitignore`                                  | Comprehensive ignores               | _inline_                                                    |
| `.gitattributes`                              | Line ending normalization           | _inline_                                                    |
| `.prettierrc`                                 | Code formatting config              | [project-config.md](references/project-config.md)           |
| `.prettierignore`                             | Prettier exclusions                 | [project-config.md](references/project-config.md)           |
| `.gitleaks.toml`                              | Secret scanning config              | [project-config.md](references/project-config.md)           |
| `package.json`                                | Project manifest                    | _inline_                                                    |
| `tsconfig.json`                               | TypeScript strict config            | [project-config.md](references/project-config.md)           |
| `eslint.config.js`                            | ESLint 10 strict + test config      | [project-config.md](references/project-config.md)           |
| `tsup.config.ts`                              | Build configuration                 | [project-config.md](references/project-config.md)           |
| `vitest.config.ts`                            | Test configuration                  | [project-config.md](references/project-config.md)           |
| `src/index.ts`                                | Entry point placeholder             | Empty file                                                  |

---

### Inline Templates

See **[inline-templates.md](references/inline-templates.md)** for the boilerplate contents of `LICENSE`, `CHANGELOG.md`, `UNRELEASED.md`, `.gitattributes`, `.gitignore`, and `package.json`.

> **Note**: AI-suggested versions may be outdated. Always run `npm outdated` and `npx npm-check-updates -u` after install.

---

## 2. Init Repo & Push

> **CRITICAL HITL GATE**: You MUST stop and ask the user for explicit confirmation before running the `gh repo create` and `git push` commands. Creating a public repository is a destructive and public action.

```powershell
cd {{TARGET_DIRECTORY}}
git init
git add .
git commit -m "Initial commit: Repository setup"
gh repo create {{ORG_NAME}}/{{REPO_NAME}} --public --source=. --remote=origin --description "{{DESCRIPTION}}"
git push -u origin main
```

> **Note**: `git add .` is appropriate here because this is a brand-new repo with a clean `.gitignore`. For established repos, always use selective staging per user rules.

## 3. Labels, Topics & GitHub Settings

```powershell
# Labels
gh label create dependencies --description "Dependency PRs" --color 0052CC --repo {{ORG_NAME}}/{{REPO_NAME}} --force
gh label create github-actions --description "GitHub Actions" --color FF6B6B --repo {{ORG_NAME}}/{{REPO_NAME}} --force
gh label create npm --description "NPM updates" --color CB3837 --repo {{ORG_NAME}}/{{REPO_NAME}} --force
gh label create bug --description "Bug reports" --color d73a49 --repo {{ORG_NAME}}/{{REPO_NAME}} --force
gh label create enhancement --description "Feature requests" --color a2eeef --repo {{ORG_NAME}}/{{REPO_NAME}} --force

# Topics
gh repo edit {{ORG_NAME}}/{{REPO_NAME}} --add-topic typescript --add-topic nodejs

# Security settings (automate instead of manual UI)
gh api repos/{{ORG_NAME}}/{{REPO_NAME}} -X PATCH -f security_and_analysis.secret_scanning.status=enabled
gh api repos/{{ORG_NAME}}/{{REPO_NAME}} -X PATCH -f security_and_analysis.secret_scanning_push_protection.status=enabled
```

## 4. Verify

```powershell
npm install          # 0 vulnerabilities
npm run build        # Compiles
npm run typecheck    # No errors
npm run lint         # No errors
git status           # .gitignore working
npm outdated         # Update if needed
git remote -v        # origin → github.com/{{ORG_NAME}}/{{REPO_NAME}}
gh repo view         # Displays repo info
```

## Reference Repos

- `{{ORG_NAME}}/db-mcp` (SQLite)
- `{{ORG_NAME}}/mysql-mcp` (MySQL)
- `{{ORG_NAME}}/postgres-mcp` (PostgreSQL)
- `{{ORG_NAME}}/memory-journal-mcp` (Memory Journal)
