hecks 2.8.0 → 3.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 66f85d62ad01467ff2ae17c6d3be63c706bea69a9e6f7b20839d9f5fc22234a5
-  data.tar.gz: 45413f0bd639bfe548ca9f8f7970d5136ed6aa30a25765870ca0212806af3c90
+  metadata.gz: c04beedd84550f06db74d93d28c907eee4a0a913f6dfb619d84a1844faefeb13
+  data.tar.gz: 7b3cf71a37bbc83fa80c14eace35831f4b9bceaa789affbda6e2b1158e1ef39e
 SHA512:
-  metadata.gz: b817baff1d4e990f1161080d23f9f10fadd2e1eb8a6f76b1ed551fe021992311f10d64f0eef63218e515905fa2757d879a607abc4b40ecfeb4d0d45a6011a8a6
-  data.tar.gz: '0819f496494a76afe81697f8a83301c07acef480b218501748616f1537f0c5d3c0148d67271dea0fd4eea6b6bcb9bbb278331a203883b3c169c08cd59f384451'
+  metadata.gz: fdf38f7f5ece37807699026ff6166408f948a827aa59d4cec712ad48a686a90d932ec49ac083853a141654a50bfbc1ade18a0c3538126821ecb187128966c155
+  data.tar.gz: 03ccb78bc4b99292abc6e39ae74b35179254583fb41f735f116da2cacec4709971c8eb36c02fdc0e0ebe13b742b58311fe8e01dd1731e2c40efcaa0a430dcbf4

data/exe/hecks

@@ -1,13 +1,56 @@
 #!/usr/bin/env ruby
 
-# The `hecks` command the gem installs: run, read, check and serve a domain you
-# supply. `hecks` with no arguments lists the subcommands; `hecks <command> --help`
-# prints one's usage. The router is `Hecks::CLI` (lib/hecks/cli.rb).
+# Hecks's command line — GENERATED by hecks project_cli. Do not edit.
 #
-# The gem's own `lib` goes first on the load path, as it does for the `bin/`
-# scripts, so this file also runs straight from a checkout.
+# A launcher, not a CLI: the verbs, their arguments and their refusals are
+# projected from the bluebook beside it every time this runs, so a change
+# to the chapter shows up here without re-minting anything.
+#
+#   exe/hecks                  every verb, and every question
+#   exe/hecks <verb> --help    what it wants, and how it refuses
+
+Encoding.default_external = Encoding::UTF_8
+Encoding.default_internal = Encoding::UTF_8
 
 $LOAD_PATH.unshift File.expand_path("../lib", __dir__)
-require "hecks/cli"
 
-exit Hecks::CLI.start(ARGV)
+# The names the gem has always shipped keep their positional forms.
+LEGACY = %w[run docs narrate ir stores model_check smoke_test project_diagrams project_cli mcp].freeze
+if LEGACY.include?(ARGV.first)
+  require "hecks/cli"
+  exit Hecks::CLI.start(ARGV) unless Hecks::CLI.launcher_form?(ARGV)
+end
+
+require "hecks"
+
+# Usage is answered from the projected chapter alone: no adapter is bound and no
+# database is opened. Only a line that runs a verb boots the domain.
+domain = File.expand_path("../lib/hecks/hecks", __dir__)
+program = "hecks"
+described = begin
+  Hecks.describe(domain)
+rescue StandardError => e
+  abort "cannot open Hecks: #{e.message.lines.first.strip}"
+end
+
+text, status, reason = Hecks::Doors::CliRunner.usage(
+  runtime: described, argv: ARGV, program: program
+)
+unless text
+  runtime = begin
+    Hecks.boot(domain, install_doors: false)
+  rescue StandardError => e
+    abort "cannot open Hecks: #{e.message.lines.first.strip}"
+  end
+  text, status, reason = Hecks::Doors::CliRunner.call(
+    runtime: runtime, argv: ARGV, program: program
+  )
+end
+# A `--wait` run that failed answers its settled record on stdout, so `| jq` reads it
+# either way, and says why on stderr.
+if reason
+  puts text
+  warn reason
+  exit status
+end
+status.zero? ? puts(text) : abort(text)

data/lib/hecks/adapters/driven/claude_code.rb

@@ -6,31 +6,8 @@ require_relative "../../ports/agent"
 
 module Hecks
   module Adapters
-    # **The real `agent` fulfillment** — shells out to the `claude` CLI
-    # itself, `claude -p --output-format json`, one process per call.
-    # `Ports::Agent`'s own scripted double (`spec/fixtures/scripted_
-    # agent.{adapter,rb}`) is the deterministic sibling every spec binds
-    # instead, the same relationship `SecureRandomIdentity` already has
-    # to `SequentialIdentity`.
-    #
-    # **This file owns transport only** — spawning the process, unwrapping
-    # the CLI's own JSON envelope (`{"result": "..."}`) down to the
-    # model's raw text, and parsing that text as JSON. It hands back a
-    # plain Hash. Whether that Hash has the keys a caller asked for, and
-    # whether its values are within the closed vocabularies this port
-    # recognizes (a critique's `kind`, a proposal's `verb` pattern) is
-    # `Ports::Agent::Answers`' job, not this file's — see `ports/agent.rb`'s
-    # own header for why that split is load-bearing.
-    #
-    # `Open3.capture2` with an explicit argv array, never a shell string
-    # — the same shape every other subprocess call in this repo already
-    # uses (`bin/rust_conformance`), and the reason `claude` being
-    # shell-aliased to `claude --dangerously-skip-permissions` in a
-    # human's own terminal never reaches this code at all: an argv spawn
-    # invokes the real binary directly, no shell, no alias.
-    #
-    # `--allowedTools ""` — this adapter asks a question and reads back
-    # text; it never wants the model reaching for a tool mid-answer.
+    # Real `agent` fulfillment: one `claude -p --output-format json` process per call.
+    # Transport only; shape and vocabulary checks belong to `Ports::Agent::Answers`.
     module ClaudeCode
       TIMEOUT_SECONDS = 120
 
@@ -40,22 +17,6 @@ module Hecks
 
       module_function
 
-      # Asks the model for the next best interview question, as a raw parsed-JSON reply.
-      #
-      # **The next best question**. `state` is whatever
-      # `Interview::Session#declaration`/`#gaps` produced — passed
-      # through as JSON, not reformatted, so this adapter never
-      # re-derives what the session already knows.
-      #
-      # @param state [Hash] the interview's whole current picture (declaration plus gaps),
-      #   JSON-able
-      # @param asked [Array<Object>] JSON-able record of the questions already asked
-      # @return [Object] the parsed JSON reply, expected to be a Hash holding a `"questions"`
-      #   array; shape validated downstream by `Ports::Agent::Answers.questions`
-      # @raise [Ports::Agent::Unavailable] if the `claude` binary is missing, the subprocess
-      #   fails, or the call times out
-      # @raise [Ports::Agent::ValidationError] if the CLI's own envelope has no `"result"`, or
-      #   the result text is not valid JSON
       def ask(state:, asked:)
         call(
           system:  SYSTEM_PREFIX + "Given the domain model so far, ask the single best next " \
@@ -65,18 +26,6 @@ module Hecks
         )
       end
 
-      # Turns a human's sentence into proposed declarations, as a raw parsed-JSON reply.
-      #
-      # Prose -> proposed declarations.
-      #
-      # @param prose [String] a human's plain-English sentence
-      # @param state [Hash] the interview's whole current picture, JSON-able
-      # @return [Object] the parsed JSON reply, expected to be a Hash holding a `"proposals"`
-      #   array; shape validated downstream by `Ports::Agent::Answers.proposals`
-      # @raise [Ports::Agent::Unavailable] if the `claude` binary is missing, the subprocess
-      #   fails, or the call times out
-      # @raise [Ports::Agent::ValidationError] if the CLI's own envelope has no `"result"`, or
-      #   the result text is not valid JSON
       def interpret(prose:, state:)
         call(
           system:  SYSTEM_PREFIX + "Given the domain model so far and a sentence the human just said, " \
@@ -89,22 +38,6 @@ module Hecks
         )
       end
 
-      # Asks the model to judge a declared model on taste, as a raw parsed-JSON reply.
-      #
-      # What is wrong with this as a model — closed to the same kind
-      # vocabulary `Ports::Agent::CRITIQUE_KINDS` declares, spelled out
-      # here too since the system prompt is the only place the model
-      # itself ever sees that list.
-      #
-      # @param declared [Hash] the chapter as declared so far, JSON-able
-      # @param refusals [Array<Object>] JSON-able refusals the language itself already raised
-      # @param findings [Array<Object>] JSON-able mechanical findings already found
-      # @return [Object] the parsed JSON reply, expected to be a Hash holding a `"findings"`
-      #   array; shape validated downstream by `Ports::Agent::Answers.findings`
-      # @raise [Ports::Agent::Unavailable] if the `claude` binary is missing, the subprocess
-      #   fails, or the call times out
-      # @raise [Ports::Agent::ValidationError] if the CLI's own envelope has no `"result"`, or
-      #   the result text is not valid JSON
       def critique(declared:, refusals:, findings:)
         kinds = Ports::Agent::CRITIQUE_KINDS.join(", ")
         call(
@@ -117,22 +50,7 @@ module Hecks
         )
       end
 
-      # Suggests a name for a construct, as a raw parsed-JSON reply.
-      #
-      # **Vocabulary help**. Named `suggest_name`, not `name` — see
-      # `Ports::Agent#suggest_name`'s own comment for why `name` is
-      # never a safe module-function name here.
-      #
-      # @param meaning [String] what the new name needs to mean
-      # @param kind [String] the kind of construct being named, such as `"event"`
-      # @param near [Array<String>] names already in use nearby, which a suggestion must not
-      #   collide with
-      # @return [Object] the parsed JSON reply, expected to be a Hash holding a `"names"`
-      #   array; shape validated downstream by `Ports::Agent::Answers.suggestions`
-      # @raise [Ports::Agent::Unavailable] if the `claude` binary is missing, the subprocess
-      #   fails, or the call times out
-      # @raise [Ports::Agent::ValidationError] if the CLI's own envelope has no `"result"`, or
-      #   the result text is not valid JSON
+      # Named `suggest_name`, not `name`: `name` is never a safe module-function name here.
       def suggest_name(meaning:, kind:, near:)
         call(
           system:  SYSTEM_PREFIX + "Suggest a name for a #{kind} meaning \"#{meaning}\", distinct from " \
@@ -142,18 +60,7 @@ module Hecks
         )
       end
 
-      # ── transport ───────────────────────────────────────────────────
-
-      # Runs `claude` as a subprocess with `payload` on stdin and returns its parsed JSON reply.
-      #
-      # @param system [String] the system-prompt text appended via `--append-system-prompt`
-      # @param payload [Hash] the JSON-able payload written to the subprocess's stdin
-      # @return [Object] the parsed JSON value nested under the CLI envelope's `"result"` key
-      #   (see `unwrap`)
-      # @raise [Ports::Agent::Unavailable] if the `claude` binary is missing, the subprocess
-      #   exits non-zero, or the call does not finish within `TIMEOUT_SECONDS`
-      # @raise [Ports::Agent::ValidationError] if the envelope has no `"result"`, or the
-      #   result text is not valid JSON (see `unwrap`)
+      # Argv spawn, never a shell, so a `claude` shell alias cannot apply; no tools are allowed.
       def call(system:, payload:)
         stdout, status = Timeout.timeout(TIMEOUT_SECONDS) do
           Open3.capture2(
@@ -171,13 +78,6 @@ module Hecks
         raise Ports::Agent::Unavailable, "claude is not on PATH: #{e.message}"
       end
 
-      # Unwraps the CLI's own JSON envelope down to the model's parsed reply.
-      #
-      # @param stdout [String] the raw stdout of the `claude` CLI invocation, the outer
-      #   `{"result": "..."}` envelope
-      # @return [Object] the JSON value parsed out of the envelope's `"result"` string
-      # @raise [Ports::Agent::ValidationError] if the envelope has no `"result"` key, or
-      #   `result` is not valid JSON
       def unwrap(stdout)
         envelope = JSON.parse(stdout)
         result = envelope["result"]