Onboarding: angular/angular-seed

Generated by RepoPilot · 2026-05-06 · Source

Agent protocol

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/angular/angular-seed 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.

Verdict

WAIT — Stale — last commit 4y ago

• 35+ active contributors
• Distributed ownership (top contributor 26% of recent commits)
• MIT licensed
• CI configured
• ⚠ Stale — last commit 4y ago
• ⚠ No test directory detected

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

Verify before trusting

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

What it runs against: a local clone of angular/angular-seed — 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 angular/angular-seed | 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 ≤ 1558 days ago | Catches sudden abandonment since generation |

<details> <summary><b>Run all checks</b> — paste this script from inside your clone of <code>angular/angular-seed</code></summary>

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of angular/angular-seed. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/angular/angular-seed.git
#   cd angular-seed
#
# 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 angular/angular-seed and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "angular/angular-seed(\\.git)?\\b" \\
  && ok "origin remote is angular/angular-seed" \\
  || miss "origin remote is not angular/angular-seed (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 "app/app.js" \\
  && ok "app/app.js" \\
  || miss "missing critical file: app/app.js"
test -f "app/index.html" \\
  && ok "app/index.html" \\
  || miss "missing critical file: app/index.html"
test -f "package.json" \\
  && ok "package.json" \\
  || miss "missing critical file: package.json"
test -f "karma.conf.js" \\
  && ok "karma.conf.js" \\
  || miss "missing critical file: karma.conf.js"
test -f "e2e-tests/protractor.conf.js" \\
  && ok "e2e-tests/protractor.conf.js" \\
  || miss "missing critical file: e2e-tests/protractor.conf.js"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 1558 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~1528d)"
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/angular/angular-seed"
  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).

</details>

TL;DR

Angular-seed is a minimal, pre-configured starter skeleton for AngularJS 1.7 single-page applications (SPAs). It scaffolds a working AngularJS project with two example views, routing via angular-route, and a complete test/build pipeline (Karma for unit tests, Protractor for e2e tests, http-server for dev). This removes boilerplate setup so developers can immediately focus on building features. Flat MVC structure: app/ contains the main application with core/ housing reusable modules (version filter/directive), and two example view modules (view1/, view2/) each with controller, template, and spec files. Tests mirror source structure with .spec.js files. End-to-end tests live separately in e2e-tests/. No build transpilation—source JavaScript and HTML serve directly.

Who it's for

Junior to mid-level frontend developers building traditional AngularJS 1.x web applications who need a working project structure, test harness, and development server without starting from scratch. Teams maintaining legacy AngularJS codebases also use this as a reference for modern tooling practices.

Maturity & risk

This is a stable, production-ready reference implementation that is not actively developed—it is AngularJS 1.7.x, released in 2018. No recent commits are evident from the repo data. The project includes complete CI (Travis), test suites (Karma + Jasmine + Protractor), and linting (.jshintrc), indicating quality standards, but it serves as a historical template rather than an evolving product.

High risk for new projects: AngularJS 1.x has been in long-term support (LTS) since 2021 and is effectively deprecated in favor of Angular 2+. The dependency chain is minimal but dated (angular@^1.7.5, html5-boilerplate@0.0.1). No obvious security updates will land. Use this only to maintain existing AngularJS applications or as a learning reference; do not start new production projects here.

Active areas of work

This repository is in maintenance-only mode. No active development is evident from the data provided. It exists as a canonical example for how to structure AngularJS 1.x projects with proper testing and tooling, preserved for historical reference and existing project maintenance.

Get running

git clone https://github.com/angular/angular-seed.git
cd angular-seed
npm install
npm start

Then open http://localhost:8000/index.html in your browser. The npm install automatically runs npm run copy-libs, copying Angular and dependencies from node_modules/ to app/lib/ for serving.

Daily commands:

npm start              # Starts http-server on localhost:8000
npm test              # Runs Karma test suite (watches for changes)
npm test-single-run   # One-shot Karma run
npm run protractor    # Runs e2e tests (requires webdriver-manager)

Map of the codebase

• app/app.js — Root AngularJS module definition that bootstraps the entire application and configures routing—every feature depends on this being correct.
• app/index.html — Main HTML entry point that loads AngularJS, dependencies, and the ng-app directive—the actual page served to browsers.
• package.json — Defines all npm dependencies and build scripts; without correct versions here, the app cannot run or test properly.
• karma.conf.js — Test runner configuration for Jasmine unit tests; any test infrastructure change flows through this file.
• e2e-tests/protractor.conf.js — End-to-end test configuration; defines how the full application is tested in a real browser.
• app/core/version/version.js — Core utility module providing version interpolation; demonstrates the seed's recommended pattern for shared services.

How to make changes

Add a New Feature View with Controller

1. Create a new directory under app/ for your feature (e.g., app/view3/) (app/view3/)
2. Create the controller file with a module and controller definition following the view1 pattern (app/view3/view3.js)
3. Create the HTML template with ng-* directives (app/view3/view3.html)
4. Register the route in app/app.js by adding a $routeProvider.when() call (app/app.js)
5. Create a unit test file (view3.spec.js) following the existing test pattern (app/view3/view3.spec.js)
6. Add a link to the new view in app/index.html navigation (app/index.html)

Add a New Reusable Service or Filter

1. Create a new file under app/core/ (e.g., app/core/myservice/myservice.js) following the version.js structure (app/core/myservice/myservice.js)
2. Define an AngularJS service/factory with .factory() or .service() (app/core/myservice/myservice.js)
3. Create a corresponding test file (myservice.spec.js) with jasmine describe/it blocks (app/core/myservice/myservice.spec.js)
4. Inject the new service into app.js module dependencies if needed (app/app.js)
5. Include the new .js file in app/index.html via a <script> tag (app/index.html)

Write and Run Unit Tests

1. Create or edit a .spec.js file (e.g., app/view1/view1.spec.js) with jasmine describe/it/expect blocks (app/view1/view1.spec.js)
2. Ensure karma.conf.js includes your test file in the files pattern (karma.conf.js)
3. Run tests with npm test, which executes karma start karma.conf.js (defined in package.json scripts) (package.json)

Run E2E Tests Against the App

1. Add test scenarios to e2e-tests/scenarios.js following the existing describe/it pattern (e2e-tests/scenarios.js)
2. Ensure e2e-tests/protractor.conf.js baseUrl points to your running server (http://localhost:8000 by default) (e2e-tests/protractor.conf.js)
3. Start the app server (npm start runs http-server) and run protractor e2e-tests/protractor.conf.js (e2e-tests/protractor.conf.js)

Why these technologies

• AngularJS 1.7.5 — Provides two-way data binding, dependency injection, and routing—core MVC framework for the seed.
• Karma + Jasmine — Standard test runner and BDD assertion library for AngularJS; integrated into the npm test script.
• Protractor — WebDriver-based E2E testing tool built for AngularJS; seamlessly handles async operations in Angular apps.
• http-server — Lightweight local dev server; npm start launches it to serve the SPA on localhost:8000.
• cpx (file copy tool) — Post-install script copies dependencies from node_modules into app/lib/ so browser can load them.

Trade-offs already made

• Single-page application (SPA) architecture with client-side routing

  • Why: Eliminates page reloads and enables smooth transitions; seed demonstrates best practice for 2010s-era AngularJS apps.
  • Consequence: Requires users to have JavaScript enabled; all routing state is in-browser; no server-side rendering.

• No backend API; all data is hardcoded or generated client-side

  • Why: Seed is a skeleton—focus is on AngularJS patterns, not API integration; keeps setup minimal.
  • Consequence: Developers must replace example controllers with real backend calls; no persistence.

• Unit tests (Karma) + E2E tests (Protractor) as two separate test levels

  • Why: Provides coverage at different granularities: unit tests for services/controllers, E2E for full workflows.
  • Consequence: Test maintenance burden is higher; requires running two different test suites.

• Manual script tag inclusion in index.html rather than module bundler

  • Why: Keeps setup simple; npm copy-libs script handles dependency distribution; no build step for JS.
  • Consequence: Global namespace pollution; order-dependent script loading; no tree-shaking or minification built in.

Non-goals (don't propose these)

• Does not provide a production-grade backend; all data is client-side.
• Does not include a database or persistence layer.
• Does not handle authentication or authorization.
• Does not provide real-time communication (WebSockets).
• Does not bundle or minify code automatically; relies on manual script inclusion.
• Not designed for mobile or responsive design (though html5-boilerplate includes responsive meta tags).
• Does not include state management beyond AngularJS $scope.
• Does not provide built-in logging, error tracking, or analytics.

Traps & gotchas

1. copy-libs quirk: npm run copy-libs (triggered by postinstall) copies Angular from node_modules/ to app/lib/. If you modify files in node_modules, you must re-run copy-libs or directly edit app/lib/ to see changes. 2. No build step: HTML and JS are served raw—no transpilation, no bundling, no minification in development. This means ES5 syntax only and careful global namespace management. 3. JDK required for e2e tests: Running npm run protractor requires Java installed for Selenium WebDriver, not obvious from package.json alone. 4. Async loader (index-async.html): The npm run update-index-async script is a one-time utility to inject the Angular loader inline; don't expect it to run automatically.

Architecture

Concepts to learn

• Client-side routing (ng-route) — Angular-seed uses ngRoute to implement SPA navigation without full page reloads; understanding how routes map URLs to controllers and templates is central to AngularJS architecture.
• Dependency Injection (DI) — AngularJS relies heavily on DI for wiring controllers, services, filters, and directives; this seed injects modules and demonstrates the pattern throughout.
• Two-way data binding — Core AngularJS feature that automatically syncs model and view; the seed's controllers use $scope to demonstrate how changes propagate without manual DOM manipulation.
• Karma test runner — The seed uses Karma to run Jasmine tests in headless browsers; understanding karma.conf.js is essential to run and write tests in this project.
• Protractor end-to-end testing — E2E tests in e2e-tests/ use Protractor to simulate user interactions in a real browser; important for verifying full workflows beyond unit tests.
• AngularJS filter architecture — The seed includes a custom interpolate filter in core/version/ demonstrating how to create reusable data transformers used in templates.
• AngularJS directive composition — The version directive in core/version/ shows how to encapsulate behavior and templates as reusable components; a stepping stone to understanding components.

Related repos

• angular/angular — The core AngularJS 1.7 framework that this seed is built upon; reference for API docs and source.
• angular/angularjs-seed-examples — Official Angular organization repo with additional seed variants and real-world example applications using AngularJS patterns.
• yeoman/generator-angular — Yeoman generator that automates AngularJS project scaffolding; alternative to cloning this seed if you prefer interactive setup.
• angular/angular.js — Archived historical AngularJS repository; useful for understanding the evolution and reading full changelog for 1.x versions.
• angular/angular-seed-springboot — Spring Boot variant of angular-seed for teams pairing AngularJS frontend with Java backend; shows full-stack integration.

PR ideas

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 missing unit tests for app/app.js and app/index.html initialization

The repo has test files for core modules and views (view1.spec.js, view2.spec.js, version.spec.js) but lacks tests for the main application bootstrap in app/app.js. This is a critical gap since app.js defines routing configuration and module dependencies. New contributors can add meaningful tests that verify route configuration, module dependencies are loaded, and the app initializes correctly.

• [ ] Create app/app.spec.js with tests for AngularJS module initialization
• [ ] Add tests verifying ngRoute is properly configured with correct route definitions for /view1 and /view2
• [ ] Add tests verifying the default route and otherwise redirect behavior
• [ ] Run 'npm test' to verify all tests pass with karma

Add GitHub Actions CI workflow to replace .travis.yml

The repo has an outdated .travis.yml configuration but no modern GitHub Actions workflow. Contributors can add a .github/workflows/ci.yml that runs unit tests (karma) and e2e tests (protractor) on every push/PR, providing faster feedback and better integration with GitHub. This modernizes the CI/CD without removing existing Travis config.

• [ ] Create .github/workflows/ci.yml with Node.js setup and caching
• [ ] Add job steps: npm install, npm run test-single-run, npm run update-webdriver, npm run protractor
• [ ] Specify Node.js versions to test against (14.x, 16.x, 18.x)
• [ ] Test the workflow by opening a pull request and verifying it runs successfully

Add e2e test coverage for view navigation and controller functionality

The e2e-tests/scenarios.js file exists but likely has minimal coverage. Contributors should expand e2e tests to verify the core functionality: navigating between view1 and view2, checking that view-specific content renders, and validating that the version directive displays correctly. This ensures the seed project's actual user workflows are tested.

• [ ] Expand e2e-tests/scenarios.js to add tests for navigating to /view1 and /view2
• [ ] Add assertions verifying view1-specific content (h2 text, ng-view content) is present after navigation
• [ ] Add assertions verifying view2-specific content is present after navigation
• [ ] Add test for version-directive rendering on the main page
• [ ] Run 'npm run protractor' to verify e2e tests pass

Good first issues

• Add a unit test for view2.js: app/view2/view2.spec.js exists but may be minimal. Add specs for the controller's initialization, scope variables, and any methods (check what the controller actually does and test all paths).
• Expand the version directive demo: app/core/version/version-directive.js is a toy example. Enhance its test coverage in version-directive.spec.js or improve the HTML rendering in app/view1/view1.html to show more version details (use the interpolate filter or extend the directive).
• Add missing e2e scenarios: e2e-tests/scenarios.js likely only tests basic navigation. Write new Protractor specs to verify view content loads, controller scope properties exist, and clicking elements triggers expected behavior (e.g., test that view1 displays the interpolated version string).

Top contributors

• @petebacondarwin — 26 commits
• @gkalpak — 22 commits
• @NgDashboard — 13 commits
• @tbosch — 4 commits
• @pedrosanta — 3 commits

Recent commits

• 8c69562 — chore(package): do not copy unnecessary files to lib (gkalpak)
• 21a3c93 — docs(README.md): mention how to upgrade to latest versions (gkalpak)
• 5ff1cb4 — chore(travis): use headless Chrome in tests (gkalpak)
• 398c09c — chore(*): do not install WebDriver for Firefox to avoid error on CI (gkalpak)
• 4079e61 — chore(travis): simplify and improve config (gkalpak)
• 04bc928 — chore(*): check in package-lock.json (gkalpak)
• b2cef7b — chore(*): upgrade all dependencies to latest versions (gkalpak)
• b218932 — docs(*): use the name AngularJS rather than Angular (petebacondarwin)
• 669efcc — chore(*): switch from bower to npm for frontend dependencies (gkalpak)
• ad58b5d — refactor(*): rename files and directories to bring in-line with modern best practices (gkalpak)

Security observations

• High · Outdated AngularJS Version with Known Vulnerabilities — package.json - dependencies: angular, angular-loader, angular-route, angular-mocks (^1.7.5). The project uses AngularJS 1.7.5, which is significantly outdated and contains multiple known security vulnerabilities. AngularJS 1.x reached end-of-life and no longer receives security updates. Known issues include XSS vulnerabilities in expression handling and template injection risks. Fix: Upgrade to the latest stable version of Angular (v17+) or at minimum Angular 1.8.3 if migration is not feasible. Consider migrating to modern Angular framework versions for long-term security.
• High · Outdated Development Dependencies with Security Vulnerabilities — package.json - devDependencies: protractor, karma, jasmine-core. Multiple development dependencies are severely outdated: Protractor (5.4.1 - deprecated since 2022), Karma (3.1.1 - missing security patches), and Jasmine (3.3.0). These tools have known vulnerabilities and lack security updates. Fix: Update to latest versions: Protractor (deprecated, migrate to Cypress/Playwright), Karma (4.4.1+), Jasmine (4.0.0+). Remove deprecated testing tools and adopt modern alternatives.
• Medium · XSS Vulnerability Risk via AngularJS Template Injection — app/view1/view1.js, app/view2/view2.js, app/core/version/version-directive.js. AngularJS 1.7.5 has known XSS vulnerabilities in expression handling and template compilation. The application uses ng-repeat and dynamic template binding patterns that could be susceptible to expression injection if user input is not properly sanitized. Fix: Implement strict Content Security Policy (CSP) headers. Use ng-bind instead of {{}} for user-controlled content. Implement input validation and output encoding. Consider using $sce.trustAsHtml carefully and validate inputs before binding.
• Medium · Insecure HTTP Server Configuration — package.json - scripts: start (http-server -a localhost -p 8000). The npm start script runs http-server on localhost without HTTPS. While limited to localhost in development, this could expose sensitive data if configuration is modified. Production use would be highly insecure. Fix: Ensure HTTPS is used in production environments. Add security headers via middleware. Document that this is development-only. Consider using webpack-dev-server or similar with built-in HTTPS support.
• Medium · Missing Security Headers Configuration — app/index.html, .travis.yml, karma.conf.js, e2e-tests/protractor.conf.js. No evidence of security headers (CSP, X-Frame-Options, X-Content-Type-Options, Strict-Transport-Security) in the server configuration or application setup. Fix: Add security headers to http-server configuration. Implement CSP policy to prevent XSS attacks. Add HSTS, X-Frame-Options, X-Content-Type-Options headers. Configure in .htaccess or server configuration files.
• Low · Outdated html5-boilerplate Dependency — package.json - dependencies: html5-boilerplate (0.0.1). html5-boilerplate version 0.0.1 is extremely outdated (appears to be a placeholder version) and likely contains security vulnerabilities and missing security best practices. Fix: Update to the latest html5-boilerplate version (8.0.0+). This includes modern security headers, modern HTML5 practices, and performance improvements.
• Low · No Input Validation Framework — app/view1/view1.js, app/view2/view2.js. The seed project lacks explicit input validation and sanitization framework setup. While AngularJS includes some built-in sanitization, there's no evidence of consistent validation patterns across the application. Fix: Implement input validation using a library like Joi or dedicated Angular validation modules. Add server-side validation. Use $sanitize service consistently for untrusted content.
• Low · Missing npm Audit and Dependency Locking — undefined. While package-lock.json exists, there's Fix: undefined

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

Where to read next

• 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.