assistant 0.0.2 → 1.0.0.rc1

data/docs/examples/index.md

@@ -0,0 +1,29 @@
+---
+title: Examples
+nav_order: 5
+has_children: true
+permalink: /examples/
+---
+
+# Examples
+
+> **Status:** gallery scaffolding — each entry below ships with a
+> runnable script under `examples/<slug>/`, a writeup on this site,
+> and a regression test. See
+> [P6–P12 of the GitHub Pages plan](https://github.com/ramongr/assistant/blob/main/docs/v1/08-github-pages.md#p6p12-examples-one-pr-per-example)
+> for the per-example schedule.
+
+| Example | Demonstrates |
+| --- | --- |
+| [Rails service](rails-service.md) | Rails-shaped controller; `case service.run in { result:, status: :ok }`. |
+| [CLI handler](cli-handler.md) | `OptionParser` driving a service; exit code derived from `#status`. |
+| [Sidekiq worker](sidekiq-worker.md) | Worker class that runs a service; idempotent; logs warnings vs errors separately. |
+| [Composing services](composing-services.md) | Outer service uses `call_service` to chain two inner services; log timeline merging. |
+| [Execute callbacks](execute-callbacks.md) | `before_execute` audit logger; `around_execute` timing wrapper; failure cases. |
+| [Instrumentation notifier](instrumentation-notifier.md) | `Assistant.notifier=` wired to a fake `ActiveSupport::Notifications`-shaped sink. |
+| [RBS generator](rbs-generator.md) | Service definition → `bin/assistant-rbs --output sig` → Steep proving per-input return types. |
+
+Each example is intentionally small enough to be read in one sitting.
+Source for every script lives under
+[`examples/`](https://github.com/ramongr/assistant/tree/main/examples)
+in the repository.

data/docs/examples/instrumentation-notifier.md

@@ -0,0 +1,17 @@
+---
+title: Instrumentation notifier
+parent: Examples
+nav_order: 6
+---
+
+# Instrumentation notifier
+
+> **Status:** placeholder — ships in
+> [P11](https://github.com/ramongr/assistant/blob/main/docs/v1/08-github-pages.md#p6p12-examples-one-pr-per-example) of
+> the GitHub Pages plan.
+
+`Assistant.notifier=` wired to a fake `ActiveSupport::Notifications`-shaped sink.
+
+When the runnable script under `examples/instrumentation_notifier/` lands, this
+page will include it verbatim via Jekyll `include_relative` so the
+prose stays in lockstep with the code.

data/docs/examples/rails-service.md

@@ -0,0 +1,17 @@
+---
+title: Rails service
+parent: Examples
+nav_order: 1
+---
+
+# Rails service
+
+> **Status:** placeholder — ships in
+> [P6](https://github.com/ramongr/assistant/blob/main/docs/v1/08-github-pages.md#p6p12-examples-one-pr-per-example) of
+> the GitHub Pages plan.
+
+A Rails-shaped controller calling a service and pattern-matching on the result hash.
+
+When the runnable script under `examples/rails_service/` lands, this
+page will include it verbatim via Jekyll `include_relative` so the
+prose stays in lockstep with the code.

data/docs/examples/rbs-generator.md

@@ -0,0 +1,17 @@
+---
+title: RBS generator
+parent: Examples
+nav_order: 7
+---
+
+# RBS generator
+
+> **Status:** placeholder — ships in
+> [P12](https://github.com/ramongr/assistant/blob/main/docs/v1/08-github-pages.md#p6p12-examples-one-pr-per-example) of
+> the GitHub Pages plan.
+
+Service definition → `bin/assistant-rbs --output sig` → Steep proving the per-input return type.
+
+When the runnable script under `examples/rbs_generator/` lands, this
+page will include it verbatim via Jekyll `include_relative` so the
+prose stays in lockstep with the code.

data/docs/examples/sidekiq-worker.md

@@ -0,0 +1,17 @@
+---
+title: Sidekiq worker
+parent: Examples
+nav_order: 3
+---
+
+# Sidekiq worker
+
+> **Status:** placeholder — ships in
+> [P8](https://github.com/ramongr/assistant/blob/main/docs/v1/08-github-pages.md#p6p12-examples-one-pr-per-example) of
+> the GitHub Pages plan.
+
+A background job that runs a service idempotently, logging warnings vs errors separately.
+
+When the runnable script under `examples/sidekiq_worker/` lands, this
+page will include it verbatim via Jekyll `include_relative` so the
+prose stays in lockstep with the code.

data/docs/getting-started.md

@@ -0,0 +1,136 @@
+---
+title: Getting started
+nav_order: 1
+---
+
+<!-- markdownlint-disable MD013 MD024 -->
+# Getting started
+
+> **TL;DR** — Subclass `Assistant::Service`, declare your inputs with
+> `input`, write an `execute` body, and call `YourService.run(**args)`.
+> You always get a hash back: either
+> `{ result:, status: :ok | :with_warnings, warnings: [...] }` or
+> `{ result: nil, status: :with_errors, errors: [...] }`. The gem
+> never raises for expected failures.
+
+This page walks a brand-new user from `gem install` to a working
+service. For deeper topics, jump to the guides:
+
+- [Inputs](./guides/inputs.md) — every option on `input` and `inputs`.
+- [Validation](./guides/validation.md) — the `validate` hook and how
+  to log warnings vs. errors.
+- [Logging and results](./guides/logging-and-results.md) — `LogItem`,
+  the `log_item_*` shorthands, the result hash.
+- [Composing services](./guides/composing-services.md) — `call_service`,
+  callbacks, the instrumentation notifier, `#input_snapshot`.
+
+The API contract is enumerated in
+[`api-reference.md`](./api-reference.md).
+
+## Install
+
+With Bundler (recommended):
+
+```sh
+bundle add assistant
+```
+
+Without Bundler:
+
+```sh
+gem install assistant
+```
+
+Ruby `>= 3.4` is required. The gem has **zero runtime dependencies** —
+adding it never pulls in another gem.
+
+## Your first service
+
+Create a file `create_user.rb`:
+
+```ruby
+require 'assistant'
+
+class CreateUser < Assistant::Service
+  input :email, type: String,  required: true
+  input :name,  type: String,  required: true
+  input :age,   type: Integer, allow_nil: true, default: nil
+
+  def validate
+    return if email.include?('@')
+
+    log_item_error(source: :validate, detail: :email, message: 'must contain @')
+  end
+
+  def execute
+    log_item_warning(source: :execute, detail: :age, message: 'age missing') if age.nil?
+
+    { id: 42, email:, name:, age: }
+  end
+end
+```
+
+Run it:
+
+```ruby
+CreateUser.run(email: 'a@b.com', name: 'Alice')
+# => { result: { id: 42, email: "a@b.com", name: "Alice", age: nil },
+#      status: :with_warnings,
+#      warnings: [#<Assistant::LogItem level=:warning ...>] }
+
+CreateUser.run(email: 'oops', name: 'Bob', age: 30)
+# => { result: nil,
+#      status: :with_errors,
+#      errors: [#<Assistant::LogItem level=:error  ...>,
+#               #<Assistant::LogItem level=:error  ...>] }
+
+CreateUser.run(email: 'c@d.com', name: 'Carol', age: 30)
+# => { result: { id: 42, ... }, status: :ok, warnings: [] }
+```
+
+Three runs, three different statuses, **zero exceptions**.
+
+## Reading the result hash
+
+Every `Service.run` returns one of two shapes:
+
+```ruby
+# Success (status is :ok or :with_warnings)
+{ result: <Object>, status: :ok | :with_warnings, warnings: Array<LogItem> }
+
+# Failure
+{ result: nil, status: :with_errors, errors: Array<LogItem> }
+```
+
+Pattern-matching is the cleanest way to consume it:
+
+```ruby
+case CreateUser.run(email: 'a@b.com', name: 'Alice')
+in { result:, status: :ok }
+  render json: result
+in { result:, status: :with_warnings, warnings: }
+  WarningsLogger.log(warnings)
+  render json: result
+in { errors:, status: :with_errors }
+  render json: { errors: errors.map(&:item) }, status: :unprocessable_entity
+end
+```
+
+The `:status` value is exhaustively one of `:ok`, `:with_warnings`,
+`:with_errors`. No new status values can be introduced in 1.x without a
+deprecation cycle.
+
+## What's next
+
+- The same example, but with optional / multi-type inputs and a
+  `default:` lambda → [Inputs guide](./guides/inputs.md).
+- Logging structured warnings during `#execute`, conditional
+  validation, the strict `LogItem` constructor →
+  [Logging and results](./guides/logging-and-results.md) +
+  [Validation](./guides/validation.md).
+- Wrapping one service inside another with shared log merging →
+  [Composing services](./guides/composing-services.md).
+- Per-class RBS signatures for Steep users → run
+  `bundle exec assistant-rbs lib --output sig`. See the
+  [Inputs guide](./guides/inputs.md) for the limitation it works
+  around.

data/docs/guides/composing-services.md

@@ -0,0 +1,222 @@
+---
+title: Composing services
+parent: Guides
+nav_order: 4
+---
+
+<!-- markdownlint-disable MD013 MD024 -->
+# Composing services
+
+> **TL;DR** — Use `call_service(OtherService, **inputs)` to nest one
+> service inside another's `#execute`; logs from the inner service
+> are merged into the outer timeline automatically. Use
+> `before_execute` / `after_execute` / `around_execute` to share
+> cross-cutting concerns at the class level. Register
+> `Assistant.notifier =` once to instrument every service. Use
+> `#input_snapshot` to forward a read-only view of the inputs to a
+> collaborator.
+
+This guide covers the four composition surfaces shipped in 1.0:
+service-to-service calls (M-S2), execute callbacks (M-S1), the
+instrumentation notifier (M-S3), and the input snapshot (M-S4).
+
+## `#call_service`: nest one service inside another
+
+`call_service(klass, **inputs)` instantiates `klass`, runs it, merges
+its `#logs` into the outer service's timeline, and returns the inner
+service instance. It does **not** raise on inner failure — the
+outer `#execute` decides what to do based on `inner.success?` /
+`inner.failure?` / `inner.result`.
+
+```ruby
+class CreateUser < Assistant::Service
+  input :email, type: String, required: true
+  def execute = { id: 1, email: }
+end
+
+class SignUp < Assistant::Service
+  input :email, type: String, required: true
+
+  def execute
+    user = call_service(CreateUser, email:)
+    return if user.failure? # inner errors already on the outer timeline
+
+    { user: user.result, signed_up_at: Time.now }
+  end
+end
+
+result = SignUp.run(email: 'a@b.com')
+result.fetch(:status)              # => :ok
+result.fetch(:result)[:user][:id]  # => 1
+```
+
+Notes:
+
+- `klass` must be a subclass of `Assistant::Service`. Anything else
+  raises `ArgumentError`.
+- The inner service's `#logs` are appended to the outer service's
+  timeline via `merge_logs(logs: inner.logs)`. Because the outer
+  service's `errors` / `warnings` / `status` are derived from its
+  full `@logs`, inner errors **automatically** downgrade the outer
+  terminal status to `:with_errors`, and inner warnings surface as
+  `:with_warnings` — no special handling required.
+- `call_service` does **not** rescue exceptions raised by the inner
+  service's `#execute` (or by the configured `Assistant.notifier`).
+  Wrap in `begin/rescue` and record via `add_log(level: :error, ...)`
+  if the inner service may raise.
+- `call_service` always calls `inner.run`, so calling it twice would
+  re-execute the inner service.
+
+## Execute callbacks (M-S1)
+
+Three class-level DSL methods register callbacks around `#execute`.
+Hooks are evaluated in the context of the service instance.
+
+```ruby
+class CreateUser < Assistant::Service
+  input :email, type: String, required: true
+
+  before_execute do
+    log_item_info(source: :hook, detail: :before, message: "starting #{email}")
+  end
+
+  around_execute do |&blk|
+    started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    value = blk.call
+    log_item_info(source: :hook, detail: :around,
+                  message: "took #{Process.clock_gettime(Process::CLOCK_MONOTONIC) - started}s")
+    value
+  end
+
+  after_execute do |result|
+    log_item_info(source: :hook, detail: :after, message: "result=#{result.inspect}")
+  end
+
+  def execute = { id: 1, email: }
+end
+```
+
+Behavior:
+
+- **Order:** `before_execute` hooks run in declaration order; then
+  `around_execute` hooks wrap the chain with the **first-declared**
+  hook as the outermost layer; finally `after_execute` hooks run
+  with the execute result as the single positional argument.
+- **Inheritance:** subclasses inherit a `dup` of each parent's hook
+  arrays. Adding hooks in a subclass does not affect the parent.
+- **Exceptions:** a `StandardError` raised inside any hook is logged
+  with `level: :error, source: :hook, detail: <hook_type>` and the
+  remaining hooks still fire. An `around_execute` hook that raises
+  before yielding to its continuation produces `nil` for that layer
+  and outer hooks still wrap normally.
+- **Missing block:** registering a hook without a block raises
+  `ArgumentError` at class-definition time.
+
+## Instrumentation notifier (M-S3)
+
+Assign a callable to `Assistant.notifier =` to receive a fixed set
+of events for **every** service execution:
+
+```ruby
+Assistant.notifier = lambda do |event, payload|
+  StatsD.increment("assistant.#{event}",
+                   tags: ["service:#{payload[:service_class]}"])
+  StatsD.timing("assistant.duration_s.#{event}",
+                payload[:duration_s] * 1000.0,
+                tags: ["service:#{payload[:service_class]}"])
+end
+```
+
+Events (frozen for 1.0):
+
+| Event                | When                                            |
+|----------------------|-------------------------------------------------|
+| `:service_started`   | Top of `#run`, before any validation.           |
+| `:service_validated` | After declarative + `#validate` checks pass.    |
+| `:service_executed`  | Success path — after `#execute` returns.        |
+| `:service_failed`    | Failure path — `#execute` was skipped.          |
+
+Payload always includes:
+
+- `:service_class` — the `Service` subclass.
+- `:duration_s` — Float seconds since the start of `#run`
+  (`Process::CLOCK_MONOTONIC`).
+
+The notifier is treated as untrusted infrastructure: any
+`StandardError` it raises is rescued and warned (`Kernel.warn`),
+so a misconfigured notifier cannot tear down every service in the
+process. `SystemExit` / `Interrupt` propagate.
+
+To disable instrumentation entirely, restore the default no-op:
+
+```ruby
+Assistant.notifier = Assistant::DEFAULT_NOTIFIER
+```
+
+## `#input_snapshot` (M-S4)
+
+`#input_snapshot` returns a read-only `Data` view of the service's
+declared inputs (post-`default:` / post-`allow_nil:`). It's the
+canonical way to hand a value object to a collaborator without
+exposing the full service instance:
+
+```ruby
+class CreateUser < Assistant::Service
+  input :email, type: String, required: true
+  input :role,  type: Symbol, default: :member
+
+  def execute
+    Mailer.welcome(input_snapshot)
+    { id: 1, **input_snapshot.to_h }
+  end
+end
+
+snapshot = CreateUser.new(email: 'a@b.com').tap(&:run).input_snapshot
+snapshot.email # => "a@b.com"
+snapshot.role  # => :member
+snapshot.to_h  # => { email: "a@b.com", role: :member }
+
+snapshot.email = 'x' # => NoMethodError (Data is structurally immutable)
+```
+
+Notes:
+
+- Members are exactly the keys of `input_definitions` — extra keyword
+  arguments to `#initialize` that have no `input` declaration are
+  excluded so the snapshot mirrors the public DSL.
+- A declared input with no default and no caller-supplied value
+  appears with `nil`, mirroring the per-input getter.
+- The snapshot class is memoized at the class level via
+  `Service.input_snapshot_class`, so repeated calls are cheap.
+- `Data` is structurally immutable. Mutable member values (an
+  `Array` passed as an input, say) keep their normal mutability —
+  the snapshot does not deep-freeze.
+
+## Common pitfalls
+
+- **Forgetting that `call_service` doesn't fail the outer service.**
+  If the inner failure should also fail the outer, check
+  `inner.failure?` (or `inner.errors.any?`) and call
+  `log_item_error(...)` in your `#execute`.
+- **Re-running `inner` after `call_service`.** `inner.run` was
+  already called; calling it again will re-execute and double-log.
+- **Mutating `#input_snapshot` member values.** They share identity
+  with the underlying inputs. Treat the snapshot as a view, not a
+  defensive copy.
+- **Putting validation in `before_execute`.** Use `#validate` — it
+  short-circuits `#execute` on errors. Hooks log but don't change
+  flow.
+- **Raising from a notifier.** It's swallowed (with a `warn`).
+  Non-`StandardError` exceptions still propagate, so don't use
+  `Kernel#exit`.
+
+## See also
+
+- [Inputs guide](./inputs.md) — `Service.input` / `Service.inputs`
+  and `#input_snapshot`.
+- [Validation guide](./validation.md) — `#validate`, conditional
+  requirements.
+- [Logging and results](./logging-and-results.md) — what
+  `merge_logs(logs:)` does, the result hash shape.
+- [API reference](../api-reference.md#assistantservice) for the
+  full callback / call_service / notifier surfaces.

data/docs/guides/index.md

@@ -0,0 +1,25 @@
+---
+title: Guides
+nav_order: 2
+has_children: true
+permalink: /guides/
+---
+
+# Guides
+
+Topic-focused walkthroughs of every part of the Assistant DSL.
+Each guide opens with a TL;DR, ships runnable examples mirrored by
+tests under `test/docs/<guide>_examples_test.rb`, and ends with a
+"common pitfalls" + "see also" section.
+
+- [Inputs](./inputs.md) — `input`/`inputs` DSL, `type:`, `required:`,
+  `default:`, `allow_nil:`, `optional:`, `if:` conditional requirement,
+  and the `assistant-rbs` Steep recipe.
+- [Validation](./validation.md) — auto-checks, `#validate`, warnings
+  vs errors, conditional requirements, strict `LogItem.new` (M10).
+- [Logging and results](./logging-and-results.md) — `LogItem`,
+  levels, `log_item_*` shorthands, `merge_logs`, the result hash.
+- [Composing services](./composing-services.md) — `call_service`,
+  callbacks, the notifier, `#input_snapshot`.
+- [RBS and types](./rbs-and-types.md) — per-class generator, the R1
+  metaprogramming limitation, Steep CI hookup.