signoff 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: daf22fb998df2e5bef0e6207a62b5a92706b25ae6d32c29b3be5ec813f5067aa
+  data.tar.gz: bc00d77c7d53a2aa56883d637d0edcc984e431593acbfbf360ba3f01fe431940
+SHA512:
+  metadata.gz: c7a29fac8c99c70171b22aac59c5b60522ff3bde67b3c81a3a58d8d66943e50d9e4f595012acdf29c7d692d8c638f8b7147af1dd397895c42d1e34f3043e3933
+  data.tar.gz: 519e9fbfd372cddf725038124762ada8dc54a0fc280dd9c566228fa2e832e854aff5147767ab3b7173eb527417ddfd153536ccaa52e1aac63e0c329cb00fc6e3

data/CHANGELOG.md

@@ -0,0 +1,79 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-06-05
+
+Initial public release. `signoff` adds concurrency-safe approval workflows
+with a complete, immutable audit trail to ActiveRecord models on Rails 7.x
+and 8.x, backed by PostgreSQL — no external services required.
+
+### Added
+
+- **Declarative workflow DSL.** `include Signoff` then declare states and
+  transitions inside a `signoff do ... end` block. DSL methods:
+  `state(name, initial: false)`, `states(*names)`, `initial_state(name)`,
+  `transition(from, to:)` (where `to:` accepts a single state or an array),
+  `reject_to(state)`, `allow_transition(from_state) { |user[, record]| }`,
+  `before_transition { |record, from, to| }`, and
+  `after_transition { |record, event| }`. The macro accepts a per-model state
+  column override via `signoff(column: :workflow_state) do ... end`.
+- **Transition methods.** `submit!`, `approve!`, and `reject!`, each accepting
+  `user:`, `comment:`, `metadata:`, `ip_address:`, and `user_agent:` keyword
+  arguments (`submit!`/`approve!` also accept `to:` for branching transitions).
+  `submit!` and `approve!` advance the single forward transition and differ only
+  in the recorded action label; `reject!` moves the record to the configured
+  `reject_to` state. Transitions run inside a transaction and roll the in-memory
+  state back if anything raises.
+- **From-state authorization guards.** `allow_transition` guards are keyed by the
+  state the record is currently in. Unauthorized attempts — including the case
+  where a guard exists but no user is supplied — raise
+  `Signoff::UnauthorizedError`. The non-raising predicates
+  `can_approve?(user = nil)` and `can_reject?(user = nil)` report whether a
+  transition is currently permitted without raising.
+- **Before/after transition callbacks.** `before_transition` runs inside the
+  transaction before the state column is written; `after_transition` runs after
+  the transaction commits with the persisted event, making it the right place to
+  enqueue ActiveJob jobs or send ActionMailer notifications.
+- **Immutable PostgreSQL JSONB audit trail.** Every transition writes a
+  `Signoff::Event` record (polymorphic `workflowable`, `user`, `action`,
+  `from_state`, `to_state`, `comment`, JSONB `metadata`, optional `ip_address`
+  and `user_agent`, `created_at`). Persisted events are read-only by default
+  (`config.immutable_events`), guaranteeing an append-only history.
+- **Audit-trail helpers.** `workflow_history` (the preloadable, chronologically
+  ordered events relation), `last_approval`, `last_rejection`, and `approved_by`
+  (the user who moved the record into a successful terminal state).
+- **State introspection.** `current_state` (returns a `Symbol`), the
+  `approved?` / `rejected?` / `pending?` predicates, and auto-generated
+  per-state predicates such as `draft?` and `manager_review?`.
+- **Query scopes.** `.approved`, `.pending`, `.rejected`, and `.in_state(*states)`,
+  all reading from the state column (the source of truth), plus the
+  `.signoff_column` and `.signoff_states` introspection
+  helpers.
+- **Rails generators.** `rails g signoff:install` creates the
+  `create_signoff_events` migration (JSONB `metadata` with supporting
+  indexes) and a `config/initializers/signoff.rb` initializer.
+  `rails g signoff:model ExpenseReport [--column=approval_state]
+  [--initial=draft]` adds an indexed state column to the target model's table.
+- **Configuration** via `Signoff.configure { |config| ... }`:
+  `user_class` (`"User"`), `track_ip_addresses` (`false`), `store_user_agent`
+  (`false`), `default_state_column` (`:approval_state`), `event_table_name`
+  (`"signoff_events"`), `validate_on_transition` (`false`), `dependent`
+  (`:delete_all`), and `immutable_events` (`true`).
+- **Request-context capture.** `Signoff::Current` (an
+  `ActiveSupport::CurrentAttributes` holding `user`, `ip_address`, and
+  `user_agent`) supplies actor and request details to transitions automatically.
+  Include `Signoff::Controller` in `ApplicationController` to populate it
+  from `current_user` and the incoming request.
+- **Typed error hierarchy** under `Signoff::Error`: `DefinitionError`,
+  `InvalidTransitionError`, `UnauthorizedError`, `NotConfiguredError`, and
+  `MissingColumnError`.
+- **Rails 7.x and 8.x support** on Ruby >= 3.2 with PostgreSQL.
+
+[Unreleased]: https://github.com/JijoBose/Signoff/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/JijoBose/Signoff/releases/tag/v0.1.0

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Jijo Bose
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.