AIFACTORY-FEAT-093: Command-line client for the first outcome¶
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 I0 Readiness · State elaborated · Route backend-developer · Build order 48 of 185 (Factory code)
The first outcome is used through the control plane API and a small command-line client: submit a vision, follow a run, approve a recipe and approve a change proposal. Studio follows in a later increment. I0 delivers the repository, the skeleton and the sign-in (authorization code with PKCE by default, device code as a switch); the commands are the I1 feature command-line-client-commands (owner decision D117).
| Delivers | — |
| Stubs | — |
| Realizes | — |
| Requirements | — |
| Depends on | — |
| Sources | docs/architecture/capability-dependencies.md, docs/ai-software-factory/current-state.md |
AIFACTORY-US-375: Command-line client: a person signs in by authorization code with PKCE or by device code, the client holds a short-lived token for the control plane gateway and keeps no long-lived secret on disk¶
enabling · persona requester
As a requester, I want to sign in from the command-line client without a secret ending up in a file, so that I can use the Factory before the Studio exists and my credentials stay where the operating system protects them.
ADR-0029 decision 2 has the first outcome used through the API and a command-line client, and the Studio follows in a later increment. Owner decision D117 splits that client over two increments: increment I0 delivers the repository, the skeleton and the sign-in, and the commands of the first outcome are the feature command-line-client-commands of increment I1. This PBI delivers the I0 part in the repository ConnectSoft.AI.SoftwareFactory.Cli. The client is a console application built by the shared pipeline templates. The model names no template for a console client, so the repository is created without one, under the name, pipeline and feed rules of the checklist of feature repository-and-pipeline-conventions. The skeleton is what the commands are written into later: the command host, the configuration, the rule that a refused call ends with a failure code and never silently, and one client port through which a command will reach the control plane gateway. In this increment the port has a hand-written adapter that does one thing, attach the token of the signed-in person to a request to the configured base address of the gateway; the pinned control plane client of feature typed-gateway-clients takes its place in increment I1. No command of the first outcome is part of the skeleton. The client is a public client of the authorization server of the Identity Platform: it holds no client secret, and a person signs in interactively. The amendment of ADR-0015 on the client sign-in (decision D117) decides the two flows. By default the client signs in with the authorization code flow with PKCE: it opens the browser of the machine on the authorization request, receives the code on a loopback redirect address of that machine and redeems it with the code verifier. A switch of the sign-in command selects the device code flow for a machine without a browser: the client prints the verification address and the user code and polls the token endpoint at the interval the authorization server gives, until the person has confirmed the code on another device, the code is denied or it expires. Both flows end in the same token and the same custody. The client side of the sign-in is this PBI: the authority, the client identifier, the requested audience and the requested scopes are read from configuration. The registration of the public client with both flows, its scopes and its redirect address is registration data of the authorization server and no output of the client repository; AIFACTORY-US-526 of feature component-auth-server-template-factory-tokens delivers it. The token the client asks for is a user token, and a user token has one audience, the gateway that fronts its scopes (ADR-0015 amendment on the audience, decision D114). The client therefore requests one token per gateway audience it calls, each audience with its scopes read from configuration, and never reuses the token of one gateway for another. The commands of the control plane call the control plane gateway, so the client requests a token for that gateway with the scopes those commands need as the service files of the model name them, factory.projects.read, factory.runs.write, factory.runs.read, factory.approvals.read and factory.approvals.decide; this increment configures that one audience. The recipe act of the first outcome calls the template catalog gateway, which fronts GenerationRecipeService (decision D123), so its commands request a second token for the audience of that gateway with factory.recipes.read and factory.recipes.approve; that audience is configured with those commands in I1 (AIFACTORY-US-1507 of feature command-line-client-commands). Each gateway forwards the user token to the service it fronts and that service accepts the audience of its gateway, so one token serves every command of its gateway and the client never asks for a token per service (ADR-0015 amendment on the forwarded user token). The token carries the tenant and one role claim per project assignment, issued by the authorization server as feature component-auth-server-template-factory-tokens delivers them; the client reads them only to show who is signed in and decides nothing from them, because every backend enforces them per request (ADR-0015 decision 6). The access token is short-lived. The token and what is needed to renew it are kept in the credential store of the operating system and in no file, so no long-lived secret is on disk. When the token has expired, the client renews it without a prompt while the authorization server allows it; when it cannot, the call stops, tells the person to sign in again and ends with a failure code. It never fails silently, never retries with an expired token and never prints a token, at any verbosity. A sign-out removes the entries from the credential store. The claim type names the client reads are those of the pinned ConnectSoft.Extensions.AI.Factory.Abstractions; the client defines none.
Acceptance criteria
| AC1 | Given valid credentials on a machine with a browser, when I sign in without a switch, then the client signs in as a public client by the authorization code flow with PKCE, sends no client secret, and holds a short-lived user token whose one audience is the control plane gateway and whose requested scopes are factory.projects.read, factory.runs.write, factory.runs.read, factory.approvals.read and factory.approvals.decide, the token and what renews it are kept in the credential store of the operating system, and no token, renewal credential or client secret is written to a file (ADR-0015 amendments on the client sign-in and on the one audience of a user token; ADR-0028 decision 2 makes the gateway the route to the services; model/services/control-plane/RunControlService.yaml and model/services/control-plane/ProjectService.yaml name the scopes). |
| AC2 | Given a machine without a browser, when I sign in with the device code switch, then the client prints the verification address and the user code, polls the token endpoint at the interval the authorization server gives, and after I confirmed the code on another device holds the same token under the same custody as after the default flow; a code that is denied or that expires ends the sign-in with a failure code and nothing is stored (ADR-0015 amendment on the client sign-in; docs/architecture/adr/0015-factory-tenancy-under-canonical-adr-0100.md). |
| AC3 | Given my token expired, when a call through the client port of the skeleton needs a token, then the client renews the token without a prompt while the authorization server allows it, and otherwise stops, asks me to sign in again and ends with a failure code; it does not fail silently and does not send the expired token a second time (ADR-0015 decision 6). |
| AC4 | Given I am signed in, when I sign out, then the entries are removed from the credential store and the next call asks me to sign in; and at any verbosity no output line and no log line holds a token value (ADR-0015 decision 2; docs/architecture/adr/0015-factory-tenancy-under-canonical-adr-0100.md). |
| Traces: adrs | ADR-0015, ADR-0028 |
| Depends on | feature:component-auth-server-template-factory-tokens, feature:component-extensions-ai, feature:repository-and-pipeline-conventions |
| Sources | docs/architecture/capability-dependencies.md, docs/ai-software-factory/current-state.md, docs/architecture/adr/0015-factory-tenancy-under-canonical-adr-0100.md, docs/architecture/adr/0029-build-backlog-as-a-model-kind.md, model/services/control-plane/RunControlService.yaml, model/services/control-plane/ProjectService.yaml |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-150 Scaffold the client and authenticate against the Identity Platform |
implementation | The repository ConnectSoft.AI.SoftwareFactory.Cli is created without a template, because the model names none for a console client, under the name, pipeline and feed rules of the checklist of feature repository-and-pipeline-conventions and after the approval of the owner; it holds a console application that builds and tests from the shared pipeline templates and the skeleton of the client: the command host, the configuration, the failure code of a refused call and the one client port to the control plane gateway with a hand-written adapter that attaches the token to a request to the configured base address; it holds no command of the first outcome; it reads the authority, its client identifier, the requested audience of the control plane gateway and the requested scopes (factory.projects.read, factory.runs.write, factory.runs.read, factory.approvals.read, factory.approvals.decide) from configuration; it signs a person in for that audience and stores no long-lived secret; the registration of the public client in the authorization server is no output of this repository. |
ConnectSoft.AI.SoftwareFactory.Cli |
AIFACTORY-TASK-191 Sign-in against the Identity Platform |
implementation | Interactive sign-in as a public client, by the authorization code flow with PKCE by default and by the device code flow behind a switch of the sign-in command, with token renewal, a command that shows who is signed in and a sign-out; the token and what renews it are kept in the credential store of the operating system and in no file; a denied or expired device code stores nothing; an expired token that cannot be renewed stops the call with a request to sign in again and a failure code. | ConnectSoft.AI.SoftwareFactory.Cli |
AIFACTORY-TASK-1543 Verify the sign-in, the renewal and the custody of the token |
verification | Run dotnet test -c Release --no-build on the client solution against a local authorization server; the sign-in by authorization code with PKCE, the sign-in by device code with a confirmed, a denied and an expired code, the audience of the control plane gateway, the silent renewal, the expired token that cannot be renewed, the sign-out and the search of output and log for a token value pass and prove AC1 to AC4 of AIFACTORY-US-375 (ADR-0015). |
ConnectSoft.AI.SoftwareFactory.Cli |
AIFACTORY-US-377: Command-line client: the pipeline of the client repository proves the sign-in by both flows, the renewal, the sign-out and the custody of the token against a local authorization server¶
evidence · persona requester
As a requester, I want proof from a pipeline run that the client signs in by both flows and leaves no secret behind, so that the commands of the first outcome are built on a sign-in that is already proven.
This PBI is the proof of the feature. The pipeline of the repository ConnectSoft.AI.SoftwareFactory.Cli is built from the shared pipeline templates, as the conventions of feature repository-and-pipeline-conventions require, and its acceptance stage runs the built client as a process, the way a person runs it. The stage starts a local authorization server, generated from connectsoft-authorization-server at the version the gate of feature component-auth-server-template-factory-tokens published into a working folder of the pipeline that is not committed. Its registration data hold the public client of the command-line client with the authorization code flow with PKCE and the device code flow, as AIFACTORY-US-526 of that feature delivers the registration, together with a tenant, a project and a member. The harness plays the part of the person and of the browser. For the default flow it follows the authorization request the client opens, signs the member in and lets the redirect reach the loopback address of the client. For the device code switch it reads the verification address and the user code the client printed and confirms the code as the member; in a second run it denies the code. After each sign-in it runs the command that shows who is signed in, lets the access token expire and proves the renewal without a prompt, then signs out. After the run a scan of every file the client process wrote, and of its output and log, searches for a token, a renewal credential and a secret: it must find none, because the only place a token may rest is the credential store of the operating system. The pipeline publishes the built client as its build artifact with the version of the build. The model does not state how the client is distributed to its users, so this PBI proves the build and the behaviour and claims no package on a feed. No command of the first outcome is run here: the commands and their run against the real control plane gateway are the feature command-line-client-commands of increment I1 (owner decision D117).
Acceptance criteria
| AC1 | Given the pipeline of the client repository, when it runs, then build and tests come from the shared pipeline templates with complete test reports, the acceptance stage runs the built client as a process, and the built client is published as the build artifact of the run (ADR-0028; docs/architecture/adr/0028-one-repository-and-deployable-per-service.md). |
| AC2 | Given the acceptance stage with a local authorization server whose registration data hold the public client of the command-line client, when the built client signs in once by the authorization code flow with PKCE and once with the device code switch, then each token it obtained has the control plane gateway as its one audience and the scopes that model/services/control-plane/RunControlService.yaml names for the commands, the command that shows who is signed in prints the tenant and the roles of the member, an expired access token is renewed without a prompt, and a sign-in whose device code was denied ends with a failure code (ADR-0015 amendments on the client sign-in and on the one audience of a user token). |
| AC3 | Given the files, the output and the log that the client process wrote during the acceptance stage, when they are scanned, then no token, no renewal credential and no secret is found, and a planted run that writes a token to a file fails the scan (ADR-0015 decision 2). |
| Traces: adrs | ADR-0015, ADR-0028 |
| Depends on | AIFACTORY-US-375, feature:repository-and-pipeline-conventions, feature:component-auth-server-template-factory-tokens |
| 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, model/services/control-plane/RunControlService.yaml |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-1546 Pipeline of the client repository from the shared pipeline templates |
operations | The pipeline file of the client repository calls the shared build and test steps of ConnectSoft.AzurePipelines, runs the acceptance stage against the built client and publishes the built client as the build artifact; it holds no build or test script of its own and restores from the ConnectSoft feed only. | ConnectSoft.AI.SoftwareFactory.Cli |
AIFACTORY-TASK-1547 Acceptance harness with a local authorization server, both sign-in flows and a secret scan |
fixture | A harness in the client repository that generates a local authorization server from connectsoft-authorization-server at the version the gate of feature component-auth-server-template-factory-tokens published, into a working folder of the pipeline that is not committed, with the public client of the command-line client in its registration data (AIFACTORY-US-526) and with a tenant, a project and a member; it runs the built client as a process through the sign-in by authorization code with PKCE, where the harness follows the authorization request to the loopback redirect, and through the sign-in with the device code switch, where the harness confirms the user code in one run and denies it in another, then through the command that shows who is signed in, a renewal after expiry and the sign-out, and scans the files, the output and the log of the process for a token, a renewal credential and a secret; a planted token file proves that the scan fails; the store of the local server is a throwaway database of the pipeline container and no named or shared database is touched. |
ConnectSoft.AI.SoftwareFactory.Cli |
AIFACTORY-TASK-1548 Verify the client by one green pipeline run and one planted failing scan |
verification | One run of the pipeline is green with the acceptance stage and the published build artifact; one run with the planted token file fails at the scan; both prove AC1 to AC3 of AIFACTORY-US-377 (ADR-0015, ADR-0028). | ConnectSoft.AI.SoftwareFactory.Cli |
AIFACTORY-US-003: Sign in from the command line and hold a token for the control plane gateway¶
enabling · persona requester
As a requester, I want to sign in from the command-line client and see who I am signed in as, so that I can use the Factory before the Studio exists.
This is the integration PBI of the feature. Increment I0 delivers the repository of the command-line client, its skeleton and its sign-in; the commands of the first outcome, submit a vision, follow the run, approve a recipe and approve a change proposal, are the feature command-line-client-commands of increment I1 (owner decision D117) and are promised by nothing here. A requester signs in from the command-line client and sees who is signed in: the tenant and the role per project that the token carries. AIFACTORY-US-375 delivers the repository, the skeleton and the sign-in as a public client, by the authorization code flow with PKCE by default and by the device code flow behind a switch, with a short-lived user token for the one audience of the control plane gateway and with no long-lived secret on disk. AIFACTORY-US-377 proves it in the pipeline of the client repository against a local authorization server. This PBI proves it in the local environment of feature local-development-environment, against the authorization server of the Factory instance of the Identity Platform that the environment runs: one walk by a person through both sign-in flows, the command that shows who is signed in, a renewal and the sign-out. The thin scope of this increment is stated exactly: the client, its skeleton and its sign-in exist and are proven; the commands and the services that answer them arrive in increment I1, where they run against the real gateway through the pinned control plane client. The client decides nothing about access: the roles in the token are enforced by every backend, and a project the token does not grant is refused by the gateway, not hidden by the client.
Acceptance criteria
| AC1 | Given valid credentials, when I sign in by the authorization code flow with PKCE or with the device code switch, then the client holds a short-lived token and no long-lived secret on disk (ADR-0015 amendments on the client sign-in and on the one audience of a user token). |
| AC2 | Given I am signed in, when I ask who is signed in, then the client shows the tenant and my role per project as the token carries them and decides nothing from them, because every backend enforces them per request (ADR-0015 decisions 5 and 6). |
| AC3 | Given my token expired, when a call needs a token, then the client renews it while the authorization server allows it and otherwise asks me to sign in again and does not fail silently (ADR-0015 decision 6). |
| AC4 | Given the local environment with the authorization server of the Factory instance of the Identity Platform, when a person walks through the sign-in by authorization code with PKCE, the command that shows who is signed in, the sign-out and the sign-in with the device code switch, then every step prints the state it reached and the walk is recorded; the commands of the first outcome are left to the feature command-line-client-commands of increment I1 (ADR-0015; model/backlog/increments.yaml). |
| Traces: adrs | ADR-0015 |
| Depends on | AIFACTORY-US-375, AIFACTORY-US-377, feature:local-development-environment |
| Sources | docs/architecture/capability-dependencies.md, docs/ai-software-factory/current-state.md, model/backlog/increments.yaml |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-1549 Recorded walk through both sign-in flows in the local environment |
verification | A record of one walk by a person in the local environment against the authorization server of the Factory instance of the Identity Platform: the sign-in by authorization code with PKCE, the command that shows who is signed in, the sign-out and the sign-in with the device code switch, each step with the printed state, which proves AC4 of AIFACTORY-US-003 and names the revision of the client that was used. | ConnectSoft.AI.SoftwareFactory.Cli |
AIFACTORY-TASK-712 Verify cli-sign-in by running the declared command |
verification | Run dotnet build -c Release and dotnet test -c Release --no-build; they pass and prove AC1 to AC3 of AIFACTORY-US-003. |
ConnectSoft.AI.SoftwareFactory.Cli |