hecks 6.0.0 → 7.0.0

data/lib/hecks/hecks/serve/serve.bluebook

@@ -0,0 +1,134 @@
+Hecks.bluebook "Hecks" do
+  domain_module "Serve" do
+    vision "Open something on a port until it is stopped: the Composer, a rendered example, or a static site."
+
+    aggregate "Server", kind: "Run" do
+      description "One server opened on a checkout, until it is stopped."
+
+      attribute :port,      Port, optional: true
+      attribute :domains,   PathList, optional: true
+      attribute :agent,     AgentName, optional: true
+      attribute :directory, Directory, optional: true
+      attribute :stdio,     Switch, optional: true
+
+      # One directory of files, named by a path.
+      value_object "Directory" do
+        attribute :value, String, matches: :present
+      end
+
+      # Which agent drives the Composer's assistant: the real `claude`, or a scripted `fake` for
+      # trying the editor without a model.
+      value_object "AgentName" do
+        attribute :value, String, pattern: '^(claude|fake)$'
+      end
+
+      # Domain directories, comma separated.
+      value_object "PathList" do
+        attribute :value, String, matches: :csv_list
+      end
+
+      # A local port a server listens on.
+      value_object "Port" do
+        attribute :value, Integer
+
+        invariant("a port is 1 to 65535") { value >= 1 && value <= 65535 }
+      end
+
+      command "Present" do
+        role "Maintainer"
+        goal "Serve the banking example's rendered forms and views on a local port until stopped"
+
+        attribute :port, Port, optional: true, sets: true
+        attribute :run,  RunKey, sets: true
+
+        sets :operation, to: "present"
+
+        emits PresentRequested
+      end
+
+      command "Compose" do
+        role "Maintainer"
+        goal "Serve the Composer, a live bluebook editor over one domain directory, on a local port until stopped"
+
+        attribute :port,    Port, optional: true, sets: true
+        attribute :domains, PathList, optional: true, sets: true
+        attribute :agent,   AgentName, default: "claude", sets: true
+        attribute :run,     RunKey, sets: true
+
+        sets :operation, to: "compose"
+
+        emits ComposeRequested
+      end
+
+      command "Preview" do
+        role "Maintainer"
+        goal "Serve one directory of static files, such as a website, on a local port until stopped"
+
+        attribute :directory, Directory, sets: true
+        attribute :port,      Port, optional: true, sets: true
+        attribute :run,       RunKey, sets: true
+
+        sets :operation, to: "preview"
+
+        emits PreviewRequested
+      end
+
+      command "ServeQueryIrMcp" do
+        role "Maintainer"
+        goal "Serve the IR queries to an MCP client over stdio until it closes"
+
+        attribute :run, RunKey, sets: true
+
+        sets :operation, to: "serve_query_ir_mcp"
+
+        emits ServeQueryIrMcpRequested
+      end
+
+      # A stdio server runs until its client closes stdin, so it cannot be asked and answered
+      # quickly. The command records that the server was started; the Terminal adapter hands the
+      # process over and answers when it closes. The launcher spells it `serve_mcp`; the `mcp`
+      # spelling is the launcher's alias for it.
+      command "ServeMcp" do
+        role "Operator"
+        goal "Serve the storehouse bus to an MCP client over stdio until it closes"
+
+        attribute :run,   RunKey, sets: true
+        attribute :stdio, Switch, optional: true, sets: true
+
+        sets :operation, to: "serve_mcp"
+
+        emits McpRequested
+      end
+    end
+
+    policy "ExamineWhenPresentRequested" do
+      on      "Server.PresentRequested"
+      ask     :examine, with: { run: :run }
+    end
+
+    policy "ExamineWhenComposeRequested" do
+      on      "Server.ComposeRequested"
+      ask     :examine, with: { run: :run }
+    end
+
+    policy "ExamineWhenPreviewRequested" do
+      on      "Server.PreviewRequested"
+      ask     :examine, with: { run: :run }
+    end
+
+    policy "ExamineWhenServeQueryIrMcpRequested" do
+      on      "Server.ServeQueryIrMcpRequested"
+      ask     :examine, with: { run: :run }
+    end
+
+    policy "ExamineWhenMcpRequested" do
+      on      "Server.McpRequested"
+      ask     :examine, with: { run: :run }
+    end
+
+    policy "ServeWhenMcpRequested" do
+      on      "Server.McpRequested"
+      ask     :serve, with: { run: :run }
+    end
+  end
+end

data/lib/hecks/hecks/shapes.json

@@ -1,17 +1,3 @@
 {
-  "Adapter": "75cc28515d7199acbb3d2f775ebae3721bb3021aef1136118fb3bf3cc77b7614",
-  "Bluebook": "1b447c6ba9afca0302b09564a4e7b6dc0e7e66a19913d51958676098f067ac35",
-  "Composer": "ffdf12a568277ebf26d016424d8a656eb21b42816fbb800d3ed05f710eb043ff",
-  "Deploy": "78bba4ff8c368b9947ff173c64963c0f6ce2714b761253565952b4b7bc81a5ee",
-  "Expression": "0a6e297b00941e428c250d3b42f3ec788d9f6d1ae7de869c31d8f7255854764b",
-  "Governance": "55c0fa41764b913a14a3e757e2fdf165cfce417698cf58ae5061375d3e594b0c",
-  "Hecks": "2404741fa89bfd1de9da9bb894c95687d8c10a7607536d5773a16972490ca8ae",
-  "Hecksagon": "80e36e507947f0ead476c023b841c1f08c2dd380f945f73c40854aad9a0434f4",
-  "Port": "db4030c45bbc8c2474a60da4e5436966d28512765016379aece17b3a3fc2acc5",
-  "QualityControl": "30b9228c89a7f23009ac6dda42709e76f64172fa53dab3e14560234ba849446a",
-  "Site": "1defb890b7f54bd12120be2494a30cb68d2d53582f2a27632d3a811e82757134",
-  "Tenancy": "410c651e3826824afa1aa7eb18246c83c503e6b619eb38fc29deebea0ffd3cd9",
-  "Tickets": "cd96d821fd8186fa7ac65c1dfe811a5917f9e5393068948630e0bf7887f45ecd",
-  "Translation": "fd2c71976c528a329bdc7c62ee9bc8c23701938dc4c95ec7b597d3bb03252e1e",
-  "World": "b0c551a5be7cfbe75a33c36e1f259643d643aefa315b787f1a3c79de63c9ba8f"
+  "Governance": "55c0fa41764b913a14a3e757e2fdf165cfce417698cf58ae5061375d3e594b0c"
 }

data/lib/hecks/hecks/site.behaviors

@@ -1,7 +1,7 @@
 Hecks.behaviors "Site" do
   vision "A projection of a site's route table is recorded as requested before anything outside is asked."
 
-  loads "hecks.bluebook", "custodian.bluebook", "tooling.bluebook", "rehearsal.bluebook", "agents.bluebook", "codebase.bluebook", "ledger.bluebook", "context_map.hecksagon", "hecks.hecksagon", "site.world", "environments/memory.world"
+  loads "hecks.bluebook", "context_map.hecksagon", "hecks.hecksagon", "site.world", "environments/memory.world", modules: :all
 
   test "ProjectSite keeps a project that has no bluebook as a faulted projection" do
     tests "ProjectSite", on: "SiteProjection"

data/lib/hecks/hecks/start/start.bluebook

@@ -0,0 +1,194 @@
+Hecks.bluebook "Hecks" do
+  domain_module "Start" do
+    vision "Begin a domain or a project."
+
+    # A run record for one launch onto the framework, not an adapter: the driving adapters live in `Hecks::Adapters::Driving`.
+    aggregate "Launch" do
+      description "A way into the framework opened for a project: its launchers, or an MCP server."
+
+      attribute :run,     LaunchKey
+      attribute :domains, DomainList, optional: true
+      attribute :stdio,   Switch,     optional: true
+      attribute :name,    DomainName, optional: true
+      attribute :adapter, AdapterName, optional: true
+      attribute :dir,     TargetDir,  optional: true
+      attribute :expert,  ExpertName, optional: true
+      attribute :no_ai,   Switch,     optional: true
+      attribute :output,  Note,       optional: true
+      attribute :refusal, Note,       optional: true
+      identified_by :run
+
+      value_object "LaunchKey" do
+        attribute :value, String, matches: :present
+
+        invariant("a launch is named") { !value.to_s.empty? }
+      end
+
+      # Domain directories under the project, comma separated.
+      value_object "DomainList" do
+        attribute :value, String, matches: :not_empty
+      end
+
+      value_object "Switch" do
+        attribute :value, Boolean
+      end
+
+      # What a new domain is called, as its bluebook spells it: a capital and then letters and digits.
+      value_object "DomainName" do
+        attribute :value, String, matches: :capitalized
+      end
+
+      # A persistence adapter a stub can be bound to; `Hecks::Tools::DomainStub` names the ones it knows.
+      value_object "AdapterName" do
+        attribute :value, String, pattern: '[A-Za-z]+'
+      end
+
+      # Where the new domain goes; the domain's snake-cased name under the current directory when absent.
+      value_object "TargetDir" do
+        attribute :value, String, matches: :not_empty
+      end
+
+      # Who is interviewed; asked for at the terminal when absent.
+      value_object "ExpertName" do
+        attribute :value, String, matches: :not_empty
+      end
+
+      value_object "Note" do
+        attribute :value, String
+      end
+
+      lifecycle :status, default: "requested" do
+        mark :failure, "stopped"
+        transition "Finish" => "finished", from: "requested"
+        transition "Stop"   => "stopped",  from: "requested"
+        mark :terminal, "finished", "stopped"
+      end
+
+      # Writes a launcher beside each domain. It replaces the generated launcher already there and
+      # deletes nothing, so it runs without `confirm` (`hecks project_cli` never asked for one).
+      command "ProjectCli" do
+        role "Operator"
+        goal "Write a command-line launcher beside each domain of this project"
+
+        attribute :run,     LaunchKey, sets: true
+        attribute :domains, DomainList, optional: true, sets: true
+
+
+        emits LaunchersRequested
+      end
+
+      # Writes the stub files of a new domain (ADR 0087). It asks nothing and replaces nothing: a
+      # directory that already holds any file it would write is refused, with that file named.
+      command "Init" do
+        role "Operator"
+        goal "Write the stub files of a new domain"
+
+        attribute :run,     LaunchKey, sets: true
+        attribute :name,    DomainName, sets: true
+        attribute :adapter, AdapterName, optional: true, sets: true
+        attribute :dir,     TargetDir,   optional: true, sets: true
+
+
+        emits StubRequested
+      end
+
+      # Writes the files a Rails app needs to drive its domain through hecks-rails: a controller per
+      # aggregate and the routes file, read from the `bluebook/` under `dir` (the current directory
+      # when absent). Models are generated at boot and need no file. A file already there is the
+      # app's own and is left alone, so it runs without `confirm`.
+      command "ProjectRails" do
+        role "Operator"
+        goal "Write the controllers and routes a Rails app drives its domain through"
+
+        attribute :run, LaunchKey, sets: true
+        attribute :dir, TargetDir, optional: true, sets: true
+
+
+        emits RailsRequested
+      end
+
+      # Holds an interview with a subject matter expert and drafts a first domain from it (ADR 0088).
+      # The Terminal adapter runs the conversation, as it runs a console; the journal records that one
+      # was held and how it ended, not what was said. `--no-ai` leaves the model out.
+      command "Interview" do
+        role "Operator"
+        goal "Hold an interview with a subject matter expert and draft a first domain from it"
+
+        attribute :run,     LaunchKey, sets: true
+        attribute :name,    DomainName, sets: true
+        attribute :adapter, AdapterName, optional: true, sets: true
+        attribute :dir,     TargetDir,   optional: true, sets: true
+        attribute :expert,  ExpertName,  optional: true, sets: true
+        attribute :no_ai,   Switch,      optional: true, sets: true
+
+
+        emits InterviewRequested
+      end
+
+      command "Finish" do
+        role "System"
+        goal "Record that the launch did its work, or was closed, and what it said"
+
+        reference_to Launch
+        attribute :output, Note, sets: true
+
+
+        emits LaunchFinished
+      end
+
+      command "Stop" do
+        role "System"
+        goal "Record that the launch could not be opened, and why"
+
+        reference_to Launch
+        attribute :refusal, Note, sets: true
+
+
+        emits LaunchStopped
+      end
+
+      query "Ended" do
+        description "How one launch ended: its status, and what it said or why it stopped."
+        attribute :run, LaunchKey
+        where(run: :run)
+        order_by :run
+      end
+
+      query "Stopped" do
+        description "Every launch that could not be opened."
+        where(status: "stopped")
+        order_by :run
+      end
+    end
+
+    policy "WriteWhenRequested" do
+      on      "Launch.LaunchersRequested"
+      ask     :write, with: { run: :run }
+    end
+
+    policy "ScaffoldWhenRequested" do
+      on      "Launch.StubRequested"
+      ask     :scaffold, with: { run: :run }
+    end
+
+    policy "ProjectRailsWhenRequested" do
+      on      "Launch.RailsRequested"
+      ask     :write_rails, with: { run: :run }
+    end
+
+    policy "ConverseWhenRequested" do
+      on      "Launch.InterviewRequested"
+      ask     :converse, with: { run: :run }
+    end
+
+    policy "RecordTheLaunch" do
+      on      "Launch.LaunchAnswered"
+      trigger Launch::Finish, with: { output: :output }
+    end
+
+    policy "RecordTheStoppedLaunch" do
+      on      "Launch.LaunchRefused"
+      trigger Launch::Stop, with: { refusal: :refusal }
+    end
+  end
+end