jazari 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dcd3c77813c6290564bdaeb857e3e16ccf09381f14ed5042bec05c4c78d34af1
-  data.tar.gz: 655b4e0d33237093113ee341b02acc5f7a51b1ad16a781fa4c15faa8ce482af0
+  metadata.gz: 781a303d10e42b7e3337381b7d167aaeb227a5cf538e4122f1b37c2143216f8f
+  data.tar.gz: b6c2d6ca19ccc6d097ea30ddc644f2f58144d6fc9d6a74722e2f625c7502ba18
 SHA512:
-  metadata.gz: dd38fccf2e5720b002824294ae7a178e206d6dccef3489cc61ce953fa507f991069e69ee9ed34b15f3a8de64c29edc7cbce8d8c02dea7c3a351a2d9ce8ab3b8f
-  data.tar.gz: e163aa00ba58ef159416ca8f41360ee8bf1ad3743c1b129d61ad0e0e5cfb353111903f890545d5439e449149b9a4c2e0deda8c13b853ff3272fabff1788abfd4
+  metadata.gz: 9d42855d9257d25cb193423c6864db7451006ae2b07fe9b013442b2cf3c3c1e8f1ceca6208e5e23b1a8f60d1d57b5502ea31e5859e81734dd3a1412f0e8accd4
+  data.tar.gz: 156a565d0e8ab2b8f8f51dbb335c0410f60484da523ba9a1de6fd216bf3377f720cc3909722bed78f3854b5a836ea126a89106831e57c7c3ac9fa160802731f9

data/CHANGELOG.md

@@ -8,6 +8,30 @@ codes, the resolved-value shape, how revisions are computed, and the schema the
 generator emits — changes to any of those are breaking even when the method
 signatures do not move.
 
+## [0.2.0] - 2026-08-10
+
+### Added
+
+- **`Jazari::Mcp::Actions`** — every action declared as data (`scope`, `effect`,
+  `confirm`, parameter schemas, summary), with `schema_fragment` for merging into
+  a host's own MCP tool. A host with an existing MCP surface keeps its tool name,
+  envelope, dispatch, and permissions, and calls `Jazari.*` directly — no
+  coupling to this gem's handler or reply shape.
+- `Jazari::Mcp::Actions.summaries` for a tool description or paired skill.
+
+### Changed
+
+- **The MCP layer is now genuinely optional.** Descriptors load with the gem;
+  the dispatcher does not. `require "jazari/mcp/handler"` to opt in.
+- `Mcp::Handler` validates and scopes against the same declarations, so a
+  published schema and the implemented behaviour cannot drift. A test asserts the
+  handler dispatches every declared action.
+
+### Fixed
+
+- `mcp/handler.rb` now requires `mcp/actions`. With the layer opt-in, a host
+  requiring the handler alone would have raised `NameError`.
+
 ## [0.1.0] - 2026-08-10
 
 First release. Proven against one host adoption.

data/README.md

@@ -10,6 +10,14 @@ Requires Ruby 3.2+, Rails 7.1+, and PostgreSQL.
 
 ---
 
+## Guides
+
+The README is the pitch; the [guides](guide/) are the working documents —
+[concepts](guide/01-concepts.md) (start here: one word means something
+different than you expect), [adoption](guide/02-adoption.md),
+[anchors](guide/03-anchors.md), [runs and evidence](guide/04-runs.md),
+[MCP](guide/05-mcp.md), and [migrating an existing checklist](guide/06-migrating.md).
+
 ## The problem
 
 You have a procedure. Verify a backup by restoring it. Provision a server.
@@ -221,34 +229,19 @@ out of coverage.
 ## What this is not
 
 Not an execution framework. Jazari holds the *state* of a procedure — the canon,
-the overrides, the runs, the evidence. It does not SSH anywhere or run your
-commands.
-
-For the execution half, see [braintree/runbook](https://github.com/braintree/runbook):
-a Ruby DSL for running operational procedures, with resumable state and a dry-run
-mode. It has no data model; Jazari has no executor. They compose.
-
-## Why "Jazari"
-
-Ismail **al-Jazari** (1136–1206), engineer at the Artuqid court in Diyarbakır,
-built programmable automata — a hand-washing machine that offered you a towel,
-a clock driven by a water wheel, pumps with the earliest known crankshafts.
-
-That is not why the gem carries his name.
-
-He also wrote *The Book of Knowledge of Ingenious Mechanical Devices*, finished
-the year he died: fifty machines, each with numbered construction steps and
-drawings detailed enough that a stranger who had never met him could rebuild the
-device. He wrote down the *procedure*, not just the result — including, in his
-own words, the steps he had gotten wrong first.
-
-Eight hundred years later people have built working machines from those pages.
-
-That is the whole idea here. A procedure is not lore in someone's head or prose
-in a document nobody opens. It is a written, versioned, checkable artefact that
-somebody else can execute and prove they executed.
-
-`runbook` was taken on RubyGems — by the execution framework above, fittingly.
+the overrides, the runs, the evidence. It does not SSH anywhere, shell out, or
+run your commands.
+
+That boundary is deliberate. Execution is already well served by whatever you
+have — CI, a rake task, Ansible, a deploy tool — and those differ per shop.
+What none of them keep is a durable, checkable, addressable record of *which
+procedure* was run, by whom, and what came back. Jazari keeps that, and stays
+out of the way of however you actually run things.
+
+(The name `runbook` was already taken on RubyGems, by a DSL for executing
+operational procedures. That gem's last release was 2021 and its last commit
+2022, so it is not a dependency worth taking — but the name is still occupied,
+which is one reason this gem is called jazari.)
 
 ## License
 

data/lib/jazari/mcp/actions.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+module Jazari
+  module Mcp
+    # Declarative descriptors for every action, so a host can absorb jazari into
+    # ITS OWN tool instead of adopting this gem's handler.
+    #
+    # Without these, a host has two bad choices: take `Mcp::Handler`'s reply
+    # shape wholesale, or hand-write the action list and let it drift from the
+    # gem it describes. Neither is acceptable for a host that already has an
+    # MCP surface with its own envelope, naming, and permission model.
+    #
+    # These descriptors are the single source of truth: `Handler` validates and
+    # scopes against them too, so the schema a host publishes and the behaviour
+    # the gem implements cannot diverge.
+    module Actions
+      # effect drives how a host should annotate the action to its clients:
+      #   :read        — no writes
+      #   :additive    — writes, but cannot destroy prior state
+      #   :overwrite   — may replace an operator's content; annotate cautiously
+      #   :destructive — removes something; gate it
+      Action = Data.define(:name, :scope, :effect, :summary, :params, :confirm) do
+        def read? = scope == :read
+        def confirm? = confirm == true
+        def to_h = { name: name, scope: scope, effect: effect, summary: summary,
+                     params: params, confirm: confirm }
+      end
+
+      REVISION = { type: "string",
+                   description: "The revision from the read immediately before this call." }.freeze
+      ITEM_ID  = { type: "string", description: "Opaque checklist item id." }.freeze
+      RUN_ID   = { type: "integer", description: "The run returned by start." }.freeze
+      ACTOR    = { type: "string", description: "Opaque identity of who is acting." }.freeze
+
+      ALL = [
+        Action.new(name: "get", scope: :read, effect: :read, confirm: false,
+                   summary: "Resolve the operating procedure for a target, with progress and last run.",
+                   params: {}),
+        Action.new(name: "last_run", scope: :read, effect: :read, confirm: false,
+                   summary: "The most recent run for a target — answers whether the ritual actually happened.",
+                   params: {}),
+        Action.new(name: "set", scope: :write, effect: :overwrite, confirm: false,
+                   summary: "Replace this subject's procedure. Materialises an override on first use.",
+                   params: { expected_revision: REVISION,
+                             topic: { type: "string", description: "Short title." },
+                             description: { type: "string", description: "Markdown body." },
+                             checklist: { type: "array", description: "Full checklist; replaces the existing one." } }),
+        Action.new(name: "add_item", scope: :write, effect: :additive, confirm: false,
+                   summary: "Append one checklist step.",
+                   params: { expected_revision: REVISION,
+                             text: { type: "string", description: "The step." },
+                             required: { type: "boolean", description: "Whether the step is required. Default true." } }),
+        Action.new(name: "remove_item", scope: :write, effect: :destructive, confirm: false,
+                   summary: "Delete one checklist step.",
+                   params: { expected_revision: REVISION, item_id: ITEM_ID }),
+        Action.new(name: "check_item", scope: :write, effect: :additive, confirm: false,
+                   summary: "Mark a step done or not done.",
+                   params: { expected_revision: REVISION, item_id: ITEM_ID,
+                             done: { type: "boolean", description: "Default true." } }),
+        Action.new(name: "reset", scope: :write, effect: :destructive, confirm: true,
+                   summary: "Discard this subject's override and reveal the current canon.",
+                   params: { expected_revision: REVISION,
+                             confirm: { type: "boolean", description: "Must be true — this discards operator content." } }),
+        Action.new(name: "start", scope: :write, effect: :additive, confirm: false,
+                   summary: "Open a run. Under a once-per-day recipe this returns the existing run instead of erroring.",
+                   params: { actor_ref: ACTOR }),
+        Action.new(name: "tick", scope: :write, effect: :additive, confirm: false,
+                   summary: "Record a step done within a run. Does not touch the subject's own checklist.",
+                   params: { run_id: RUN_ID, expected_revision: REVISION, item_id: ITEM_ID,
+                             done: { type: "boolean", description: "Default true." },
+                             actor_ref: ACTOR,
+                             note: { type: "string", description: "Optional free text." } }),
+        Action.new(name: "evidence", scope: :write, effect: :additive, confirm: false,
+                   summary: "Attach evidence to a run: output, url, sha, count, or note.",
+                   params: { run_id: RUN_ID, expected_revision: REVISION, item_id: ITEM_ID,
+                             kind: { type: "string", description: "One of: output, url, sha, count, note." },
+                             value: { type: "string", description: "The evidence itself." } }),
+        Action.new(name: "finish", scope: :write, effect: :additive, confirm: false,
+                   summary: "Close a run with an outcome: completed, abandoned, or failed.",
+                   params: { run_id: RUN_ID, expected_revision: REVISION,
+                             outcome: { type: "string", description: "completed | abandoned | failed" } })
+      ].freeze
+
+      NAMES = ALL.map(&:name).freeze
+
+      module_function
+
+      # scope: :read advertises only the read-only subset. A read-scoped
+      # connection should not SEE mutations in its tool list — offering them and
+      # then refusing is a worse experience than not offering them.
+      def all(scope: :write)
+        scope.to_s == "read" ? ALL.select(&:read?) : ALL
+      end
+
+      def names(scope: :write) = all(scope: scope).map(&:name)
+
+      def fetch(name)
+        ALL.find { |action| action.name == name.to_s } or
+          raise ArgumentError, "unknown runbook action #{name.inspect}"
+      end
+
+      # A fragment a host merges into its OWN tool's input schema. It deliberately
+      # returns only the action enum and the parameter properties — the host owns
+      # the tool name, the description, its own target params, and its reply
+      # envelope. Nothing here presumes this gem's handler is in the loop.
+      #
+      #   frag = Jazari::Mcp::Actions.schema_fragment
+      #   MY_TOOL[:input_schema][:properties].merge!(frag[:properties])
+      #   MY_TOOL[:input_schema][:properties][:action][:enum] += frag[:enum]
+      def schema_fragment(scope: :write)
+        actions = all(scope: scope)
+        properties = actions.each_with_object({}) do |action, acc|
+          action.params.each { |key, spec| acc[key] ||= spec }
+        end
+        { enum: actions.map(&:name), properties: properties }
+      end
+
+      # Human-readable action list for a tool description or a paired skill.
+      def summaries(scope: :write)
+        all(scope: scope).map { |a| "#{a.name} — #{a.summary}" }
+      end
+    end
+  end
+end

data/lib/jazari/mcp/handler.rb

@@ -1,5 +1,9 @@
 # frozen_string_literal: true
 
+# The handler dispatches against Mcp::Actions, so it must require it: a host may
+# `require "jazari/mcp/handler"` on its own now that this layer is opt-in.
+require "jazari/mcp/actions"
+
 module Jazari
   module Mcp
     # Transport-neutral adapter between an MCP action name and the domain.
@@ -13,23 +17,15 @@ module Jazari
     # That split is deliberate: two products sharing this handler still present
     # their own tool, their own subject vocabulary, and their own permissions.
     class Handler
-      READ_ACTIONS = %w[get last_run].freeze
-      WRITE_ACTIONS = %w[set add_item remove_item check_item reset start tick evidence finish].freeze
-      ACTIONS = (READ_ACTIONS + WRITE_ACTIONS).freeze
-
-      # Advertise only what the granted scope may call. A read-scoped connection
-      # should not see mutations in its tool list at all — hiding them is not
-      # security, but offering them and refusing is a worse experience.
-      def self.actions_for(scope)
-        scope.to_s == "read" ? READ_ACTIONS : ACTIONS
-      end
+      # Actions are declared once, in Mcp::Actions, so the schema a host
+      # publishes and the behaviour implemented here cannot drift apart.
+      def self.actions_for(scope) = Actions.names(scope: scope)
 
       def call(action:, target:, arguments: {})
         args = symbolize(arguments)
-        name = action.to_s
-        raise ArgumentError, "unknown runbook action #{action.inspect}" unless ACTIONS.include?(name)
+        descriptor = Actions.fetch(action)   # raises on an unknown action
 
-        reply(public_send(:"handle_#{name}", target, args))
+        reply(public_send(:"handle_#{descriptor.name}", target, args))
       rescue Jazari::Error => error
         # The closed taxonomy crosses the wire as a code, never as a message
         # that could disclose a record, a query, or whether a target exists.

data/lib/jazari/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Jazari
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end

data/lib/jazari.rb

@@ -10,7 +10,11 @@ require "jazari/resolved_runbook"
 require "jazari/recipe_registry"
 require "jazari/runs"
 require "jazari/operations"
-require "jazari/mcp/handler"
+# The MCP layer is OPTIONAL. Descriptors are cheap and a host may want them to
+# build its own tool, so they load; the handler does not, because a host with
+# its own MCP surface never calls it.
+#   require "jazari/mcp/handler"   # only if you want the ready-made dispatcher
+require "jazari/mcp/actions"
 require "jazari/railtie" if defined?(::Rails::Railtie)
 
 # Addressable operating procedures.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: jazari
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Nauman Tariq
@@ -60,6 +60,7 @@ files:
 - lib/jazari/anchors.rb
 - lib/jazari/checklist.rb
 - lib/jazari/errors.rb
+- lib/jazari/mcp/actions.rb
 - lib/jazari/mcp/handler.rb
 - lib/jazari/operations.rb
 - lib/jazari/railtie.rb