diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 000000000..9130a0ae2 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,56 @@ +# Contributing to agent-ruby + +Thanks for helping improve the Forest Ruby agent. This guide covers how to report an issue, set up the repository, and get a pull request merged. + +## Before you start + +- **Found a bug?** Open an issue with the template: expected behavior, actual behavior, logs, and the gem versions you use. +- **Found a security issue?** Do not open a public issue. Follow the [security policy](https://github.com/ForestAdmin/.github/blob/main/SECURITY.md). +- **Planning a large change?** Open an issue first to discuss it, so your work fits the agent's direction before you write it. + +## Setup + +This monorepo holds one gem per folder in [`packages/`](./packages). Ruby `>= 3.0` is required. + +```bash +bundle install +``` + +A complete demo application lives in [`packages/_examples/demo`](./packages/_examples/demo) to try your changes end to end. + +## Tests and lint + +Tests run per package: + +```bash +cd packages/ +BUNDLE_GEMFILE=Gemfile-test bundle install +BUNDLE_GEMFILE=Gemfile-test bundle exec rspec --color --format doc +``` + +Lint, from the repository root: + +```bash +bundle exec rubocop +``` + +Tests must pass and RuboCop must be clean before you open a pull request. + +## Commit messages + +Commits follow the [Conventional Commits](https://www.conventionalcommits.org/) specification, checked by the Overcommit hook (`(): `). Releases and changelogs are generated from them, so the type matters: + +- `fix(datasource_active_record): handle null dates` → patch release +- `feat(agent): add the X option` → minor release +- `docs: ...`, `test: ...`, `chore: ...` → no release + +## Pull requests + +1. Fork the repository and create a branch from `main`. +2. Make your change, with tests. +3. Give the pull request a Conventional Commits title and fill in the template checklist. +4. The CI must be green. The Forest team reviews every pull request before merging. + +## Code of conduct + +Everyone taking part in this project is expected to follow the [code of conduct](https://github.com/ForestAdmin/.github/blob/main/CODE_OF_CONDUCT.md). diff --git a/README.md b/README.md index 784685372..2cff46a99 100644 --- a/README.md +++ b/README.md @@ -1,166 +1,121 @@ -# Forest Admin agent Ruby - - -Forest Admin provides an off-the-shelf administration panel based on a highly-extensible API plugged into your application. - -This project has been designed with scalability in mind to fit requirements from small projects to mature companies. - -## Who Uses Forest Admin - -- [Apartmentlist](https://www.apartmentlist.com) -- [Carbon Health](https://carbonhealth.com) -- [Ebanx](https://www.ebanx.com) -- [First circle](https://www.firstcircle.ph) -- [Forest Admin](https://www.forestadmin.com) of course :-) -- [Heetch](https://www.heetch.com) -- [Lunchr](https://www.lunchr.co) -- [Pillow](https://www.pillow.com) -- [Qonto](https://www.qonto.eu) -- [Shadow](https://shadow.tech) -- And hundreds more… - -## Getting started - -[https://docs.forestadmin.com/documentation/how-tos/setup/install](https://docs.forestadmin.com/documentation/how-tos/setup/install) - -## Documentation - -[https://docs.forestadmin.com/documentation/](https://docs.forestadmin.com/documentation/) - -## How it works - -

- Howitworks +

+ + + Forest agent for Ruby: your data, workflows and AI agents, running on your infrastructure. +

-Forest Admin consists of two components: - -- The Admin Frontend is the user interface where you'll manage your data and configuration. -- The Admin Backend API hosted on your servers where you can find and extend your data models and all the business logic (routes, actions, …) related to your admin panel. - -The Forest Admin package (aka Forest Liana) introspects all your data model -and dynamically generates the Admin API hosted on your servers. The Forest Admin -interface is a web application that handles communication between the admin -user and your application data through the Admin API. - -## Features - -### CRUD - -All of your CRUD operations are natively supported. The API automatically -supports your data models' validation and allows you to easily extend or -override any API routes' with your very own custom logic. - -CRUD - -### Search & Filters - -Forest Admin has a built-in search allowing you to run basic queries to -retrieve your application's data. Set advanced filters based on fields and -relationships to handle complex search use cases. - -Search and Filters - -### Sorting & Pagination - -Sorting and pagination features are natively handled by the Admin API. We're -continuously optimizing how queries are run in order to display results faster -and reduce the load of your servers. - -Sorting and Pagination - -### Custom action - -A custom action is a button which allows you to trigger an API call to execute -a custom logic. With virtually no limitations, you can extend the way you -manipulate data and trigger actions (e.g. refund a customer, apply a coupon, -ban a user, etc.) - -Custom action - -### Export - -Sometimes you need to export your data to a good old fashioned CSV. Yes, we -know this can come in handy sometimes :-) - -Export - -### Segments - -Get in app access to a subset of your application data by doing a basic search -or typing an SQL query or implementing an API route. +

+ gem + CI + License +

-Segments +**Forest is the back office for operations teams in regulated companies.** Ops teams review, decide and act on your data from one interface, or let AI agents do it, within the roles, permissions and audit logs you define. -### Dashboards +This repository is the **Ruby agent**: the part of Forest that runs inside your Rails application, connects to your databases and services, and exposes them to the Forest interface. Your business data never goes through Forest. -Forest Admin is able to tap into your actual data to chart out your metrics -using a simple UI panel, a SQL query or a custom API call. +> [!NOTE] +> **Forest v2.** This is the current Ruby SDK. Using the `forest_liana` gem? You are on v1: see [forest-rails](https://github.com/ForestAdmin/forest-rails) and the [migration guide](https://docs.forest.app/guides/migration/from-v1/overview). -Dashboard +## Quick start -### WYSIWYG +```ruby +# Gemfile +gem 'forest_admin_rails' +``` -The WYSIWYG interface saves you a tremendous amount of frontend development -time using drag'n'drop as well as advanced widgets to build customizable views. +```bash +bundle install +bundle exec rails generate forest_admin_rails:install +``` -WYSIWYG +The generator mounts the engine, and creates the initializer and the agent entry point: -### Custom HTML/JS/CSS +```ruby +# config/initializers/forest_admin_rails.rb +ForestAdminRails.configure do |config| + config.auth_secret = ENV['FOREST_AUTH_SECRET'] + config.env_secret = ENV['FOREST_ENV_SECRET'] +end +``` -Code your own views using JS, HTML, and CSS to display your application data in -a more appropriate way (e.g. Kanban, Map, Calendar, Gallery, etc.). +```ruby +# lib/forest_admin_rails/create_agent.rb +module ForestAdminRails + class CreateAgent + def self.setup! + database_configuration = Rails.configuration.database_configuration + datasource = ForestAdminDatasourceActiveRecord::Datasource.new(database_configuration[Rails.env]) -Custom views + @create_agent = ForestAdminAgent::Builder::AgentFactory.instance.add_datasource(datasource) + customize + @create_agent.build + end -### Team-based permissions + def self.customize + # Add computed fields, actions, segments and hooks here + end + end +end +``` -Without any lines of code, manage directly from the UI who has access or can -act on which data using a team-based permission system. +Environment variables: `FOREST_ENV_SECRET`, `FOREST_AUTH_SECRET`, and `FOREST_SERVER_URL` if you target a dedicated instance. +Full guide: [docs.forest.app/get-started/quickstart](https://docs.forest.app/get-started/quickstart) -Team based permissions +## Requirements -### Third-party integrations +| | | +|---|---| +| Ruby | `>= 3.0` (CI tests 3.4 and 4.0) | +| Rails | `>= 6.1` | -Leverage data from third-party services by reconciling it with your -application’s data and providing it directly to your Admin Panel. All your -actions can be performed at the same place, bringing additional intelligence to -your Admin Panel and ensuring consistency. +## What the agent gives you -Third-party integrations +| | | +|---|---| +| **Data** | ActiveRecord, Mongoid, Snowflake, Zendesk, GraphQL/Hasura, Mambu, Pylon, RPC: one data source package per source. | +| **Customization** | Computed fields, actions, segments, hooks and relationships through `forest_admin_datasource_customizer`. | +| **Permissions and audit** | Roles, scopes and activity logs defined in Forest, enforced on every request. | +| **Testing** | `forest_admin_test_toolkit` to test your customizations. | -### Notes & Comments +## How it works -Assign your teammates to specific tasks, leave a note or simply comment a -record, thereby simplifying collaboration all across your organization. + + + The Ruby agent runs on your infrastructure. Forest calls it over HTTPS; the agent queries your databases and services. + -Notes and Comments +The agent runs **on your infrastructure**. The Forest interface calls your agent, and your agent queries your sources: Forest does not store your business data. -### Activity logs +## Documentation -Monitor each action executed and follow the trail of modification on any data -with an extensive activity log system. +| | | +|---|---| +| Get started | https://docs.forest.app/get-started/quickstart | +| Connect a data source | https://docs.forest.app/get-started/connect/data-sources/overview | +| Ruby API reference | https://docs.forest.app/reference/agent-api/ruby | +| Migrating from v1 | https://docs.forest.app/guides/migration/from-v1/overview | -Activity logs +
+Packages in this monorepo -## How to contribute +`forest_admin_rails` · `forest_admin_agent` · `forest_admin_rpc_agent` · `forest_admin_datasource_toolkit` · `forest_admin_datasource_customizer` · `forest_admin_datasource_active_record` · `forest_admin_datasource_mongoid` · `forest_admin_datasource_snowflake` · `forest_admin_datasource_zendesk` · `forest_admin_datasource_graphql_hasura` · `forest_admin_datasource_mambu_payments` · `forest_admin_datasource_pylon` · `forest_admin_datasource_rpc` · `forest_admin_test_toolkit` -This repository is officially maintained by Forest Admin. -We're always happy to get contributions for other fellow lumberjacks. -All contributions will be reviewed by Forest Admin's team before being merged into main. +A complete demo application lives in [`packages/_examples/demo`](./packages/_examples/demo). -Here is the contribution workflow: +
-1. **Fork** the repo on GitHub -2. **Clone** the project to your own machine -3. **Commit** changes to your own branch -4. **Push** your work back up to your fork -5. Submit a **Pull request** so that we can review your changes +## Contributing -Please ensure that the **tests** are passing before submitting any pull request. +Bug reports and pull requests are welcome. See [CONTRIBUTING.md](./CONTRIBUTING.md) for setup, tests and commit conventions. -## Community +```bash +cd packages/ +BUNDLE_GEMFILE=Gemfile-test bundle install +BUNDLE_GEMFILE=Gemfile-test bundle exec rspec +``` -👇 Join our Developers community for support and more +## License -[![Discourse developers community](https://img.shields.io/discourse/posts?label=discourse&server=https%3A%2F%2Fcommunity.forestadmin.com)](https://community.forestadmin.com) +Apache 2.0. See [LICENSE](./LICENSE). diff --git a/assets/arch-agent-ruby-dark.svg b/assets/arch-agent-ruby-dark.svg new file mode 100644 index 000000000..a70b1a847 --- /dev/null +++ b/assets/arch-agent-ruby-dark.svg @@ -0,0 +1 @@ + diff --git a/assets/arch-agent-ruby-light.svg b/assets/arch-agent-ruby-light.svg new file mode 100644 index 000000000..baa100224 --- /dev/null +++ b/assets/arch-agent-ruby-light.svg @@ -0,0 +1 @@ + diff --git a/assets/header-agent-ruby-dark.svg b/assets/header-agent-ruby-dark.svg new file mode 100644 index 000000000..265a869ea --- /dev/null +++ b/assets/header-agent-ruby-dark.svg @@ -0,0 +1,7 @@ + + + + + + + diff --git a/assets/header-agent-ruby-light.svg b/assets/header-agent-ruby-light.svg new file mode 100644 index 000000000..a9664e058 --- /dev/null +++ b/assets/header-agent-ruby-light.svg @@ -0,0 +1,7 @@ + + + + + + +