aw-spec-cli 0.1.7 → 0.1.9

package/assets/.appweaver/orchestrator/workflows/aw-spec-add-component.orch.yaml

@@ -0,0 +1,270 @@
+# =============================================================================
+# aw-spec-add-component (orchestrator) — add an opt-in AppWeaver framework component
+#
+# Picks a component from
+# foundations/<ecosystem>/components/ for the ecosystem the backend lane declares, parses its
+# implementation catalog, asks which implementation(s)
+# to wire, resolves the host/startup project (via Program.cs), authors the edits
+# STRICTLY from the component's integration.md runbook, then VERIFIES the wiring
+# (dotnet build + the R0.2a dual-registration guard, self-correcting up to 2×).
+#
+# This is the ONLY place framework components are installed. `implement` codes an
+# aggregate against a component's PORT (e.g. IEmailService) but never wires the
+# component itself — run this after implement (or whenever a port needs a provider).
+# The per-component foundations/<ecosystem>/components/<C>/integration.md runbook is the AUTHORITY on
+# what to add; the model reads it (in context) and authors the edits from it. It is
+# pure technology (domain-agnostic) — no domain rule files are involved.
+#
+# Prereq: a scaffolded host project (/appweaver foundation) — components wire INTO it.
+#
+# Launch:  /appweaver add-component [strategy] [ComponentName]
+#   e.g.  /appweaver add-component Email
+# Action semantics: .appweaver/ORCH-DIALECT.md
+# =============================================================================
+
+name: aw-spec-add-component
+description: Add an opt-in AppWeaver framework component — pick one from the declared ecosystem's foundations/<ecosystem>/components/, choose implementation(s) from its catalog, wire the code in per its integration.md runbook, and verify the build + dual-registration. Pure technology; not a per-feature phase.
+version: 1.0.0
+agent_agnostic: true
+dialect: aw-spec.orchestrator/v1
+
+inputs:
+  user_input:
+    description: Optional component folder name to select directly (e.g. Email).
+    required: false
+    bind: USER_INPUT
+
+scripts:
+  actions:
+    sh:  .appweaver/scripts/bash/aw-spec-actions.sh
+    ps1: .appweaver/scripts/powershell/aw-spec-actions.ps1
+
+standards:
+  - { path: .appweaver/ai-rules.md }   # kit-resident: the universal operating rules, every flow
+
+vars:
+  verify_ok: "false"     # verify-loop guard, flipped by component-verify
+
+workflow:
+
+  # 1. Discover components — foundations/<ecosystem>/components/* that have an integration.md,
+  #    for the ecosystem the BACKEND lane declares. The dir it resolved is echoed back as
+  #    components_dir and every later path is built from it, so the runbook the model reads
+  #    is always the one for the stack the code is actually in.
+  - id: list_components
+    action: execute_script
+    script: { ref: actions }
+    subcommand: list-components
+    outputs:
+      - { name: components,     from: "$.components" }
+      - { name: components_dir, from: "$.dir" }
+      - { name: components_eco, from: "$.ecosystem" }
+
+  - id: guard_components
+    action: verify_context
+    require_non_empty: components
+    on_empty: stop
+    on_empty_message: >
+      No components are available for the `{{components_eco}}` ecosystem this repository
+      declares in .appweaver/stacks.json — {{components_dir}}/ holds no runbook. A component
+      is installed by editing the host project's build files and its startup registration,
+      so it only exists for the ecosystem whose build files it knows how to edit; a
+      component from another ecosystem is not a substitute. Add one under
+      {{components_dir}}/<Name>/integration.md (see the README in that tree for the
+      expected layout), or wire the capability with the stack's own libraries — implement
+      already codes against the design's PORT, and add-component only supplies a provider.
+
+  # 2. Select the component (direct arg fast-path, else interactive; lone option confirms).
+  - id: select_component
+    action: user_select
+    prompt: "Select a component to add:"
+    options_from_variable: components
+    preselect_from: USER_INPUT
+    single_option_confirm: true
+    outputs:
+      - { name: chosen, from: selection }
+
+  - id: guard_chosen
+    action: verify_context
+    require_non_empty: chosen
+    on_empty: stop
+    on_empty_message: "No component selected — nothing to do."
+
+  # 3. Extract the implementation catalog from the runbook — DETERMINISTIC markdown
+  #    table parse (script, NO model). integrable=false when no catalog table exists.
+  - id: extract_catalog
+    action: execute_script
+    script: { ref: actions }
+    subcommand: component-catalog
+    args: ["--file", "{{components_dir}}/{{chosen}}/integration.md"]
+    outputs:
+      - { name: integrable,      from: "$.integrable" }
+      - { name: impl_keys,       from: "$.impl_keys" }
+      - { name: implementations, from: "$.implementations" }
+
+  - id: catalog_gate
+    action: verify_context
+    require_true: integrable
+    on_false: stop
+    on_false_message: "Component '{{chosen}}' is not integrable via this command (no implementation catalog in integration.md)."
+
+  # 4. Select implementation(s) (multi-select). Empty selection => leave untouched.
+  - id: select_impls
+    action: ask
+    prompt: "Select one or more '{{chosen}}' implementations to wire in (honor the runbook's grouping rules):"
+    options_from: "{{impl_keys}}"
+    multi: true
+    answer_var: chosen_impls
+
+  - id: guard_selection
+    action: verify_context
+    require_non_empty: chosen_impls
+    on_empty: stop
+    on_empty_message: "No implementation selected — project left untouched. Re-run /appweaver add-component any time."
+
+  # 5. Resolve the host/startup project (by locating Program.cs).
+  - id: find_host
+    action: execute_script
+    script: { ref: actions }
+    subcommand: find-host-project
+    outputs:
+      - { name: host_found,  from: "$.found" }
+      - { name: host_dir,    from: "$.project_dir" }
+      - { name: program_cs,  from: "$.program_cs" }
+      - { name: host_csproj, from: "$.csproj" }
+      - { name: host_eco,    from: "$.ecosystem" }
+      - { name: host_search, from: "$.searched" }
+
+  - id: host_gate
+    action: verify_context
+    require_true: host_found
+    on_false: stop
+    on_false_message: >
+      No .NET host/startup project found — nothing named Program.cs under `{{host_search}}`,
+      the source path the backend lane declares, nor elsewhere in this repository. Wiring a
+      component means editing a host project's startup registration, so there has to be one
+      to edit. If this is a .NET repository, scaffold it first with /appweaver foundation.
+      If it is not — this lane's ecosystem is `{{host_eco}}` — then this catalogue's runbooks
+      do not apply to it: components are per-ecosystem, and the capability should be wired
+      with the stack's own libraries against the port the design declares.
+
+  # 6. Pre-execution hooks.
+  - id: resolve_pre_hooks
+    action: execute_script
+    script: { ref: actions }
+    subcommand: resolve-hooks
+    args: ["--phase", "before_addcomponent"]
+    outputs:
+      - { name: before_hooks, from: "$.hooks" }
+  - id: dispatch_pre_hooks
+    action: dispatch_hooks
+    hooks_from_variable: before_hooks
+
+  # 7. Plan the concrete file edits from the runbook + selected implementations.
+  - id: plan_edits
+    action: agent_query
+    context: ["{{components_dir}}/{{chosen}}/integration.md"]
+    include_standards: false
+    task: |
+      Using the runbook (in context) apply the "Common steps" plus each selected
+      implementation's block for: {{chosen_impls}}. The host/startup project is
+      {{host_dir}} (Program.cs at {{program_cs}}; csproj {{host_csproj}}). Honor the
+      cross-cutting rules (versions only in Directory.Packages.props; register in the
+      host project's AddInfrastructure AND AddAspireInfrastructure when both exist; set
+      options.Provider; never commit secrets). Return ONLY JSON listing each file to
+      create or edit, the active provider, and the exact registration marker token a
+      deterministic guard can look for in each infrastructure-registration method.
+    schema: { edits: [ { path: "<repo-relative path>", purpose: "<one line>" } ], active_provider: "<provider key>", registration_marker: "<exact code token that MUST appear in each infra-registration method>" }
+    mock: { edits: [], active_provider: "", registration_marker: "" }
+    outputs:
+      - { name: edits,               from: "$.edits" }
+      - { name: active_provider,     from: "$.active_provider" }
+      - { name: registration_marker, from: "$.registration_marker" }
+
+  # 8. Apply each edit — full updated file content, guided by the runbook in context.
+  #    build_context loads the runbook envelope; the agent Reads each target file.
+  - id: ctx_apply
+    action: build_context
+    context:
+      - { path: "{{components_dir}}/{{chosen}}/integration.md" }
+      - { path: "{{components_dir}}/{{chosen}}/README.md", optional: true }
+  - id: apply_loop
+    action: loop
+    over: "{{edits}}"
+    as: e
+    steps:
+      - id: apply_edit
+        action: agent_generate
+        tools: "Read,Write,Edit"
+        permission_mode: acceptEdits
+        task: |
+          Apply the '{{chosen}}' component runbook edit (integration.md in context) to the
+          single file {{e.path}} — {{e.purpose}}. Selected implementations: {{chosen_impls}};
+          active provider: {{active_provider}}; host project: {{host_dir}}.
+          Read {{e.path}} first if it exists and PRESERVE all existing content, applying
+          ONLY the runbook's additions (package version, PackageReference, registration
+          line, config); create it if absent. Change NO other file.
+        outputs:
+          - { name: applied_files, from: "$.files" }
+
+  # 9. Post-wiring verification — `dotnet build` the host project + the R0.2a
+  #    dual-registration guard (a script, NO model judgment), self-correcting up to 2×.
+  #    Build degrades gracefully (skipped => ok) when the .NET SDK is absent.
+  - id: ctx_verify
+    action: build_context
+    context:
+      - { path: "{{components_dir}}/{{chosen}}/integration.md" }
+  - id: verify_loop
+    action: loop
+    while: "{{verify_ok}} != true"
+    max_iterations: 2
+    steps:
+      - id: verify
+        action: execute_script
+        script: { ref: actions }
+        subcommand: component-verify
+        args: ["--host-dir", "{{host_dir}}", "--host-csproj", "{{host_csproj}}", "--marker", "{{registration_marker}}"]
+        outputs:
+          - { name: verify_ok,      from: "$.ok" }
+          - { name: verify_can_fix, from: "$.can_fix" }
+          - { name: fix_target,     from: "$.fix_target" }
+          - { name: fix_reason,     from: "$.fix_reason" }
+      - id: verify_break
+        action: break
+        condition: "{{verify_ok}} == true"
+      - id: verify_fix
+        action: agent_generate
+        condition: "{{verify_can_fix}} == true"
+        tools: "Read,Write,Edit"
+        permission_mode: acceptEdits
+        task: |
+          The '{{chosen}}' component wiring failed verification. Fix ONLY the file
+          {{fix_target}} to resolve it, following the integration.md runbook (in context)
+          and preserving all unrelated existing content. If the issue is R0.2a dual
+          registration, add the component's registration to that method exactly as the
+          other registration method already has it (adjusting only provider-specific calls).
+            Reason: {{fix_reason}}
+          Read {{fix_target}} first; change NO other file.
+
+  # 10. Post-execution hooks.
+  - id: resolve_post_hooks
+    action: execute_script
+    script: { ref: actions }
+    subcommand: resolve-hooks
+    args: ["--phase", "after_addcomponent"]
+    outputs:
+      - { name: after_hooks, from: "$.hooks" }
+  - id: dispatch_post_hooks
+    action: dispatch_hooks
+    hooks_from_variable: after_hooks
+
+outputs:
+  component: "{{chosen}}"
+  implementations: "{{chosen_impls}}"
+  active_provider: "{{active_provider}}"
+  edits: "{{edits}}"
+  host_project: "{{host_dir}}"
+  build_verified: "{{verify_ok}}"
+  verify_detail: "{{fix_reason}}"
+  note: "Component wired in and verified (dotnet build + R0.2a dual-registration guard). If build_verified is false, verify_detail says what still needs a manual touch. Complete any out-of-band follow-ups (secrets, migrations, DDL) the runbook calls for."
+  next: "Run /appweaver build to compile, or continue implementing features that depend on this component's port."