If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/toptal/gitignore.io shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across all four use cases

• 31+ active contributors
• Distributed ownership (top contributor 28% of recent commits)
• MIT licensed
• CI configured
• Tests present
• ⚠ Stale — last commit 1y ago

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live toptal/gitignore.io repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/toptal/gitignore.io.

What it runs against: a local clone of toptal/gitignore.io — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in toptal/gitignore.io | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 533 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of toptal/gitignore.io. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/toptal/gitignore.io.git
#   cd gitignore.io
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of toptal/gitignore.io and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "toptal/gitignore.io(\\.git)?\\b" \\
  && ok "origin remote is toptal/gitignore.io" \\
  || miss "origin remote is not toptal/gitignore.io (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "Sources/App/Server.swift" \\
  && ok "Sources/App/Server.swift" \\
  || miss "missing critical file: Sources/App/Server.swift"
test -f "Sources/App/RouteHandlers/SiteRouteHandlers.swift" \\
  && ok "Sources/App/RouteHandlers/SiteRouteHandlers.swift" \\
  || miss "missing critical file: Sources/App/RouteHandlers/SiteRouteHandlers.swift"
test -f "Sources/App/RouteHandlers/APIRouteHandlers.swift" \\
  && ok "Sources/App/RouteHandlers/APIRouteHandlers.swift" \\
  || miss "missing critical file: Sources/App/RouteHandlers/APIRouteHandlers.swift"
test -f "Sources/App/Controllers/TemplateController.swift" \\
  && ok "Sources/App/Controllers/TemplateController.swift" \\
  || miss "missing critical file: Sources/App/Controllers/TemplateController.swift"
test -f "Package.swift" \\
  && ok "Package.swift" \\
  || miss "missing critical file: Package.swift"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 533 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~503d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/toptal/gitignore.io"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

gitignore.io is a web service that generates customized .gitignore files for Git repositories based on selected operating systems, programming languages, and IDEs. Built in Swift with a Vapor backend, it serves a REST API and web UI that combines templates from the toptal/gitignore submodule to create project-specific ignore rules without manual curation. Monolithic web app: Swift backend (Package.swift, main logic likely in Sources/ not listed) serves REST endpoints; Public/ contains static assets (HTML, CSS compiled from LESS, JavaScript via Webpack); Localizations/ JSON files provide i18n; .gitmodules points to toptal/gitignore templates as the data layer. Docker containerization via Dockerfile and docker-compose-dev.yml enables portable deployment.

Developers of all levels who need to quickly scaffold correct .gitignore files for new projects without memorizing language-specific patterns; teams adopting new tech stacks; CI/CD operators automating gitignore generation in project templates.

Production-ready and actively maintained. The repo shows CI/CD via Travis and GitHub Actions (close-inactive.yaml, update-templates.yml), multi-language localization (16 language JSON files), Docker support, and Webpack asset pipeline. Last visible activity shows dependabot.yml and recent workflow updates, indicating ongoing maintenance and security patching.

Low risk for a stable utility. Dependencies are well-curated (webpack, less-loader, jest for e2e tests) with recent versions. No obvious single-point-of-failure: template data is in an external submodule (toptal/gitignore) which could desync if not regularly updated. E2E tests exist via jest-puppeteer, reducing regression risk. No major red flags visible, but reliance on Swift 4.1 (.swift-version) may need modernization.

Active maintenance of CI workflows: dependabot.yml for dependency updates, update-templates.yml to sync the gitignore submodule templates, close-inactive.yaml for issue hygiene. Asset pipeline being maintained (Webpack 5, modern CSS loaders). No specific feature branch visible, but infrastructure improvements suggest focus on reliability and staying current.

git clone https://github.com/toptal/gitignore.io && cd gitignore.io && git submodule update --init --recursive && yarn install && docker-compose -f ./docker-compose-dev.yml up; then open http://localhost:8080

Daily commands: Development: docker-compose -f ./docker-compose-dev.yml build && docker-compose -f ./docker-compose-dev.yml up (mounts /Public and /Resources as volumes for hot reload, server on http://localhost:8080). Production: docker-compose up --build. For asset compilation: yarn install && yarn build to process LESS→CSS.

• Sources/App/Server.swift — Application entry point and server configuration for the Vapor web framework; every contributor must understand how the server initializes and routes requests.
• Sources/App/RouteHandlers/SiteRouteHandlers.swift — Defines web UI routes and template rendering logic; essential for understanding how users interact with the application.
• Sources/App/RouteHandlers/APIRouteHandlers.swift — Implements API endpoints that generate .gitignore files; core business logic for the service.
• Sources/App/Controllers/TemplateController.swift — Manages template loading, parsing, and composition; central to how gitignore content is assembled and served.
• Package.swift — Swift package manifest with Vapor framework dependencies; required to understand build configuration and dependency versions.
• Resources/Views/index.leaf — Main HTML template for the web interface; defines the user-facing UI and form interactions.
• .gitmodules — Git submodule configuration pointing to gitignore template repositories; templates are loaded as external dependencies.

Add a new gitignore template

1. Add template file to the gitignore submodule directory (typically in a git submodule pointed to by .gitmodules) (.gitmodules)
2. Template files are auto-discovered by TemplateController by scanning the template directory (Sources/App/Controllers/TemplateController.swift)
3. Templates appear automatically in API responses and dropdowns via IgnoreTemplateModel (Sources/App/Models/IgnoreTemplateModel.swift)

Add a new language localization

1. Create a new JSON file in Localizations directory following the English structure (Localizations/en.json)
2. Add translated UI strings using the same keys as the English version (Localizations/[new-language].json)
3. Update the Leaf template to load localized strings for the new language (Resources/Views/index.leaf)

Add a new API endpoint

1. Define the route and handler function in APIRouteHandlers (Sources/App/RouteHandlers/APIRouteHandlers.swift)
2. Register the route in Server.swift under the API route group (Sources/App/Server.swift)
3. Use UrlResolver to parse query parameters if needed (Sources/App/RouteHandlers/UrlResolver.swift)
4. Write unit tests for the new endpoint logic (Tests/AppTests/Controllers/TemplateControllerTests.swift)

Add a new UI form field or dropdown option

1. Update the HTML form structure in the Leaf template (Resources/Views/index.leaf)
2. Update client-side JavaScript to handle the new field in form submission (Public/assets/main.js)
3. Add corresponding CSS styling if needed (Public/assets/main.css)
4. Update APIRouteHandlers to process the new parameter (Sources/App/RouteHandlers/APIRouteHandlers.swift)

• Swift + Vapor — Type-safe web framework enabling fast backend development with compile-time guarantees; Swift is performant for I/O-bound template serving
• Leaf templating — Vapor's native templating engine; integrates seamlessly with Swift models for HTML generation
• jQuery + vanilla JavaScript — Lightweight client-side interaction for form handling and API calls without heavy framework overhead
• Webpack — Bundles and minifies CSS and JavaScript assets for production; configured for LESS preprocessing
• Git submodules — Templates are maintained in external repositories; submodules allow version-pinned template inclusion without duplicating content

• Templates loaded at startup and cached in memory

  • Why: Fast response times; templates are stable and infrequently updated
  • Consequence: Server restart required to pick up new templates; memory usage grows with template count; not suitable for >10k templates

• Stateless API design with URL-based template selection

  • Why: Enables shareable URLs, easy caching, and horizontal scaling without session storage
  • Consequence: Long URLs when selecting many templates; query string parsing complexity increases with feature additions

• No authentication or user accounts

  • Why: Simplifies deployment and reduces infrastructure complexity; .gitignore generation is a public utility
  • Consequence: No personalization, no usage analytics, no rate limiting per user; all users share global rate limits

• Swift backend instead of Node.js

  • Why: Type safety, single language across compiled server; faster startup and lower memory footprint than Node
  • Consequence: Smaller Swift ecosystem for web compared to Node; deployment requires Swift runtime or compilation

• Does not provide authentication or user accounts
• Does not store user-generated templates or preferences
• Does not track usage analytics or metrics
• Does not support real-time template updates without server restart
• Does not implement template versioning or rollback
• Does not support database persistence; all state is in-memory or on filesystem

1. The toptal/gitignore submodule must be initialized (git submodule update --init --recursive) or template data won't be available, causing API failures. 2) LESS compilation requires yarn build before Docker build; changes to Public/css/*.less won't appear in dev without this step. 3) Environment variables (HOST_ORIGIN, BASE_PREFIX, GOOGLE_ANALYTICS_UID) must be set in docker-compose YAML or fall back to hardcoded defaults, potentially causing CORS or analytics issues in non-standard deployments. 4) Swift 4.1 (.swift-version) is locked and may not run on modern Xcode/macOS without version pinning; dependency resolution in Package.resolved is critical.

• Git Submodules — gitignore.io uses .gitmodules to embed toptal/gitignore as a dependency; understanding submodule sync is critical for maintaining template freshness and avoiding stale rules
• LESS (CSS Preprocessor) — The project uses LESS in Public/css/ compiled via webpack's less-loader; modifying styles requires understanding LESS variables, mixins, and the build step
• Webpack Asset Pipeline — The build process orchestrates LESS compilation, CSS minimization, font bundling, and JavaScript via multiple loaders and plugins (mini-css-extract-plugin, css-minimizer-webpack-plugin); any frontend asset change flows through this
• Docker Volume Mounts — Development mode (docker-compose-dev.yml) mounts /Public and /Resources as volumes for live reload; understanding volume semantics is essential for debugging local dev setup
• Swift Package Manager (SPM) — Package.swift and Package.resolved manage backend dependencies; Swift backend modifications require understanding SPM dependency resolution and Vapor framework structure
• E2E Testing with Puppeteer — jest-puppeteer runs headless browser tests (e2e-tests/) to validate the full workflow from UI interaction to .gitignore generation; this is the primary safety net for user-facing changes
• Internationalization (i18n) via JSON — The Localizations/*.json structure stores UI text for 16 languages; adding features requires understanding how keys are namespaced and how the backend serves the right locale to frontend

• toptal/gitignore — Official template data source (submodule); this is the actual .gitignore rule collection that gitignore.io wraps
• github/gitignore — GitHub's official .gitignore template repository; a competing/complementary source of templates with similar scope
• dcodeIO/protobuf.js — Example of a well-maintained multi-language library with similar i18n + asset pipeline patterns (webpack, JSON localization)
• vapor/vapor — The Swift web framework used by gitignore.io's backend; understanding Vapor is necessary to modify server-side logic
• webpack/webpack — The asset bundler used in this repo's frontend; knowledge of Webpack 5 plugins (mini-css-extract, css-minimizer) is needed for build changes

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add E2E test coverage for template generation API endpoints

The repo has jest-puppeteer and puppeteer configured in package.json with a 'test' script for e2e-tests, but there's no visible e2e-tests directory in the file structure. The core functionality (generating .gitignore files) lacks automated browser-based tests. This would validate that the web UI correctly renders templates, handles API calls, and downloads generated files across different template combinations.

• [ ] Create e2e-tests/ directory with test setup files
• [ ] Add tests for main template selection flow in Resources/Views/index.leaf
• [ ] Add tests for API response validation (generating gitignore content)
• [ ] Add tests for file download functionality
• [ ] Ensure tests run in CI via existing GitHub Actions workflows

Implement automated localization validation in CI pipeline

The repo maintains 15 localization files (Localizations/*.json from ar.json to zh.json), but there's no visible CI workflow validating JSON syntax, key consistency across locales, or missing translations. This prevents silent bugs where translations become out of sync. A GitHub Action workflow should validate all localization files before merge.

• [ ] Create .github/workflows/validate-localization.yml
• [ ] Add JSON schema validation for all files in Localizations/
• [ ] Add check that all locales have the same translation keys as en.json
• [ ] Add check for common character encoding issues in non-Latin scripts
• [ ] Document process in .github/CONTRIBUTING.md with localization guidelines

Add Jest unit tests for frontend asset bundling and webpack configuration

The repo has webpack, multiple loaders (css-loader, less-loader, file-loader, style-loader), and assets in Public/, but no unit tests validating the build output. Jest is configured but unused. This would catch regressions in CSS/JS bundling, font loading, and asset optimization that currently relies only on CI build success.

• [ ] Create tests/ or tests/ directory with webpack config tests
• [ ] Add tests validating css-minimizer-webpack-plugin output size
• [ ] Add tests for font file loading and mini-css-extract-plugin output
• [ ] Add tests for Public/assets/main.js and main.css generation
• [ ] Update package.json test script to run both e2e and unit tests

• Add Jest unit tests for Public/assets/main.js (currently only e2e tests via jest-puppeteer exist); this would improve confidence in frontend refactoring and CI coverage.
• Create a missing Localizations/README.md guide documenting the JSON schema (which fields are translatable, how to add a new language, naming conventions); currently only exists as comment in README snippet.
• Add API documentation in .github/ or docs/ showing REST endpoint signatures (e.g. POST /api/gitignore with parameter schemas), since no OpenAPI/Swagger spec is visible but the service serves an API.

• High · Outdated and Vulnerable Dependencies — Package.swift / package.json dependencies. Multiple npm dependencies have known vulnerabilities and are significantly outdated. Notably: puppeteer@2.1.1 (released 2019, current is v20+), jest@27.5.1 (outdated), and jquery@3.6.0 which may have security issues. These dependencies should be updated to their latest stable versions. Fix: Run 'npm audit' to identify all vulnerabilities. Update all dependencies to latest stable versions: npm update. Consider using npm audit fix to automatically patch known vulnerabilities. Implement automated dependency scanning in CI/CD pipeline.
• High · Missing Security Headers Configuration — Dockerfile / Application configuration. No evidence of security headers (CSP, X-Frame-Options, X-Content-Type-Options, Strict-Transport-Security) in the visible configuration. This is critical for a web application serving user-generated content (gitignore templates). Fix: Implement security headers in the Swift/Vapor application middleware. Add Content-Security-Policy, X-Frame-Options: DENY, X-Content-Type-Options: nosniff, and HSTS headers. Review FileMiddlewareWithBasePrefix.swift for proper header implementation.
• High · Potential Path Traversal via File Operations — Sources/App/Extensions/FileManager+Extensions.swift, Sources/App/Controllers/TemplateController.swift. FileManager+Extensions.swift and file handling logic may be vulnerable to path traversal attacks if user input is not properly validated when constructing file paths for template retrieval. Fix: Implement strict input validation and path normalization. Use allowlist validation for template names. Never directly concatenate user input into file paths. Validate that resolved paths stay within allowed directories using canonicalization.
• Medium · Exposed Docker Port Without Rate Limiting — docker-compose.yml, Dockerfile. Docker configuration exposes port 8080 without visible rate limiting, DDoS protection, or authentication mechanisms. The application could be vulnerable to brute force or resource exhaustion attacks. Fix: Implement rate limiting middleware in the application. Deploy behind a reverse proxy (nginx/Apache) with rate limiting and DDoS protection. Consider implementing API authentication/API keys for programmatic access.
• Medium · Insufficient Input Validation on Template Generation — Sources/App/Controllers/TemplateController.swift, Sources/App/Extensions/String+Extensions.swift. The TemplateController.swift likely accepts user input to generate .gitignore files. Without proper validation, this could lead to injection attacks or generation of malicious content. Fix: Implement strict input validation for all user-supplied template parameters. Use allowlist validation for template identifiers. Sanitize all output. Implement content validation before file generation.
• Medium · Old Travis CI Configuration — .travis/ci.sh, .travis/update-submodule.sh, .travis.yml. The .travis directory and .travis.yml configuration may contain outdated security practices or abandoned CI/CD setup. Travis CI has known issues with credential exposure. Fix: Migrate to GitHub Actions (already partially done with .github/workflows). Review and remove all Travis CI configuration. Audit git history for any exposed secrets. Implement branch protection rules.
• Medium · Submodule Dependency Management Risk — .gitmodules, .travis/update-submodule.sh. .gitmodules indicates external git submodule dependencies. These can introduce supply chain risks if submodules are compromised or point to untrusted sources. Fix: Audit all submodule sources for legitimacy. Use signed commits and tags where possible. Implement submodule verification in CI/CD. Consider moving to npm/package manager dependencies instead. Pin submodules to specific commit hashes, not branches.
• Low · Missing HTTPS Enforcement — docker-compose.yml, Dockerfile. No visible enforcement of HTTPS in docker-compose or Dockerfile configuration. The application should redirect HTTP to HTTPS. Fix: Configure HTTPS enforcement in the Swift/Vapor application. Deploy behind a reverse proxy with automatic HTTPS redirection. Implement HSTS header (Strict-Transport-Security).
• Low · Potential Information — undefined. undefined Fix: undefined

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.