hecks 3.12.0 → 3.14.0

data/lib/hecks/deploy/bluebook/deploy.bluebook

@@ -451,7 +451,7 @@ Hecks.bluebook "Deploy" do
 
     # The domain's own directory on disk, where `environments/<slug>.world` is written.
     value_object "DirectoryPath" do
-      attribute :value, String, pattern: '[^\t\n\r]'
+      attribute :value, String, matches: :not_empty
     end
 
     value_object "Report" do
@@ -581,14 +581,14 @@ Hecks.bluebook "Deploy" do
     identified_by :run
 
     value_object "RunKey" do
-      attribute :value, String, pattern: '[^ \t\n\r]'
+      attribute :value, String, matches: :present
 
       invariant("a run is named") { !value.to_s.empty? }
     end
 
     # A domain directory, whose `bluebook/` holds the `.world` that declares `deployed_to`.
     value_object "DomainPath" do
-      attribute :value, String, pattern: '[^\t\n\r]'
+      attribute :value, String, matches: :not_empty
 
       invariant("a domain is named by its path") { !value.to_s.empty? }
     end
@@ -604,7 +604,7 @@ Hecks.bluebook "Deploy" do
 
     # Where the recipe is written, for a domain that lives in a client's repository.
     value_object "Location" do
-      attribute :value, String, pattern: '[^\t\n\r]'
+      attribute :value, String, matches: :not_empty
     end
 
     # An `environments/<name>.world` overlay of the domain, which must exist.
@@ -707,14 +707,14 @@ Hecks.bluebook "Deploy" do
     identified_by :run
 
     value_object "RunKey" do
-      attribute :value, String, pattern: '[^ \t\n\r]'
+      attribute :value, String, matches: :present
 
       invariant("a run is named") { !value.to_s.empty? }
     end
 
     # A domain directory, whose `bluebook/` holds the `.world` that declares `deployed_to`.
     value_object "DomainPath" do
-      attribute :value, String, pattern: '[^\t\n\r]'
+      attribute :value, String, matches: :not_empty
 
       invariant("a domain is named by its path") { !value.to_s.empty? }
     end
@@ -722,7 +722,7 @@ Hecks.bluebook "Deploy" do
     # A directory the cleared worlds are written to, at their paths below `bluebook/`, instead of
     # over the originals.
     value_object "Location" do
-      attribute :value, String, pattern: '[^\t\n\r]'
+      attribute :value, String, matches: :not_empty
     end
 
     value_object "Report" do
@@ -813,14 +813,14 @@ Hecks.bluebook "Deploy" do
     identified_by :run
 
     value_object "RunKey" do
-      attribute :value, String, pattern: '[^ \t\n\r]'
+      attribute :value, String, matches: :present
 
       invariant("a run is named") { !value.to_s.empty? }
     end
 
     # Makefile paths, comma separated; three generated fixture domains when absent.
     value_object "PathList" do
-      attribute :value, String, pattern: '[^\t\n\r]'
+      attribute :value, String, matches: :not_empty
     end
 
     value_object "Report" do
@@ -909,7 +909,7 @@ Hecks.bluebook "Deploy" do
     identified_by :run
 
     value_object "RunKey" do
-      attribute :value, String, pattern: '[^ \t\n\r]'
+      attribute :value, String, matches: :present
 
       invariant("a run is named") { !value.to_s.empty? }
     end
@@ -1020,13 +1020,13 @@ Hecks.bluebook "Deploy" do
     identified_by :run
 
     value_object "RunKey" do
-      attribute :value, String, pattern: '[^ \t\n\r]'
+      attribute :value, String, matches: :present
 
       invariant("a run is named") { !value.to_s.empty? }
     end
 
     value_object "Location" do
-      attribute :value, String, pattern: '[^\t\n\r]'
+      attribute :value, String, matches: :not_empty
 
       invariant("a project or script is named by its path") { !value.to_s.empty? }
     end
@@ -1159,13 +1159,13 @@ Hecks.bluebook "Deploy" do
     identified_by :run
 
     value_object "RunKey" do
-      attribute :value, String, pattern: '[^ \t\n\r]'
+      attribute :value, String, matches: :present
 
       invariant("a run is named") { !value.to_s.empty? }
     end
 
     value_object "Location" do
-      attribute :value, String, pattern: '[^\t\n\r]'
+      attribute :value, String, matches: :not_empty
 
       invariant("a project or script is named by its path") { !value.to_s.empty? }
     end
@@ -1187,7 +1187,7 @@ Hecks.bluebook "Deploy" do
 
     # A local image reference to push, as the script's LOCAL_IMAGE takes it.
     value_object "ImageName" do
-      attribute :value, String, pattern: '^[^ \t\n\r]+$'
+      attribute :value, String, matches: :no_whitespace
     end
 
     value_object "Switch" do
@@ -1352,13 +1352,13 @@ Hecks.bluebook "Deploy" do
     identified_by :run
 
     value_object "RunKey" do
-      attribute :value, String, pattern: '[^ \t\n\r]'
+      attribute :value, String, matches: :present
 
       invariant("a run is named") { !value.to_s.empty? }
     end
 
     value_object "Location" do
-      attribute :value, String, pattern: '[^\t\n\r]'
+      attribute :value, String, matches: :not_empty
 
       invariant("a project or script is named by its path") { !value.to_s.empty? }
     end
@@ -1538,13 +1538,13 @@ Hecks.bluebook "Deploy" do
     identified_by :run
 
     value_object "RunKey" do
-      attribute :value, String, pattern: '[^ \t\n\r]'
+      attribute :value, String, matches: :present
 
       invariant("a run is named") { !value.to_s.empty? }
     end
 
     value_object "Location" do
-      attribute :value, String, pattern: '[^\t\n\r]'
+      attribute :value, String, matches: :not_empty
 
       invariant("a project or script is named by its path") { !value.to_s.empty? }
     end
@@ -1560,7 +1560,7 @@ Hecks.bluebook "Deploy" do
 
     # A Secrets Manager id or ARN; the script reads the password from it, so no value travels here.
     value_object "Secret" do
-      attribute :value, String, pattern: '^[^ \t\n\r]+$'
+      attribute :value, String, matches: :no_whitespace
     end
 
     # A database's name; empty leaves it to the generated script's own default.
@@ -1826,13 +1826,13 @@ Hecks.bluebook "Deploy" do
     identified_by :run
 
     value_object "RunKey" do
-      attribute :value, String, pattern: '[^ \t\n\r]'
+      attribute :value, String, matches: :present
 
       invariant("a run is named") { !value.to_s.empty? }
     end
 
     value_object "Location" do
-      attribute :value, String, pattern: '[^\t\n\r]'
+      attribute :value, String, matches: :not_empty
 
       invariant("a project or script is named by its path") { !value.to_s.empty? }
     end
@@ -1846,7 +1846,7 @@ Hecks.bluebook "Deploy" do
     end
 
     value_object "Secret" do
-      attribute :value, String, pattern: '^[^ \t\n\r]+$'
+      attribute :value, String, matches: :no_whitespace
     end
 
     # A database's name; empty leaves it to the generated script's own default.
@@ -1984,13 +1984,13 @@ Hecks.bluebook "Deploy" do
     identified_by :run
 
     value_object "RunKey" do
-      attribute :value, String, pattern: '[^ \t\n\r]'
+      attribute :value, String, matches: :present
 
       invariant("a run is named") { !value.to_s.empty? }
     end
 
     value_object "Location" do
-      attribute :value, String, pattern: '[^\t\n\r]'
+      attribute :value, String, matches: :not_empty
 
       invariant("a project, script or file is named by its path") { !value.to_s.empty? }
     end
@@ -2134,13 +2134,13 @@ Hecks.bluebook "Deploy" do
     identified_by :run
 
     value_object "RunKey" do
-      attribute :value, String, pattern: '[^ \t\n\r]'
+      attribute :value, String, matches: :present
 
       invariant("a run is named") { !value.to_s.empty? }
     end
 
     value_object "Location" do
-      attribute :value, String, pattern: '[^\t\n\r]'
+      attribute :value, String, matches: :not_empty
 
       invariant("a project or script is named by its path") { !value.to_s.empty? }
     end
@@ -2152,7 +2152,7 @@ Hecks.bluebook "Deploy" do
 
     # A git branch name. A preview is never of a production branch.
     value_object "Branch" do
-      attribute :value, String, pattern: '^[^ \t\n\r]+$'
+      attribute :value, String, matches: :no_whitespace
 
       invariant("a preview is never of main or master") { value != "main" && value != "master" }
     end
@@ -2510,13 +2510,13 @@ Hecks.bluebook "Deploy" do
     identified_by :run
 
     value_object "RunKey" do
-      attribute :value, String, pattern: '[^ \t\n\r]'
+      attribute :value, String, matches: :present
 
       invariant("a run is named") { !value.to_s.empty? }
     end
 
     value_object "Location" do
-      attribute :value, String, pattern: '[^\t\n\r]'
+      attribute :value, String, matches: :not_empty
 
       invariant("a project or script is named by its path") { !value.to_s.empty? }
     end
@@ -2656,13 +2656,13 @@ Hecks.bluebook "Deploy" do
     identified_by :run
 
     value_object "RunKey" do
-      attribute :value, String, pattern: '[^ \t\n\r]'
+      attribute :value, String, matches: :present
 
       invariant("a run is named") { !value.to_s.empty? }
     end
 
     value_object "Location" do
-      attribute :value, String, pattern: '[^\t\n\r]'
+      attribute :value, String, matches: :not_empty
 
       invariant("a template is named by its path") { !value.to_s.empty? }
     end
@@ -2785,14 +2785,14 @@ Hecks.bluebook "Deploy" do
     identified_by :run
 
     value_object "RunKey" do
-      attribute :value, String, pattern: '[^ \t\n\r]'
+      attribute :value, String, matches: :present
 
       invariant("a run is named") { !value.to_s.empty? }
     end
 
     # Domain directories, comma separated; every domain of the checkout when absent.
     value_object "DomainList" do
-      attribute :value, String, pattern: '[^\t\n\r]'
+      attribute :value, String, matches: :not_empty
     end
 
     value_object "Report" do
@@ -2806,7 +2806,7 @@ Hecks.bluebook "Deploy" do
     end
 
     command "ProjectOidc" do
-      goal "Write each domain's OIDC client and scope manifest beside it as oidc.json"
+      goal "Write each domain's OIDC client and scope manifest beside it: oidc.json, or one <chapter>.oidc.json for each chapter of a directory that holds several"
 
       attribute :domains, DomainList, optional: true
       attribute :run,     RunKey

data/lib/hecks/framework/bluebook/change.behaviors

@@ -0,0 +1,30 @@
+Hecks.behaviors "Change" do
+  vision "A change names its script, faults when that script cannot plan it, and is confirmed only from a plan."
+
+  loads "change.bluebook", "governance.bluebook", "change.hecksagon", "../../../../spec/fixtures/change/governance.hecksagon"
+
+  test "Request refuses a change that names no script" do
+    tests "Request", on: "Change"
+    input run: { value: "c1" }, script: { value: "" }
+    expect refused: "must match"
+  end
+
+  test "Request refuses a change that is not named" do
+    tests "Request", on: "Change"
+    input run: { value: "" }, script: { value: "rename" }
+    expect refused: "must match"
+  end
+
+  test "Request faults a change whose script nobody registered" do
+    tests "Request", on: "Change"
+    input run: { value: "c2" }, script: { value: "no_such_script" }
+    expect status: "faulted"
+  end
+
+  test "Confirm refuses a change that was never planned" do
+    tests "Confirm", on: "Change"
+    setup  "Change::Change.Request", run: { value: "c3" }, script: { value: "no_such_script" }
+    input  run: { value: "c3" }, digest: { value: "ab12" }
+    expect refused: "the digest confirmed is the digest planned"
+  end
+end

data/lib/hecks/framework/bluebook/change.bluebook

@@ -0,0 +1,162 @@
+Hecks.bluebook "Change" do
+  vision "A change you can preview: it is planned, shown, confirmed against exactly that plan, and only then carried out, whatever script it runs."
+  supporting
+
+  # A framework member like Governance and Identity: attach it with `attaches "Change"` in the
+  # consuming domain's own `.hecksagon`. The script is the port's adapter, so what a change
+  # does lives behind the `Script` port, and this chapter holds only how any change moves.
+  aggregate "Change" do
+    description "One change a script makes, previewed before it is carried out and applied only if its plan is unchanged."
+
+    attribute :run,            RunKey
+    attribute :script,         ScriptName
+    attribute :arguments,      list_of(Argument), optional: true
+    attribute :plan,           Report,            optional: true
+    attribute :planned_digest, Digest,            optional: true
+    attribute :report,         Report,            optional: true
+    attribute :refusal,        Report,            optional: true
+    identified_by :run
+
+    value_object "RunKey" do
+      attribute :value, String, matches: :present
+
+      invariant("a change is named") { !value.to_s.empty? }
+    end
+
+    # The name the script is registered under with the adapter.
+    value_object "ScriptName" do
+      attribute :value, String, matches: :present
+
+      invariant("a change names its script") { !value.to_s.empty? }
+    end
+
+    # One argument of the script, spelled as text; the script says what each key means.
+    value_object "Argument" do
+      attribute :key,   String
+      attribute :value, String
+    end
+
+    value_object "Report" do
+      attribute :value, String
+    end
+
+    # A fingerprint of the plan, the script and its arguments: confirming one digest applies
+    # that plan and no other.
+    value_object "Digest" do
+      attribute :value, String, pattern: '[0-9a-f]+'
+
+      invariant("a plan has a digest") { !value.to_s.empty? }
+    end
+
+    lifecycle :status, default: "requested" do
+      mark :failure, "faulted"
+      transition "Plan"     => "planned",   from: "requested"
+      transition "Confirm"  => "confirmed", from: "planned"
+      transition "Complete" => "applied",   from: "confirmed"
+      transition "Fault"    => "faulted",   from: ["requested", "planned", "confirmed"]
+    end
+
+    command "Request" do
+      role "Maintainer"
+      goal "Ask for a change by naming its script and giving the script's arguments"
+
+      attribute :run,       RunKey
+      attribute :script,    ScriptName
+      attribute :arguments, list_of(Argument), optional: true
+
+      sets :run
+      sets :script
+      sets :arguments
+
+      emits ChangeRequested
+    end
+
+    command "Plan" do
+      role "System"
+      goal "Record what the script would do, and the digest that stands for it"
+
+      reference_to Change
+      attribute :plan,   Report
+      attribute :digest, Digest
+
+      sets :plan
+      sets :planned_digest, to: :digest
+
+      emits ChangePlanned
+    end
+
+    command "Confirm" do
+      role "Maintainer"
+      goal "Agree to the plan shown, by naming its digest"
+
+      reference_to Change
+      attribute :digest, Digest
+
+      given("the digest confirmed is the digest planned") { digest.value == planned_digest.value }
+
+      emits ChangeConfirmed
+    end
+
+    command "Complete" do
+      role "System"
+      goal "Record that the confirmed plan was carried out, and what the script reported"
+
+      reference_to Change
+      attribute :report, Report
+
+      sets :report
+
+      emits ChangeApplied
+    end
+
+    command "Fault" do
+      role "System"
+      goal "Record that the change was refused or could not be carried out, and why"
+
+      reference_to Change
+      attribute :refusal, Report
+
+      sets :refusal
+
+      emits ChangeFaulted
+    end
+
+    query "Outcome" do
+      description "How one change stands: its status, its plan, and what it reported or why it failed."
+      attribute :run, RunKey
+      where(run: :run)
+      order_by :run
+    end
+
+    query "Faulted" do
+      description "Every change that was refused or could not be carried out."
+      where(status: "faulted")
+      order_by :run
+    end
+  end
+
+  policy "ExamineWhenRequested" do
+    on      "Change.ChangeRequested"
+    trigger Change::Script::Examine, with: { run: :run }
+  end
+
+  policy "RecordThePlanWhenExamined" do
+    on      "Change.ChangeExamined"
+    trigger Change::Plan, with: { plan: :plan, digest: :digest }
+  end
+
+  policy "PerformWhenConfirmed" do
+    on      "Change.ChangeConfirmed"
+    trigger Change::Script::Perform, with: { run: :run }
+  end
+
+  policy "RecordTheOutcomeWhenPerformed" do
+    on      "Change.ChangeAnswered"
+    trigger Change::Complete, with: { report: :report }
+  end
+
+  policy "RecordTheRefusal" do
+    on      "Change.ChangeRefused"
+    trigger Change::Fault, with: { refusal: :refusal }
+  end
+end

data/lib/hecks/framework/bluebook/change.hecksagon

@@ -0,0 +1,21 @@
+Hecks.hecksagon "Change" do
+  # `Change.Request` and `Change.Confirm` declare roles; same reason as Compliance.
+  attaches "Governance"
+  persisted_by "Memory"
+
+  # The change moves through two asks: `Examine` plans it, `Perform` carries it out. What a
+  # script does is the adapter's, so the chapter never names one.
+  Change::Change.port "Script" do
+    asks "Examine", to: Change do
+      attribute :run, RunKey
+      answers "ChangeExamined"
+      refuses "ChangeRefused"
+    end
+
+    asks "Perform", to: Change do
+      attribute :run, RunKey
+      answers "ChangeAnswered"
+      refuses "ChangeRefused"
+    end
+  end
+end

data/lib/hecks/framework/change.oidc.json

@@ -0,0 +1,34 @@
+{
+  "audience": "Change",
+  "scopes": [
+    {
+      "scope": "change:change.complete",
+      "verb": "Change::Change.Complete",
+      "role": "System"
+    },
+    {
+      "scope": "change:change.confirm",
+      "verb": "Change::Change.Confirm",
+      "role": "Maintainer"
+    },
+    {
+      "scope": "change:change.fault",
+      "verb": "Change::Change.Fault",
+      "role": "System"
+    },
+    {
+      "scope": "change:change.plan",
+      "verb": "Change::Change.Plan",
+      "role": "System"
+    },
+    {
+      "scope": "change:change.request",
+      "verb": "Change::Change.Request",
+      "role": "Maintainer"
+    }
+  ],
+  "roles": [
+    "Maintainer",
+    "System"
+  ]
+}

data/lib/hecks/framework/console_settings.oidc.json

@@ -0,0 +1,103 @@
+{
+  "audience": "ConsoleSettings",
+  "scopes": [
+    {
+      "scope": "console_settings:collection.declare",
+      "verb": "ConsoleSettings::Collection.Declare",
+      "role": "Console"
+    },
+    {
+      "scope": "console_settings:collection.replace_columns",
+      "verb": "ConsoleSettings::Collection.ReplaceColumns",
+      "role": "Console"
+    },
+    {
+      "scope": "console_settings:collection.replace_detail_field_columns",
+      "verb": "ConsoleSettings::Collection.ReplaceDetailFieldColumns",
+      "role": "Console"
+    },
+    {
+      "scope": "console_settings:collection.replace_detail_fields",
+      "verb": "ConsoleSettings::Collection.ReplaceDetailFields",
+      "role": "Console"
+    },
+    {
+      "scope": "console_settings:collection.replace_field_formats",
+      "verb": "ConsoleSettings::Collection.ReplaceFieldFormats",
+      "role": "Console"
+    },
+    {
+      "scope": "console_settings:collection.replace_preconditions",
+      "verb": "ConsoleSettings::Collection.ReplacePreconditions",
+      "role": "Console"
+    },
+    {
+      "scope": "console_settings:collection.set_extra",
+      "verb": "ConsoleSettings::Collection.SetExtra",
+      "role": "Console"
+    },
+    {
+      "scope": "console_settings:collection.set_identity",
+      "verb": "ConsoleSettings::Collection.SetIdentity",
+      "role": "Console"
+    },
+    {
+      "scope": "console_settings:collection.set_key",
+      "verb": "ConsoleSettings::Collection.SetKey",
+      "role": "Console"
+    },
+    {
+      "scope": "console_settings:collection.set_label",
+      "verb": "ConsoleSettings::Collection.SetLabel",
+      "role": "Console"
+    },
+    {
+      "scope": "console_settings:collection.set_list_query",
+      "verb": "ConsoleSettings::Collection.SetListQuery",
+      "role": "Console"
+    },
+    {
+      "scope": "console_settings:collection.set_nav_order",
+      "verb": "ConsoleSettings::Collection.SetNavOrder",
+      "role": "Console"
+    },
+    {
+      "scope": "console_settings:collection.set_primary_field",
+      "verb": "ConsoleSettings::Collection.SetPrimaryField",
+      "role": "Console"
+    },
+    {
+      "scope": "console_settings:overview.declare",
+      "verb": "ConsoleSettings::Overview.Declare",
+      "role": "Console"
+    },
+    {
+      "scope": "console_settings:overview.replace_stats",
+      "verb": "ConsoleSettings::Overview.ReplaceStats",
+      "role": "Console"
+    },
+    {
+      "scope": "console_settings:state_style.declare",
+      "verb": "ConsoleSettings::StateStyle.Declare",
+      "role": "Console"
+    },
+    {
+      "scope": "console_settings:state_style.set_attention",
+      "verb": "ConsoleSettings::StateStyle.SetAttention",
+      "role": "Console"
+    },
+    {
+      "scope": "console_settings:state_style.set_extra",
+      "verb": "ConsoleSettings::StateStyle.SetExtra",
+      "role": "Console"
+    },
+    {
+      "scope": "console_settings:state_style.set_tone",
+      "verb": "ConsoleSettings::StateStyle.SetTone",
+      "role": "Console"
+    }
+  ],
+  "roles": [
+    "Console"
+  ]
+}

data/lib/hecks/framework/governance.oidc.json

@@ -0,0 +1,28 @@
+{
+  "audience": "Governance",
+  "scopes": [
+    {
+      "scope": "governance:role_assignment.assign",
+      "verb": "Governance::RoleAssignment.Assign",
+      "role": "Governance administrator"
+    },
+    {
+      "scope": "governance:role_assignment.revoke",
+      "verb": "Governance::RoleAssignment.Revoke",
+      "role": "Governance administrator"
+    },
+    {
+      "scope": "governance:role_transition.grant",
+      "verb": "Governance::RoleTransition.Grant",
+      "role": "Governance administrator"
+    },
+    {
+      "scope": "governance:role_transition.revoke",
+      "verb": "Governance::RoleTransition.Revoke",
+      "role": "Governance administrator"
+    }
+  ],
+  "roles": [
+    "Governance administrator"
+  ]
+}

data/lib/hecks/framework/identity.oidc.json

@@ -0,0 +1,18 @@
+{
+  "audience": "Identity",
+  "scopes": [
+    {
+      "scope": "identity:external_identifier.link",
+      "verb": "Identity::ExternalIdentifier.Link",
+      "role": "Identity registrar"
+    },
+    {
+      "scope": "identity:identity.register",
+      "verb": "Identity::Identity.Register",
+      "role": "Identity registrar"
+    }
+  ],
+  "roles": [
+    "Identity registrar"
+  ]
+}