aw-spec-cli 0.1.26 → 0.1.27

package/assets/.appweaver/orchestrator/modules/foundation-pack.orch.yaml

@@ -0,0 +1,349 @@
+# =============================================================================
+# foundation-pack (orchestrator) — scaffold ONE lane by unpacking a foundation pack
+#
+# Included by foundation-lane when the operator picks a `[pack]` entry. Almost entirely
+# deterministic: locate the verified byte-for-byte bundle, confirm, dry-run for
+# collisions, unpack into the lane root folder exactly as packed with the sentinel renamed,
+# optionally add the reference sample on top, and check that no sentinel is left behind.
+#
+# Every file in a pack lands as packed, replacing a file already there — except the ones
+# its RULE FILE (<pack name>.rules.json beside the pack) says to merge. The model is used
+# ONLY for those merges: an `agent_author` (read-only generation, the ENGINE writes the
+# file) with include_standards: false and a two-file context — the file that was there
+# and the pack's version — following the rule's own instruction.
+#
+# Every refusal RETURNS rather than stops: the run carries on with the next lane, and the
+# reason lands in fl_status (message_var), which the caller reports per lane.
+#
+# Inputs (shared vars, set by foundation-lane):
+#   fl_name, app, fl_kind, fl_lane_id, fl_title, fl_language, fl_ecosystem,
+#   fl_source_path, fl_test_path, fl_overwrite
+# Produces: fl_status, fl_files (files written), and the fp_* details.
+# =============================================================================
+
+name: foundation-pack
+dialect: aw-spec.orchestrator/v1
+
+scripts:
+  actions:
+    sh:  .appweaver/scripts/bash/aw-spec-actions.sh
+    ps1: .appweaver/scripts/powershell/aw-spec-actions.ps1
+
+workflow:
+
+  # 0. This module runs once per lane in the same run, and vars are shared — the second
+  #    lane must not inherit the first lane's overwrite answer or reference choice.
+  - id: fp_reset
+    action: set
+    vars:
+      fp_overwrite: "no"
+      fp_has_collisions: "false"
+      fp_want_reference: "no"
+      fp_has_reference: "false"
+      fp_merge_state: ".appweaver/orchestrator/.state/foundation-{{fl_lane_id}}.merge/"
+      fp_rules_ok: ""
+      fp_rules_reason: ""
+      fp_rules_file: ""
+      fp_merges: "[]"
+      fp_rules_note: ""
+      fp_ref_rules_ok: ""
+      fp_ref_rules_reason: ""
+      fp_ref_rules_file: ""
+      fp_ref_merges: "[]"
+      fp_ref_rules_note: ""
+      fp_ref_go: "no"
+      fp_ok: ""
+      fp_written: "0"
+      fp_tests_message: ""
+      fp_tests_note: ""
+      fp_ref_ok: ""
+      fp_ref_written: "0"
+      fp_ref_tests_message: ""
+      fp_ref_note: ""
+      fp_clean: ""
+      fp_residue: ""
+      fp_residue_note: "not checked"
+
+  # 1. Locate the bundle + its unpacker and read the (bounded) pack header: the sentinel,
+  #    the file count, and whether a Reference pack ships beside it.
+  - id: fp_locate
+    action: execute_script
+    script: { ref: actions }
+    subcommand: foundation-locate
+    args: ["--name", "{{fl_name}}", "--app", "{{app}}", "--out", "{{fl_source_path}}"]
+    outputs:
+      - { name: fp_locate_ok,     from: "$.ok" }
+      - { name: fp_locate_msg,    from: "$.reason" }
+      - { name: fp_available,     from: "$.available" }
+      - { name: fp_sentinel,      from: "$.sentinel" }
+      - { name: fp_file_count,    from: "$.file_count" }
+      - { name: fp_has_reference, from: "$.has_reference" }
+
+  - id: fp_locate_gate
+    action: verify_context
+    require_true: fp_locate_ok
+    on_false: return
+    message_var: fl_status
+    on_false_message: "not scaffolded — {{fp_locate_msg}} (packs available: {{fp_available}})"
+
+  # 1b. The lane already had files and foundation-lane's overwrite question was answered
+  #     yes before the pick list: that answer stands, so the unpack overwrites and the
+  #     collision question below is not asked a second time.
+  - id: fp_overwrite_agreed
+    action: set
+    condition: "{{fl_overwrite}} == yes"
+    vars: { fp_overwrite: "yes" }
+
+  # 2. Confirm (checkpoint kind 'ask' under every strategy).
+  - id: fp_confirm
+    action: ask
+    prompt: |
+      Foundation: {{fl_name}} pack (sentinel {{fp_sentinel}}, {{fp_file_count}} files)
+      App name:   {{app}}
+      Lane:       {{fl_lane_id}} — {{fl_title}}, {{fl_language}} ({{fl_ecosystem}})
+      Folder:     {{fl_source_path}}     <- the pack unpacks here as packed: build files, source and tests
+      Tests:      {{fl_test_path}}
+      Overwrite:  {{fp_overwrite}}     <- yes: files the pack writes replace existing ones
+      The sentinel {{fp_sentinel}} is renamed to {{app}} in file contents and paths, as the
+      replacement contract in the pack's header describes. Proceed?
+    options: ["yes", "no"]
+    answer_var: fp_proceed
+
+  - id: fp_confirm_gate
+    action: verify_context
+    require_value: fp_proceed
+    equals: "yes"
+    on_mismatch: return
+    message_var: fl_status
+    on_mismatch_message: "not scaffolded — the {{fl_name}} pack was declined at the confirmation; nothing was written to {{fl_source_path}}"
+
+  # 3. Dry-run to surface collisions, then confirm overwrite if needed — only for a lane
+  #    that was empty: one that already had files was asked before the pick list (step 1b).
+  - id: fp_dry_run
+    action: execute_script
+    condition: "{{fl_overwrite}} != yes"
+    script: { ref: actions }
+    subcommand: foundation-unpack
+    args: ["--name", "{{fl_name}}", "--app", "{{app}}", "--out", "{{fl_source_path}}", "--dry-run"]
+    outputs:
+      - { name: fp_has_collisions, from: "$.has_collisions" }
+
+  - id: fp_ask_overwrite
+    action: ask
+    condition: "{{fp_has_collisions}} == true"
+    prompt: "Files the {{fl_name}} pack writes already exist under {{fl_source_path}}. Overwrite them?"
+    options: ["yes", "no"]
+    answer_var: fp_overwrite
+
+  - id: fp_overwrite_gate
+    action: verify_context
+    condition: "{{fp_has_collisions}} == true"
+    require_value: fp_overwrite
+    equals: "yes"
+    on_mismatch: return
+    message_var: fl_status
+    on_mismatch_message: "not scaffolded — files the {{fl_name}} pack writes already exist under {{fl_source_path}} and overwriting them was declined"
+
+  # 4. The pack's rule file: which of its files are merged with what the lane holds now.
+  #    Read before anything is written, so a broken rule file leaves the lane untouched;
+  #    the files to merge with are put aside under fp_merge_state.
+  - id: fp_rules
+    action: execute_script
+    script: { ref: actions }
+    subcommand: foundation-rules
+    args: ["--name", "{{fl_name}}", "--app", "{{app}}", "--out", "{{fl_source_path}}", "--state", "{{fp_merge_state}}"]
+    outputs:
+      - { name: fp_rules_ok,     from: "$.ok" }
+      - { name: fp_rules_reason, from: "$.reason" }
+      - { name: fp_rules_file,   from: "$.rules_file" }
+      - { name: fp_merges,       from: "$.merges" }
+      - { name: fp_rules_note,   from: "$.note" }
+
+  - id: fp_rules_gate
+    action: verify_context
+    require_true: fp_rules_ok
+    on_false: return
+    message_var: fl_status
+    on_false_message: "not scaffolded — {{fp_rules_reason}}; nothing was written to {{fl_source_path}}"
+
+  # 5. Unpack for real, and check it worked: an unpacker that refuses (existing files, a
+  #    bad name) exits non-zero with 0 files written, and reporting that as a scaffold is
+  #    how a lane with no project gets as far as implement.
+  - id: fp_unpack
+    action: execute_script
+    script: { ref: actions }
+    subcommand: foundation-unpack
+    args: ["--name", "{{fl_name}}", "--app", "{{app}}", "--out", "{{fl_source_path}}", "--test-path", "{{fl_test_path}}", "--force", "{{fp_overwrite}}"]
+    outputs:
+      - { name: fp_ok,            from: "$.ok" }
+      - { name: fp_written,       from: "$.written" }
+      - { name: fp_tests_message, from: "$.tests_message" }
+      - { name: fp_unpack_out,    from: "$.stdout" }
+
+  - id: fp_unpack_gate
+    action: verify_context
+    require_true: fp_ok
+    on_false: return
+    message_var: fl_status
+    on_false_message: "NOT scaffolded — the {{fl_name}} unpacker failed and wrote {{fp_written}} file(s). Its output ends: {{fp_unpack_out}}"
+
+  # 6. The merges the rule file asks for: the file that was there (put aside) and the
+  #    pack's version (now on disk) become one, as the rule's instruction says.
+  - id: fp_merge
+    action: loop
+    over: "{{fp_merges}}"
+    as: m
+    steps:
+      - id: fp_merge_file
+        action: agent_author
+        context: ["{{m.existing}}", "{{m.target}}"]
+        include_standards: false
+        task: |
+          Merge two versions of {{m.target}} into one file.
+            EXISTING  {{m.existing}} — the file as it was in the lane before the {{fl_name}} pack was unpacked
+            INCOMING  {{m.target}} — the file as the pack ships it, with {{fp_sentinel}} renamed to {{app}}
+          The pack's rule file ({{fp_rules_file}}) says how, in its rule for {{m.rule}}:
+          {{m.instruction}}
+          Change nothing that instruction does not ask for.
+        output_target: { type: file, path: "{{m.target}}" }
+
+  - id: fp_rules_done
+    action: execute_script
+    script: { ref: actions }
+    subcommand: foundation-rules-done
+    args: ["--state", "{{fp_merge_state}}"]
+
+  # 7. Optional reference sample — offered only when the pack ships one. It goes on top
+  #    of the base project the same way: its own rule file, the unpack, its merges.
+  - id: fp_ask_reference
+    action: ask
+    condition: "{{fp_has_reference}} == true"
+    prompt: "The {{fl_name}} foundation also ships a reference sample ({{fl_name}}.Reference.pack.txt): worked example code unpacked on top of the base project. Include it?"
+    options: ["yes", "no"]
+    answer_var: fp_want_reference
+
+  - id: fp_ref_rules
+    action: execute_script
+    condition: "{{fp_want_reference}} == yes"
+    script: { ref: actions }
+    subcommand: foundation-rules
+    args: ["--name", "{{fl_name}}", "--app", "{{app}}", "--out", "{{fl_source_path}}", "--reference", "--state", "{{fp_merge_state}}"]
+    outputs:
+      - { name: fp_ref_rules_ok,     from: "$.ok" }
+      - { name: fp_ref_rules_reason, from: "$.reason" }
+      - { name: fp_ref_rules_file,   from: "$.rules_file" }
+      - { name: fp_ref_merges,       from: "$.merges" }
+      - { name: fp_ref_rules_note,   from: "$.note" }
+
+  # A broken rule file keeps the sample out but leaves the base project in place, so this
+  # reports and carries on rather than returning.
+  - id: fp_ref_rules_gate
+    action: verify_context
+    condition: "{{fp_want_reference}} == yes"
+    require_true: fp_ref_rules_ok
+    on_false: continue
+    message_var: fp_ref_note
+    on_false_message: "; the reference sample was NOT added — {{fp_ref_rules_reason}}"
+
+  - id: fp_ref_go
+    action: set
+    condition: "{{fp_ref_rules_ok}} == true"
+    vars: { fp_ref_go: "yes" }
+
+  - id: fp_reference_unpack
+    action: execute_script
+    condition: "{{fp_ref_go}} == yes"
+    script: { ref: actions }
+    subcommand: foundation-unpack
+    args: ["--name", "{{fl_name}}", "--app", "{{app}}", "--out", "{{fl_source_path}}", "--test-path", "{{fl_test_path}}", "--reference"]
+    outputs:
+      - { name: fp_ref_ok,            from: "$.ok" }
+      - { name: fp_ref_written,       from: "$.written" }
+      - { name: fp_ref_tests_message, from: "$.tests_message" }
+      - { name: fp_ref_out,           from: "$.stdout" }
+
+  # A failed reference sample does not undo the base project, so this reports and carries
+  # on to the residue check rather than returning.
+  - id: fp_reference_gate
+    action: verify_context
+    condition: "{{fp_ref_go}} == yes"
+    require_true: fp_ref_ok
+    on_false: continue
+    message_var: fp_ref_note
+    on_false_message: "; the reference sample FAILED to unpack ({{fp_ref_out}})"
+
+  - id: fp_reference_done
+    action: set
+    condition: "{{fp_ref_ok}} == true"
+    vars: { fp_ref_note: "; reference sample added ({{fp_ref_written}} file(s))" }
+
+  # The sample's own test tree is lifted onto the lane's test path like the base pack's;
+  # say what happened to it, or the lane line reports only the base pack's tests.
+  - id: fp_reference_tests_noted
+    action: set
+    condition: "{{fp_ref_tests_message}} != "
+    vars: { fp_ref_note: "{{fp_ref_note}} — its tests: {{fp_ref_tests_message}}" }
+
+  # The sample's merges: what the base project (or the lane before it) had, and the
+  # sample's version, become one as the sample's rule file says.
+  - id: fp_ref_merge
+    action: loop
+    condition: "{{fp_ref_ok}} == true"
+    over: "{{fp_ref_merges}}"
+    as: m
+    steps:
+      - id: fp_ref_merge_file
+        action: agent_author
+        context: ["{{m.existing}}", "{{m.target}}"]
+        include_standards: false
+        task: |
+          Merge two versions of {{m.target}} into one file.
+            EXISTING  {{m.existing}} — the file as it was in the lane before the {{fl_name}} reference sample was unpacked
+            INCOMING  {{m.target}} — the file as the reference sample ships it, with {{fp_sentinel}} renamed to {{app}}
+          The sample's rule file ({{fp_ref_rules_file}}) says how, in its rule for {{m.rule}}:
+          {{m.instruction}}
+          Change nothing that instruction does not ask for.
+        output_target: { type: file, path: "{{m.target}}" }
+
+  - id: fp_ref_merged_noted
+    action: set
+    condition: "{{fp_ref_ok}} == true"
+    vars: { fp_ref_note: "{{fp_ref_note}}{{fp_ref_rules_note}}" }
+
+  - id: fp_ref_rules_done
+    action: execute_script
+    condition: "{{fp_ref_go}} == yes"
+    script: { ref: actions }
+    subcommand: foundation-rules-done
+    args: ["--state", "{{fp_merge_state}}"]
+
+  # 8. Verify — sentinel residue must be zero in the generated tree.
+  - id: fp_verify
+    action: execute_script
+    script: { ref: actions }
+    subcommand: foundation-verify
+    args: ["--out", "{{fl_source_path}}", "--sentinel", "{{fp_sentinel}}"]
+    outputs:
+      - { name: fp_clean,   from: "$.clean" }
+      - { name: fp_residue, from: "$.residue" }
+
+  - id: fp_residue_clean
+    action: set
+    condition: "{{fp_clean}} == true"
+    vars: { fp_residue_note: "no sentinel left" }
+
+  - id: fp_residue_found
+    action: set
+    condition: "{{fp_clean}} == false"
+    vars: { fp_residue_note: "SENTINEL {{fp_sentinel}} STILL IN {{fp_residue}}" }
+
+  - id: fp_tests_noted
+    action: set
+    condition: "{{fp_tests_message}} != "
+    vars: { fp_tests_note: "; {{fp_tests_message}}" }
+
+  - id: fp_done
+    action: set
+    vars:
+      fl_files: "{{fp_written}}"
+      fl_status: "scaffolded from the {{fl_name}} pack — {{fp_written}} file(s) into {{fl_source_path}}{{fp_tests_note}}{{fp_rules_note}}{{fp_ref_note}}; {{fp_residue_note}}"