Skip to content

infrastructure: WP-CLI commands as a capability interface #35

Open

Description

@schlessera

Context

src/Infrastructure/ServiceBasedPlugin.php:1731-1821 schedules/conditionally registers services, and :2152-2168 stores non-Registerable services lazily. src/BasicScaffoldPlugin.php:322-324 defines the existing hook/service prefixes. No WP-CLI capability or WP-CLI registration call exists in the reviewed src/ tree.

Services that provide WP-CLI commands have to register them themselves today. The AMP plugin, built on this scaffold, added a CliCommand capability interface: the service declares its command name, and when running under WP-CLI the plugin builds it eagerly (lazy storage would hide the interface) and calls WP_CLI::add_command(). This fits the core idea: a lifecycle point gets a capability interface instead of a conditional inside the service.

Next step: design proposal

The software design is not settled yet. Once this issue's other needs: labels are resolved, the next deliverable is a design proposal posted as a comment on this issue: what is already decided, the options with their trade-offs and how each fits docs/design-principles.md, and a recommendation. After posting it, the issue moves to needs: decision (see the github skill, "Unsettled software design"). The proposal should answer:

the interface shape (a static command name, synopsis or a full registration array), how the prefix is applied, and whether parent command namespaces are declared separately.

Scope

  • A capability interface for WP-CLI commands, orchestrated by the plugin, with command names carrying the plugin's prefix (principle 13).

Out of scope

  • Shipping sample commands beyond one teaching example.

Acceptance criteria

  • A service implementing the interface is registered with WP-CLI only under WP-CLI; tests with a WP-CLI stand-in.
  • Errors while registering a command follow the exception boundary (principle 10).

Verification

composer test
composer lint

Impact on generated plugins

Additive.

Remaining readiness gaps

Name one concrete command the scaffold should teach (its inputs/output and why its lifecycle needs infrastructure support). Once that scenario is supplied, an agent can prepare the design proposal for command metadata, prefix/namespace rules and Conditional/Delayed interactions; the maintainer approves the concrete proposal before implementation. Do not require the maintainer to invent the API before proposal work can begin. The exception-boundary acceptance criterion depends on the general callback/lifecycle boundary, now investigated in #143; unblock only once that mechanism is settled and usable.

Blocked by #143

Priority remains p3: this is parked capability expansion, without a concrete sample command yet.

Updated 2026-10-22: triaged against origin/main at 055978329c94b0fbbda5832f582ee727ca7bdecd; factual checks and remaining gaps are recorded above.

Updated 2026-10-22: needs: design is now reserved for visual design, so that label was removed. The design proposal is the next deliverable once the remaining needs: labels from triage are resolved.

Updated 2026-10-22: verified source anchors and native membership under #18 at origin/main bc789c1fa7f9cc416ef2003bb8ce45fa7d43527c. #27 remains open; its next deliverable is the exception-boundary design proposal, so the implementation dependency remains. The concrete teaching command is still missing.

Updated 2026-10-23: verified source at origin/main ccda54a8c8d0a386191a8488618f18fe0e3d2390 and repaired the shifted composition-root prefix citation after #19. The teaching-command scenario is still absent and #27 remains open.

Updated 2026-10-23: #27 was narrowed by maintainer ruling to view-only graceful degradation and closed by #150. The general exception boundary this issue needs moved to #143, so the blocker now points there; blocked stays.

Updated 2026-10-23: Rechecked 1133d65 and repaired scheduling/lazy/prefix or sample-hook anchors. The teaching command is still unspecified and #143 remains the open exception-boundary dependency; no API was invented.

Updated 2026-10-23: Verified current main 61a9b00 and repaired orchestration/lazy/prefix or sample-hook anchors after #163/#167. The concrete teaching scenario is still missing; no capability API or policy was selected. #143 remains the exception-boundary blocker.

Updated 2026-10-24: Repaired scheduling, lazy-instantiation and prefix anchors. Still needs a concrete teaching command with inputs/output and lifecycle requirements, and remains Blocked by #143 for the exception boundary; p3 and needs: use-case stay. Reviewed origin/main 15cac4c2.

Activity

  1. added
    type: featA new capability or a change in behaviour.
    area: infrastructuresrc/Infrastructure: services, injector, views, autoloader. What generated plugins build on.
    priority: p3Someday. Needs a driving use case before it starts.
    needs: designBlocked on visual design (UI, website, graphics). Software design is proposal work, not this label.
    on Oct 22, 2026
  2. added
    needs: use-caseDeliberately parked until something real drives it.
    blockedWaiting on another issue. Name it on a 'Blocked by #N' line in the body.
    on Oct 22, 2026
  3. schlessera commented on Oct 22, 2026

    @schlessera
    MemberAuthor

    Triage (2026-10-22): Added local scheduling/lazy/prefix anchors and recorded Blocked by #27 for the explicit exception-boundary criterion. Kept needs: design and added needs: use-case: name the actual teaching command and its inputs/output before choosing its capability API. Retained p3 as parked expansion.

  4. added
    agent-readyContext and acceptance criteria are complete enough for an agent to take this unattended.
    and removed
    needs: designBlocked on visual design (UI, website, graphics). Software design is proposal work, not this label.
    agent-readyContext and acceptance criteria are complete enough for an agent to take this unattended.
    on Oct 22, 2026
  5. schlessera commented on Oct 22, 2026

    @schlessera
    MemberAuthor

    Triage (2026-10-22): Verified current source anchors and parent #18. Retained needs: use-case and Blocked by #27: supply a specific command, its inputs/output and the lifecycle need; #27 must provide the usable exception boundary for implementation. Clarified that agents propose the API after the scenario is supplied, then seek the maintainer ruling. No command scenario or design was invented.

  6. schlessera commented on Oct 23, 2026

    @schlessera
    MemberAuthor

    Triage (2026-10-23): Corrected the composition-root prefix citation to :196-198 after #19. Existing blockers remain: supply a concrete command with inputs/output and the lifecycle requirement; #27 must provide the usable exception boundary. No scenario, API or policy was invented.

  7. schlessera commented on Oct 23, 2026

    @schlessera
    MemberAuthor

    Triage (2026-10-23): Rechecked 1133d65 and repaired scheduling/lazy/prefix or sample-hook anchors. The teaching command is still unspecified and #143 remains the open exception-boundary dependency; no API was invented.

  8. schlessera commented on Oct 23, 2026

    @schlessera
    MemberAuthor

    Triage (2026-10-23): Verified current main 61a9b00 and repaired orchestration/lazy/prefix or sample-hook anchors after #163/#167. The concrete teaching scenario is still missing; no capability API or policy was selected. #143 remains the exception-boundary blocker.

  9. schlessera commented on Oct 24, 2026

    @schlessera
    MemberAuthor

    Triage (2026-10-24): Repaired scheduling, lazy-instantiation and prefix anchors. Still needs a concrete teaching command with inputs/output and lifecycle requirements, and remains Blocked by #143 for the exception boundary; p3 and needs: use-case stay.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    area: infrastructuresrc/Infrastructure: services, injector, views, autoloader. What generated plugins build on.blockedWaiting on another issue. Name it on a 'Blocked by #N' line in the body.needs: use-caseDeliberately parked until something real drives it.priority: p3Someday. Needs a driving use case before it starts.type: featA new capability or a change in behaviour.

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions