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/solidusio/solidus 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 the board

• Last commit 5d ago
• 15 active contributors
• Distributed ownership (top contributor 27% of recent commits)
• Other licensed
• CI configured
• Tests present
• ⚠ Non-standard license (Other) — review terms

_{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 solidusio/solidus repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/solidusio/solidus.

What it runs against: a local clone of solidusio/solidus — 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 solidusio/solidus | Confirms the artifact applies here, not a fork | | 2 | License is still Other | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 35 days ago | Catches sudden abandonment since generation |

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

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

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

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

# 4. Critical files exist
test -f "Gemfile" \\
  && ok "Gemfile" \\
  || miss "missing critical file: Gemfile"
test -f "admin/app/components/solidus_admin/base_component.rb" \\
  && ok "admin/app/components/solidus_admin/base_component.rb" \\
  || miss "missing critical file: admin/app/components/solidus_admin/base_component.rb"
test -f ".github/workflows/test.yml" \\
  && ok ".github/workflows/test.yml" \\
  || miss "missing critical file: .github/workflows/test.yml"
test -f ".rubocop.yml" \\
  && ok ".rubocop.yml" \\
  || miss "missing critical file: .rubocop.yml"
test -f "admin/app/assets/config/solidus_admin_manifest.js" \\
  && ok "admin/app/assets/config/solidus_admin_manifest.js" \\
  || miss "missing critical file: admin/app/assets/config/solidus_admin_manifest.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 35 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~5d)"
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/solidusio/solidus"
  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).

Solidus is an open-source Rails-based e-commerce platform that provides a complete, modular foundation for building custom online stores. It gives merchants and developers full control over their storefront through a REST API, customizable admin interface (built in the /admin directory with modern JavaScript/React), and a highly extensible Ruby gem architecture. The core value is enabling industry-specific e-commerce workflows without vendor lock-in. Solidus is a Rails engine-based monorepo structure: the root contains the main solidus gem, the /admin subdirectory is a separate Node.js/JavaScript asset build pipeline for the modern admin UI, and multiple specialized gems live as composable packages (core, api, backend, frontend inferred from governance and workflows). State and business logic flow through Rails engines, controllers, and REST endpoints.

Rails developers and e-commerce agencies building custom storefronts who need a flexible, open alternative to Shopify or Magento. Store operators and product teams using Solidus-powered sites need admin tools. Contributors are distributed across the community with Nebulab providing primary technical direction.

Solidus is production-ready and actively maintained. It has 4.3M lines of Ruby, comprehensive GitHub Actions CI/CD pipelines (test.yml, lint.yml, backport.yml), and strong version governance (backportrc.json indicates active maintenance of multiple release branches). The codebase shows active commits and a mature changelog (CHANGELOG.md), though as a community-driven project it depends on contributor availability.

Primary risk is concentration: Nebulab is listed as the main contributor and director, creating potential bottleneck. The monorepo spans multiple gems (core, api, admin, backend, etc. inferred from structure) increasing coordination complexity. The admin rebuild in modern JavaScript (separate build pipeline in /admin/app/assets/builds) adds a JavaScript ecosystem dependency alongside the primary Ruby stack, expanding maintenance surface.

Active development visible in workflows: prepare_release.yml, prepare_post_release.yml, and update_release_draft.yml indicate ongoing versioning work; solidus_installer.yml suggests a new installation experience is being refined; triage_for_changelog.yml shows structured changelog management. The /admin rebuild is a current major initiative (separate Rakefile, build assets pipeline).

Check README for instructions.

Daily commands: Development: ./Procfile.dev (Procfile-based with Foreman or similar). Tests: bundle exec rake test or bundle exec rspec spec/. Admin UI dev: cd admin && npm install && npm start (inferred from separate admin structure). Docker dev environment available via .dockerdev/Dockerfile.

• Gemfile — Root dependency manifest defining all core gems and plugins; essential for understanding the project's external dependencies and version constraints.
• admin/app/components/solidus_admin/base_component.rb — Base component class for the admin UI system; all admin components inherit from this, making it the foundation for understanding component architecture.
• .github/workflows/test.yml — Primary CI/CD pipeline definition; shows how code is tested, linted, and validated before merge.
• .rubocop.yml — Code style and quality enforcement configuration; defines the linting standards every contributor must follow.
• admin/app/assets/config/solidus_admin_manifest.js — Asset pipeline configuration for admin UI; controls how stylesheets, JavaScript, and images are bundled and served.
• .github/CODEOWNERS — File ownership and review requirements; determines which maintainers must approve changes to specific areas.
• Rakefile — Task automation and build orchestration; entry point for common development workflows like running tests or building gems.

• ViewComponent base_component.rb (Rails ViewComponent, ERB) — Provides shared initialization, helpers, and lifecycle hooks for all admin components
  • Failure mode: If base class is broken, all admin pages fail to render; cascading UI collapse
• Tailwind CSS asset pipeline (Tailwind CSS, Webpack/Sprockets, PostCSS) — Compiles utility CSS, applies tree-shaking, serves compiled CSS to browser
  • Failure mode: If CSS compilation fails, styles are missing; admin UI becomes unusable
• GitHub Actions CI pipeline — Validates code quality, runs tests, caches gems, reports

Add a new admin component/page

1. Create a ViewComponent class inheriting from base_component.rb with proper slots and data access (admin/app/components/solidus_admin/[feature]/[action]/component.rb)
2. Create the HTML template for your component using ERB with Tailwind classes (admin/app/components/solidus_admin/[feature]/[action]/component.html.erb)
3. Add component documentation YAML with props, slots, and usage examples (admin/app/components/solidus_admin/[feature]/[action]/component.yml)
4. Register the route in admin routes if it's a page-level component (admin/config/routes.rb (inferred from file structure))

Add a new automated workflow or check

1. Create a new GitHub Actions workflow file in .github/workflows/ directory (.github/workflows/[workflow_name].yml)
2. Define triggers (on push, pull_request, schedule, etc.) and job matrix if needed (.github/workflows/[workflow_name].yml)
3. For custom logic, create a corresponding action in .github/actions/ subdirectory (.github/actions/[action_name]/action.yml)
4. Reference the workflow in CODEOWNERS if it relates to protected code paths (.github/CODEOWNERS)

Update code style or linting rules

1. Modify RuboCop rules in .rubocop.yml or add exceptions to .rubocop_todo.yml for gradual adoption (.rubocop.yml or .rubocop_todo.yml)
2. If using Standard instead, update .standard.yml configuration (.standard.yml)
3. Run lint workflow to validate rules don't break existing code (.github/workflows/lint.yml)
4. Document the rationale in GOVERNANCE.md or a pull request description for transparency (GOVERNANCE.md)

• Rails/ViewComponent — Encapsulated, testable, reusable UI components with isolated state; standard for modern Rails apps
• Tailwind CSS — Utility-first CSS for rapid, consistent admin UI styling without custom CSS bloat
• GitHub Actions — Native GitHub CI/CD eliminates external dependencies; built-in secret management and matrix testing
• RuboCop + Standard — Enforces consistent Ruby style across 600+ files; reduces code review friction on style issues
• Docker (Dockerfile + .psqlrc) — Standardizes dev environment across contributors; eliminates 'works on my machine' problems

• Component-based admin UI vs. traditional Rails ERB templates

  • Why: Improves reusability, testability, and maintainability of complex admin UI
  • Consequence: Higher initial setup overhead; requires learning ViewComponent patterns; slightly larger bundle size

• Tailwind CSS utility-first approach

  • Why: Faster iteration, smaller final CSS, consistent design tokens
  • Consequence: HTML templates become verbose; requires IDE support for class autocomplete; different mental model from CSS modules

• GitHub Actions as sole CI/CD

  • Why: Native integration, no third-party dependencies, cost-effective for open source
  • Consequence: Limited to GitHub ecosystem; less flexible for complex on-prem setups

• Matrix testing across Ruby versions in CI

  • Why: Catches compatibility regressions early across supported Ruby versions
  • Consequence: Longer CI run times (~10–20 min); uses more GitHub Actions minutes

• This repository does not provide a headless/API-first frontend framework; it is Rails-only
• Does not support non-Ruby implementations or language bindings
• Not a SaaS or hosted solution; purely a self-hosted open-source framework
• Does not provide pre-built payment processor integrations; relies on community gems

Database requirement: PostgreSQL is strongly preferred (.dockerdev/.psqlrc present, workflow comments likely assume Postgres); SQLite may have untested edge cases. Admin build separation: /admin has its own package.json, build tools, and asset pipeline—changes to admin require npm run build before testing and knowledge of JavaScript tooling alongside Ruby. Rails engine complexity: Solidus extends Rails through engines, so config/routes.rb mounting and initializer order matter greatly—misunderstanding engine load order causes cryptic bugs. Version constraints: .backportrc.json indicates multi-version maintenance—changes must be backported to stable branches per GOVERNANCE. Docker dev setup: .dockerdev/Dockerfile suggests local development may prefer containerized Postgres; native installs require manual Postgres setup.

• Rails Engines — Solidus is built as composable Rails engines (core, api, backend each extend Rails)—understanding engine initialization, route mounting, and gem dependencies is essential to modify or extend Solidus without breaking the framework
• Decorator Pattern (Spree Preference System) — Solidus uses decorators and preference objects extensively to allow extensions to override behavior without modifying core code—critical for writing non-breaking add-ons and custom stores
• State Machines (Order & Payment Workflows) — Orders and payments in Solidus transition through well-defined states (pending, completed, shipped, etc.) using state machine gems; understanding state transitions prevents race conditions and data corruption in critical paths
• REST API Versioning — Solidus maintains stable API versions for third-party integrations (mobile apps, headless frontends, webhooks); breaking API changes require careful migration strategy visible in backport workflows
• Polymorphic Associations (Payment Methods, Adjustments) — Solidus uses polymorphic database relationships to handle flexible entities (multiple payment types, tax/promotion adjustments)—understanding the implications for queries and N+1 problems is crucial for performance
• Asset Pipeline & Engine Asset Mounting — Modern admin UI is a separate JavaScript pipeline (webpack/esbuild in /admin), while legacy assets are Rails asset pipeline—confusion between the two causes CSS/JS not loading correctly
• Backporting & Multi-Version Maintenance — .backportrc.json indicates Solidus maintains multiple release branches; bug fixes and security patches must be applied to stable versions—workflow automation and careful version numbering prevent regressions in production stores

• spree/spree — Spiritual predecessor and inspiration; Solidus forked from Spree to create a more modular, community-governed alternative with different development philosophy
• shopware/shopware — Competing open-source e-commerce platform (PHP/Symfony) solving identical problem; useful for learning alternative architectural choices in platform design
• evershop/evershop — Modern open-source e-commerce framework (Node.js/React) targeting similar merchant use cases; shows how e-commerce logic translates to non-Rails stacks
• solidusio/solidus_cmd — Official CLI tool for Solidus; developers using Solidus will extend this for custom store setup and automation
• solidusio/solidus-starter-frontend — Reference storefront implementation showing best practices for building customer-facing Solidus apps; critical learning resource for new contributors

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 integration tests for Solidus Admin component library

The admin UI has grown significantly with many components in admin/app/components/solidus_admin/ but there's no visible test coverage for the component rendering and interactions. New contributors could add Jest/system tests for key components like adjustment_reasons, state_blueprint, and the slotable_default concern to ensure consistent behavior across the admin interface.

• [ ] Create admin/spec/components or admin/test/components directory structure
• [ ] Add tests for admin/app/components/solidus_admin core components (start with 3-5 high-value ones)
• [ ] Add Jest configuration to admin/package.json if needed for JavaScript component testing
• [ ] Reference existing test patterns in the main solidus core tests and apply to admin components
• [ ] Document component testing approach in admin/README.md

Implement missing workflow for Solidus Admin npm package release

The admin directory appears to be a separate npm package (admin/Rakefile, admin/README.md, admin/.prettierrc present) but there's no dedicated GitHub Actions workflow for publishing it to npm. Currently only solidus_installer.yml and main solidus releases are automated. Adding a workflow would streamline admin package releases and reduce manual maintenance burden.

• [ ] Create .github/workflows/release_admin.yml workflow file
• [ ] Add npm registry authentication using secrets (NPM_TOKEN)
• [ ] Implement version bumping logic from admin/package.json
• [ ] Trigger on tags matching pattern like 'admin-v*' or on release event
• [ ] Document admin release process in admin/README.md with workflow details

Add comprehensive E2E test coverage for solidus_installer workflow

The solidus_installer.yml workflow exists but there's no corresponding end-to-end test validating the complete installer flow. A new contributor could add a test workflow that actually runs the installer against a test Rails app, validates generated files, and confirms the dummy app starts successfully—catching regressions early.

• [ ] Create .github/workflows/test_installer_e2e.yml workflow
• [ ] Add steps to run solidus installer via CLI on a fresh Rails app
• [ ] Validate key generated files: config/initializers/solidus.rb, Gemfile modifications
• [ ] Add startup validation: run 'rails server' health check or 'rails db:setup'
• [ ] Document installer E2E testing approach in a new INSTALLER_TESTING.md guide

• The /admin directory has a separate JavaScript build pipeline with .prettierrc—audit and document the admin asset build process in CONTRIBUTING.md, as it's not obvious that npm run build is required after admin JS changes.
• Review core/spec/ test coverage for payment processing models (look for spree/payment.rb tests)—many e-commerce edge cases (partial refunds, processor failures) often lack test scenarios; add specs for uncovered branches.
• The .github/actions/ directory has custom GitHub Actions (check_page_content, commit_and_submit_pull_request, etc.) with minimal inline documentation—add brief README comments to each action explaining its trigger and side effects.

Solidus appears to be a mature eCommerce framework with structured code organization and CI/CD pipelines. However, the security assessment is limited by incomplete information (no dependencies provided). Key concerns include: (1) inability to identify vulnerable dependencies without package files, (2) insufficient visibility into authentication/authorization mechanisms critical for eCommerce, (3) potential XSS risks in admin UI components requiring template review, and (4) GitHub Actions workflow security. The framework should implement comprehensive security testing (SAST), dependency scanning, and regular security audits given its role in handling sensitive payment and customer data. Recommend using brakeman for Rails security analysis and bundler-audit for dependency scanning.

• Medium · Missing Dependency Information — Gemfile, Gemfile.lock, package.json (not provided). No dependency/package file content was provided for analysis. This prevents identification of known vulnerable dependencies, outdated libraries, or supply chain risks that could affect the Solidus eCommerce framework. Fix: Provide Gemfile, Gemfile.lock, and any package.json files for dependency scanning using tools like bundler-audit, brakeman, or npm audit.
• Medium · Limited Visibility into Authentication/Authorization Implementation — app/controllers, app/models (authentication/authorization logic not visible). As an eCommerce platform, Solidus handles sensitive user data, payment information, and order details. The partial file structure provided doesn't show authentication/authorization implementation details, making it difficult to assess security controls. Fix: Conduct thorough review of authentication mechanisms (devise or similar), authorization checks, and access control lists. Ensure proper role-based access control (RBAC) for admin and customer areas.
• Medium · Potential XSS Risks in Admin Components — admin/app/components/solidus_admin/*/component.html.erb files. The admin interface contains numerous ERB templates and Vue/JavaScript components (evidenced by .prettierrc and component files). Without reviewing the actual template content, there's risk of inadequate output encoding or unsafe use of user input. Fix: Ensure all user input is properly escaped in ERB templates. Use Rails' safe string methods, avoid raw() without sanitization, and implement Content Security Policy headers.
• Low · Docker Development Environment Security — .dockerdev/Dockerfile. A Dockerfile exists for development (.dockerdev/Dockerfile) but contents weren't provided. Development containers should not contain credentials or be configured for production-like security. Fix: Review Dockerfile for: no hardcoded secrets, minimal base images, non-root user execution, and proper separation between dev and production configurations.
• Low · GitHub Actions Workflow Security — .github/workflows/*.yml. Multiple GitHub Actions workflows are present (test.yml, prepare_release.yml, etc.). Without reviewing their content, potential risks include secrets exposure, untrusted action dependencies, or insecure CI/CD configurations. Fix: Audit all workflows for: secrets handling, use of trusted/verified actions, proper RBAC on repository, and protection of deployment credentials.
• Low · No Visible Security Policy — Root directory. While GOVERNANCE.md exists, a dedicated SECURITY.md or security policy document isn't evident in the provided structure, which is important for responsible vulnerability disclosure. Fix: Create a SECURITY.md file with vulnerability disclosure policy, supported versions, and responsible disclosure contact information.

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.