aw-spec-cli 0.1.3 → 0.1.5

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

@@ -0,0 +1,244 @@
+# =============================================================================
+# aw-spec-add-component (orchestrator) — add an opt-in AppWeaver framework component
+#
+# Picks a component from
+# docs/components/*, 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 docs/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 (/aw-spec-orch foundation) — components wire INTO it.
+#
+# Launch:  /aw-spec-orch add-component [strategy] [ComponentName]
+#   e.g.  /aw-spec-orch add-component Email
+# Action semantics: .aw-spec/ORCH-DIALECT.md
+# =============================================================================
+
+name: aw-spec-add-component
+description: Add an opt-in AppWeaver framework component — pick one from docs/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:  .aw-spec/scripts/bash/aw-spec-actions.sh
+    ps1: .aw-spec/scripts/powershell/aw-spec-actions.ps1
+
+vars:
+  verify_ok: "false"     # verify-loop guard, flipped by component-verify
+
+workflow:
+
+  # 1. Discover components (docs/components/* that have an integration.md).
+  - id: list_components
+    action: execute_script
+    script: { ref: actions }
+    subcommand: list-components
+    outputs:
+      - { name: components, from: "$.components" }
+
+  - id: guard_components
+    action: verify_context
+    require_non_empty: components
+    on_empty: stop
+    on_empty_message: "No components available. See docs/components/README.md for the expected layout."
+
+  # 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", "docs/components/{{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 /aw-spec-orch 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" }
+
+  - id: host_gate
+    action: verify_context
+    require_true: host_found
+    on_false: stop
+    on_false_message: "No host/startup project found (no Program.cs) — run /aw-spec-orch foundation first."
+
+  # 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: ["docs/components/{{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: "docs/components/{{chosen}}/integration.md" }
+      - { path: "docs/components/{{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: "docs/components/{{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 /aw-spec-orch build to compile, or continue implementing features that depend on this component's port."