AIFACTORY-FEAT-187: Commands of the command-line client against the control plane gateway¶
Generated from the architecture model
This page is rendered from model/**/*.yaml by tools/docs_model during mkdocs build. Edit the YAML, not this page; hand-written design lives on the linked service, platform and plane pages.
A design artefact, not a tracker
This backlog is generated from model/backlog/ and validated against the architecture model. No work item exists in any tracker, and no item carries a date, an estimate or an assignee (ADR-0029).
Epic Engineering readiness · Increment I1 Generate a microservice · State elaborated · Route backend-developer · Build order 84 of 185 (Factory code)
The command-line client of the first outcome gets its commands once the services they call exist: submit a vision, follow a run, approve a recipe and approve a change proposal run against the control plane gateway through the pinned typed client, with the user token of the signed-in member. The repository, the skeleton and the sign-in of the client are delivered in I0 by the feature command-line-client (owner decision D117).
| Delivers | — |
| Stubs | — |
| Realizes | — |
| Requirements | — |
| Depends on | AIFACTORY-FEAT-093 Command-line client for the first outcomeAIFACTORY-FEAT-002 ControlPlaneApi: gateway deliveryAIFACTORY-FEAT-178 Typed client libraries for the Factory gateways from the API library template |
| Sources | docs/architecture/capability-dependencies.md, docs/ai-software-factory/current-state.md |
AIFACTORY-US-376: Command-line client: the projects, submit, status, watch, approvals, approve and reject commands call the modelled control plane operations through the pinned client and explain every refusal¶
enabling · persona requester
As a requester, I want commands to see my projects, submit a vision, follow the run and decide its approvals, so that the first outcome can be driven end to end from a terminal.
The first outcome is four acts of a person: submit a vision, follow a run, approve a recipe and approve a change proposal. This PBI gives a command to the three acts on the control plane; the recipe act calls the template catalog gateway, because GenerationRecipeService is fronted by TemplateCatalogHost and the client reaches no service host directly (decision D123), and its commands recipe show and recipe approve are delivered by AIFACTORY-US-1507 of this feature. Owner decision D117 places the commands in increment I1, where the services they call exist: the repository, the skeleton and the sign-in of the client are delivered in increment I0 by the feature command-line-client, and the commands are written into that skeleton here. Every command calls one public REST operation of the control plane as the model states it, through the control plane gateway and through nothing else (ADR-0028 decision 2), and holds no business rule of its own. projects calls ListProjects of ProjectService and prints the key, the name and my role for each project my membership grants. submit sends a run submission of the descriptor run-submission-v1 to SubmitRun of RunControlService with an idempotency key that the client generates once for the submission and reuses when it retries, so that the same key with the same input prints the same accepted run and the same key with another input prints a conflict (ADR-0014 decision 3). status reads one run with GetRun. watch has no operation of its own: the model has no public stream, and RunControl.WatchRun is an internal gRPC server stream for the BFF and the workers that a public caller cannot use. watch therefore polls GetRun, GET /factory/runs/{runId} under the scope factory.runs.read, at a configurable interval until the run is Completed, Failed or Cancelled, prints each change of the run, of its steps and of its pending approvals, and stops on 404 or 403 with the explanation of the class; whether a public stream is wanted later is open for the owner. approvals list reads the approval requests visible to my roles with ListApprovals, and approve and reject send a decision of the descriptor approval-decision-v1 to DecideApproval that quotes the version of the request it decides. A run-level spend approval, which has no step (decision D117), is listed and decided by the same commands. A refused command explains the refusal from the problem response and ends with a failure code of its class. 401 asks me to sign in again. 403 names the scope or the right I lack inside my tenant. 404 says not found, and is the same answer for an identifier that does not exist and for a resource of another tenant, which the client cannot and does not tell apart (ADR-0015 amendment on a resource of another tenant). 409 prints the reason the service gives; on a decision it has the two causes the model states: the quoted version no longer matches, or the request is already decided, Stale or Cancelled. 410 says that the approval request expired and that the run follows the expiry rule of its request; the decision was not recorded. 400 prints the fields that failed validation. 503, the answer of the gateway for a fronted service that is unavailable, prints the retry hint, is not retried blindly and has a failure code of its own. The commands reach the gateway through the one client port of the skeleton. Behind that port stands the control plane client of feature typed-gateway-clients in its user-token layout, pinned at its published version from the ConnectSoft feed: it takes the place of the hand-written adapter of the skeleton, and the client repository holds no second HTTP call to the control plane gateway. The pinned client attaches the user token of the signed-in member for the audience of the control plane gateway only to requests to the base address of that gateway. The gateway forwards that token to the service it fronts, and the service accepts the audience of its gateway, so that one token serves every command of this PBI and nothing is exchanged on the way; the recipe commands use a second token, requested for the audience of the template catalog gateway (AIFACTORY-US-1507) (ADR-0015 amendments on the one audience of a user token and on the forwarded user token). The commands are proven against the real gateway and not against a contract stub. The acceptance suite of the client repository runs the built commands against the acceptance environment that feature local-development-environment defines, in which ControlPlaneApi fronts ProjectService and RunControlService and the authorization server of the Factory instance of the Identity Platform issues the tokens. The fixture uses the fixture tenant and project of that environment with two members, a requester and a reviewer, because the requester of a run is never eligible to decide its approvals. The workflow chain that raises approvals in a real run is delivered by other features of the increment, so a worker stand-in of the fixture raises the approval requests of the fixture run through the internal operation RunControl.RequestApproval, one of them with an expiry that has passed. Request bodies are the types of the pinned contracts package. The responses of SubmitRun, GetRun and ListApprovals name the descriptors run-accepted-v1, run-view-v1 and approval-list-v1, for which no schema file defines a shape today; the client prints the run and approval state those responses carry as the pinned control plane client types them from the OpenAPI document of the gateway, and a reading through types of the contracts package waits for the open question recorded with feature contracts-package.
Acceptance criteria
| AC1 | Given I am signed in, when I list projects, then the command calls ProjectService/ListProjects, the list operation that model/services/control-plane/ProjectService.yaml names, through the control plane gateway and prints, for exactly the projects my membership grants, the project key, the name and my role (ADR-0015 decisions 5 and 6). |
| AC2 | Given a run submission, when I submit it, then the command sends a document of run-submission-v1 to RunControlService/SubmitRun with an idempotency key it generated once; a repeated submit with the same key and the same input prints the same accepted run, and the same key with another input prints the conflict (ADR-0014 decision 3; model/services/control-plane/RunControlService.yaml names the operation and its codes). |
| AC3 | Given a submitted run, when I run status, approvals list, approve or reject, then each command calls its modelled operation (RunControlService/GetRun, RunControlService/ListApprovals, RunControlService/DecideApproval) through the control plane gateway and prints the run or approval state the service returned, a decision of approval-decision-v1 quotes the version of the request it decides, and a run-level spend approval without a step is listed and decided like any other; and when I run watch, then the client polls GetRun, GET /factory/runs/{runId} under the scope factory.runs.read, at a configurable interval, prints each change of the run, its steps and its pending approvals, ends when the run is Completed, Failed or Cancelled, stops on 404 or 403 with the explanation of the class, and never calls the internal stream WatchRun (ADR-0028 decision 2; model/services/control-plane/RunControlService.yaml). |
| AC4 | Given a command that the gateway or a service refuses, when the answer is 401, 403, 404, 409, 410, 400 or 503, then the client prints the explanation of that class from the problem response and ends with the failure code of the class: a 404 for a resource of another tenant reads exactly as a 404 for an identifier that does not exist; a 409 on a decision says that the quoted version no longer matches or that the request is already decided, Stale or Cancelled; a 410 says that the approval request expired, that the run follows the expiry rule of its request and that the decision was not recorded; a 503 prints the retry hint and is not retried blindly (ADR-0015 amendment on a resource of another tenant; model/services/control-plane/RunControlService.yaml lists the codes of DecideApproval, and model/services/control-plane/ControlPlaneApi.yaml the 503 of an unavailable fronted service). |
| AC5 | Given the client repository, when its architecture test runs, then the control plane client of feature typed-gateway-clients in the user-token layout is pinned at its published version from the ConnectSoft feed and is the only adapter to the control plane gateway behind the client port, the hand-written adapter of the skeleton is removed, no other type of the repository sends a request to that gateway, the only other adapter is the pinned template catalog gateway client of AIFACTORY-US-1507 for the other gateway, and the user token of the control plane audience is attached only to requests to the base address of the control plane gateway (ADR-0028 decision 2; ADR-0015 amendment on the one audience of a user token; model/backlog/pbis/engineering-readiness/typed-gateway-clients.yaml names the package). |
| Traces: apis | ProjectService/ListProjects, RunControlService/SubmitRun, RunControlService/GetRun, RunControlService/ListApprovals, RunControlService/DecideApproval |
| Traces: descriptors | run-submission-v1, approval-decision-v1 |
| Traces: adrs | ADR-0014, ADR-0015, ADR-0028 |
| Depends on | feature:command-line-client, feature:control-plane-api, feature:typed-gateway-clients, feature:project-service, feature:run-control-service, feature:contracts-package, feature:local-development-environment |
| Sources | docs/architecture/capability-dependencies.md, docs/architecture/adr/0015-factory-tenancy-under-canonical-adr-0100.md, docs/reference/schemas/run-submission.schema.json, docs/reference/schemas/approval.schema.json, model/services/control-plane/RunControlService.yaml, model/services/control-plane/ProjectService.yaml, model/services/control-plane/ControlPlaneApi.yaml, model/backlog/pbis/engineering-readiness/typed-gateway-clients.yaml |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-192 Projects command |
implementation | The command prints project key, name and my role for each project my membership grants, read from the list operation of ProjectService through the control plane gateway and the pinned control plane client; a refusal is explained and ends with the failure code of its class. | ConnectSoft.AI.SoftwareFactory.Cli |
AIFACTORY-TASK-151 Commands: submit, status, watch, approvals list, approve, reject |
implementation | Each command calls the modelled public REST operation through the one client port of the skeleton and prints the run or approval state; submit sends run-submission-v1 with an idempotency key generated once and reused on a retry; watch polls GetRun at a configurable interval until the run is Completed, Failed or Cancelled, prints each change of the run, its steps and its pending approvals and stops on 404 or 403; approve and reject send approval-decision-v1 with the version of the request, for a run-level spend approval without a step as for any other; a refused command explains the refusal by its class (401, 403, 404, 409, 410, 400, 503) and ends with the failure code of that class: 409 on a decision names the two modelled causes, 410 says that the approval request expired and that the run follows the expiry rule of its request and that the decision was not recorded, and 503 prints the retry hint. |
ConnectSoft.AI.SoftwareFactory.Cli |
AIFACTORY-TASK-2111 Pinned control plane client behind the client port in place of the hand-written adapter |
implementation | The client repository pins the published control plane client package of feature typed-gateway-clients in its user-token layout in the central package file and restores it from the ConnectSoft feed without a project reference; the package is registered behind the one client port of the skeleton with the base address of the control plane gateway and the token of the sign-in; the hand-written adapter of the skeleton is removed; the typed errors of the package are mapped to the failure codes of the refusal classes; an architecture test fails when a type of the repository other than the pinned client sends a request to the control plane gateway, or when a type other than the pinned client of its gateway sends a request to another gateway, which proves AC5 of AIFACTORY-US-376. |
ConnectSoft.AI.SoftwareFactory.Cli |
AIFACTORY-TASK-1544 Acceptance fixture of the commands on the real control plane gateway |
fixture | A fixture of the acceptance suite of the client repository that addresses the acceptance environment of feature local-development-environment, in which ControlPlaneApi fronts ProjectService and RunControlService and the authorization server of the Factory issues the tokens, in place of the contract stub the commands were first planned against: it uses the fixture tenant and project of the environment with a requester and a reviewer, submits the fixture run through the gateway, and lets a worker stand-in raise the approval requests of that run through the internal operation RunControl.RequestApproval, one with an expiry that has passed for the 410 and one that is decided twice for the 409; it holds an identifier of a second tenant for the 404 and a member without the deciding scope for the 403; the fixture creates, resets and removes no database and touches only the fixture tenant and project the environment page names. |
ConnectSoft.AI.SoftwareFactory.Cli |
AIFACTORY-TASK-1545 Verify every control plane command and every class of refusal against the real gateway |
verification | Run dotnet test -c Release --no-build on the client solution with the fixture of AIFACTORY-TASK-1544; the projects list, the idempotent submit with its conflict, status, watch by polling to a terminal run and its stop on 404, approvals list, approve and reject, the run-level spend approval without a step, and one refusal per class with its failure code, the expired approval with 410, both causes of 409 on a decision and the stopped fronted service with 503 among them, pass against the real control plane gateway through the pinned control plane client, and the architecture test over the single adapter passes, which proves AC1 to AC5 of AIFACTORY-US-376 (ADR-0014, ADR-0015). |
ConnectSoft.AI.SoftwareFactory.Cli |
AIFACTORY-US-1507: Command-line client: recipe show and recipe approve call GenerationRecipeService through the template catalog gateway with the pinned client of that gateway and a token of its audience¶
enabling · persona asset-maintainer
As an asset maintainer, I want to read a generation recipe with its pins and approve it from a terminal, so that the recipe act of the first outcome is driven from the same client as the other three acts.
The third act of the first outcome is the approval of a generation recipe. GenerationRecipeService is fronted by the gateway TemplateCatalogHost, which is delivered in I1 (decision D123), and the command-line client calls the gateway and reaches no service host directly. This PBI writes the two commands of that act into the skeleton of the client. recipe show calls GetRecipe, GET /factory/recipes/{recipeId}/versions/{version} under the scope factory.recipes.read, and prints the module plan with its template versions, switches, parameters and pins, the libraries, the compatibility evidence, the state, the approver and draftAllowanceUsed, so that the approver sees whether the recipe binds a version under the Draft allowance. recipe approve calls ApproveRecipe, POST /factory/recipes/{recipeId}/versions/{version}/approve under the scope factory.recipes.approve, by recipe identifier and version, and prints the approved state or the explanation of a refusal. The two commands go through the template catalog gateway client of feature typed-gateway-clients in its user-token layout, pinned at its published version from the ConnectSoft feed and registered behind the client port with the base address of the template catalog gateway; the repository holds no hand-written adapter for these operations and no address of the service. A user token has one audience, so the client requests a second token for the audience of the template catalog gateway with the scopes factory.recipes.read and factory.recipes.approve from the Factory entry of the client at the Authorization Server, and that client attaches it only to requests to the base address of that gateway; the token of the control plane gateway is never sent to it and this token never to the control plane gateway. A refused command explains the refusal from the problem response and ends with the failure code of its class, as the control plane commands do (AIFACTORY-US-376): 401 asks me to sign in again, 403 names the scope or the role I lack, 404 is the same answer for an unknown recipe and a recipe of another tenant, 409 says that the recipe is not Validated or its pins no longer resolve, with the pin named, and 503 prints the retry hint of the gateway or of a dependency that does not answer. The commands are proven in the acceptance suite of the client repository against a stub of the template catalog gateway built from its OpenAPI document; the run of a recipe through a generation is proven by the features of the chain.
Acceptance criteria
| AC1 | Given I am signed in with a token for the audience of the template catalog gateway, when I run recipe show for a recipe identifier and version, then the command calls GenerationRecipeService/GetRecipe through the pinned template catalog gateway client and prints the module plan with its template versions, switches, parameters and pins, the libraries, the compatibility evidence, the state, the approver and draftAllowanceUsed (model/services/template-library/GenerationRecipeService.yaml). |
| AC2 | Given a Validated recipe, when I run recipe approve for its identifier and version, then the command calls GenerationRecipeService/ApproveRecipe through the same client and prints the approved state and the approver; given a recipe that is not Validated, whose pins no longer resolve, of another tenant or a scope I lack, then the command prints the explanation of 409 with the reason, 404, or 403 and ends with the failure code of the class, and a 503 prints the retry hint (ADR-0027, model/services/template-library/GenerationRecipeService.yaml). |
| AC3 | Given the client repository, when its architecture test and the token test run, then the template catalog gateway client is the only adapter to that gateway, the token of its audience is attached only to requests to the base address of the template catalog gateway, the token of the control plane gateway never reaches it, and no token is written to a file, the output or the log of the client (ADR-0015 amendment on the one audience of a user token, model/backlog/pbis/engineering-readiness/typed-gateway-clients.yaml). |
| Traces: apis | GenerationRecipeService/GetRecipe, GenerationRecipeService/ApproveRecipe |
| Traces: adrs | ADR-0015, ADR-0027, ADR-0028 |
| Depends on | feature:command-line-client, feature:typed-gateway-clients, feature:generation-recipe-service, feature:template-catalog-host |
| Sources | model/services/template-library/GenerationRecipeService.yaml, model/services/template-library/TemplateCatalogHost.yaml, model/backlog/pbis/engineering-readiness/typed-gateway-clients.yaml |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-217 CLI commands recipe show and recipe approve |
implementation | The client has the commands recipe show and recipe approve: show prints the module plan with its template versions, switches and pins from GetRecipe, and approve sends ApproveRecipe by recipe identifier and version and prints the approved state or the explanation of a 403, 404, 409 or 503. Both commands go through the gateway TemplateCatalogHost, which is delivered in I1 and fronts GenerationRecipeService (D123): the client pins the typed client of that gateway that feature typed-gateway-clients publishes, in its user-token layout, restores it from the ConnectSoft feed, registers it with the base address of the gateway and attaches a user token requested for the audience of that gateway and no other, because a user token has one audience; the client holds no hand-written adapter for these operations and no address of the service. | ConnectSoft.AI.SoftwareFactory.Cli |
AIFACTORY-TASK-6133 Verify the recipe commands against a stub of the template catalog gateway |
verification | Run dotnet test -c Release --no-build on the client solution with a stub of the template catalog gateway built from its OpenAPI document; recipe show and recipe approve with their printed states, one refusal per class with its failure code, the token of the template catalog audience attached only to that gateway and the architecture test over the single adapter of that gateway pass, which proves AC1 to AC3 of AIFACTORY-US-1507 and AC4 of AIFACTORY-US-013. |
ConnectSoft.AI.SoftwareFactory.Cli |
AIFACTORY-US-528: Command-line client commands: the pipeline of the client repository and one recorded walk prove the commands against the real control plane gateway, from the sign-in to a decided approval¶
evidence · persona requester
As a requester, I want proof that the commands of the command-line client drive a run and its approvals through the real control plane gateway, so that the first outcome can be demonstrated from a terminal and not only from a test double.
This is the integration PBI and the proof of the feature. Increment I0 proved the sign-in of the command-line client (AIFACTORY-US-377 and AIFACTORY-US-003 of feature command-line-client); this PBI proves the commands that AIFACTORY-US-376 writes into the skeleton, against the real services. Two proofs are kept. The first is the pipeline of the repository ConnectSoft.AI.SoftwareFactory.Cli: its acceptance stage, which in increment I0 ran the sign-in only, now also runs the built client as a process against the acceptance environment of feature local-development-environment, with ControlPlaneApi in front of ProjectService and RunControlService and with the authorization server of the Factory instance of the Identity Platform. It signs in as the requester, lists projects, submits a run twice with one idempotency key, reads its status and watches it; it signs in as the reviewer, lists approvals, approves one and rejects one; and it provokes one refusal of each class, the 410 of an expired approval request and the 503 of a stopped fronted service among them. Every call leaves the client through the pinned control plane client of feature typed-gateway-clients, with the user token of the signed-in member, which the gateway forwards to the service it fronts. The scan of the files, the output and the log of the client process for a token, a renewal credential and a secret stays part of the stage and must find none. The second proof is a recorded walk by a person in the same environment, from the sign-in to a decided approval, with the printed state of every step, the revision of the client, the version of the pinned control plane client and the trace identifier of the submission. The record names no person and carries no date. A failed run or a failed walk is recorded as failed with the step that failed, and the feature is not accepted on it. The run of a vision through the six workflows to an approved change proposal is the demonstration of increment I1 and belongs to the feature that verifies that increment; this PBI ends where the commands are proven.
Acceptance criteria
| AC1 | Given the acceptance environment with ControlPlaneApi, ProjectService, RunControlService and the authorization server of the Factory, when the acceptance stage of the client pipeline runs the built client as a process, then the sign-in, projects, submit twice with one idempotency key, status, watch, approvals list, approve and reject each print the state the real service returned for RunControlService/SubmitRun, RunControlService/GetRun, RunControlService/ListApprovals, RunControlService/DecideApproval and ProjectService/ListProjects, and one refusal of each class ends with the failure code of its class (ADR-0028 decision 2; model/services/control-plane/RunControlService.yaml). |
| AC2 | Given a person in that environment, when they walk from the sign-in as a requester through projects, submit, status and watch and, signed in as a reviewer, through approvals list and approve, then the walk is recorded with the printed state of every step, the revision of the client, the version of the pinned control plane client and the trace identifier of the submission, and the reviewer is another member than the requester, because docs/reference/schemas/approval.schema.json makes the requester of a run never eligible to decide (ADR-0015 decision 6). |
| AC3 | Given the files, the output and the log that the client process wrote during the acceptance stage with the commands, when they are scanned, then no token, no renewal credential and no secret is found, and the stage fails on a planted token file as it did for the sign-in alone (ADR-0015 decision 2). |
| Traces: apis | ProjectService/ListProjects, RunControlService/SubmitRun, RunControlService/GetRun, RunControlService/ListApprovals, RunControlService/DecideApproval |
| Traces: adrs | ADR-0015, ADR-0028 |
| Depends on | AIFACTORY-US-376, feature:command-line-client, feature:control-plane-api, feature:typed-gateway-clients, feature:project-service, feature:run-control-service, feature:local-development-environment |
| Sources | docs/architecture/capability-dependencies.md, docs/architecture/adr/0015-factory-tenancy-under-canonical-adr-0100.md, docs/architecture/adr/0028-one-repository-and-deployable-per-service.md, docs/reference/schemas/approval.schema.json, model/services/control-plane/RunControlService.yaml, model/backlog/increments.yaml |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-2112 Acceptance stage of the client pipeline runs the commands against the acceptance environment |
operations | The acceptance stage of the pipeline of the client repository, which holds the sign-in harness of AIFACTORY-TASK-1547, also runs the built client as a process against the acceptance environment with the fixture of AIFACTORY-TASK-1544: the sign-in as requester and as reviewer, projects, submit twice with one idempotency key, status, watch, approvals list, approve, reject and one refusal per class; the scan for a token, a renewal credential and a secret covers the files, the output and the log of these runs; the stage holds no build or test script of its own and creates, resets and removes no database. | ConnectSoft.AI.SoftwareFactory.Cli |
AIFACTORY-TASK-2113 Recorded walk from the sign-in to a decided approval against the real gateway |
verification | A record of one walk by a person in the acceptance environment: the sign-in as a requester, projects, submit, status and watch, then the sign-in as a reviewer, approvals list and approve, each step with the printed state, the revision of the client, the version of the pinned control plane client and the trace identifier of the submission, which proves AC2 of AIFACTORY-US-528; the record names no person. | ConnectSoft.AI.SoftwareFactory.Cli |
AIFACTORY-TASK-2114 Verify the commands by one green pipeline run and one planted failing scan |
verification | One run of the pipeline of the client repository is green with the commands of the acceptance stage against the real control plane gateway; one run with a planted token file fails at the scan; both prove AC1 and AC3 of AIFACTORY-US-528 (ADR-0015, ADR-0028). | ConnectSoft.AI.SoftwareFactory.Cli |