diff --git a/CHANGELOG.md b/CHANGELOG.md index 4773b150..de7ba9b9 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -15,6 +15,7 @@ All notable changes to this project will be documented in this file. ### Added - Official marketplace bundle extraction (OpenSpec change `module-migration-02-bundle-extraction`, issue [#316](https://github.com/nold-ai/specfact-cli/issues/316)): five bundle packages (`specfact-project`, `specfact-backlog`, `specfact-codebase`, `specfact-spec`, `specfact-govern`) are now produced in the dedicated `nold-ai/specfact-cli-modules` repository. +- Backlog bundle auth command group (OpenSpec change `backlog-auth-01-backlog-auth-commands`, issue [#340](https://github.com/nold-ai/specfact-cli/issues/340)): `specfact backlog auth` now provides `azure-devops`, `github`, `status`, and `clear` using core `specfact_cli.utils.auth_tokens` storage. - Official-tier trust model in module validation and display: `official` tier verification path with `nold-ai` publisher allowlist and `[official]` module list badge. - Bundle dependency auto-install in module installer: installing `nold-ai/specfact-spec` or `nold-ai/specfact-govern` now auto-installs `nold-ai/specfact-project` when missing. - Bundle publishing mode in `scripts/publish-module.py` (`--bundle` and `--modules-repo-dir`) for packaging/signing/index updates against the dedicated modules repository. diff --git a/docs/reference/authentication.md b/docs/reference/authentication.md index ecb83d3a..7d12546c 100644 --- a/docs/reference/authentication.md +++ b/docs/reference/authentication.md @@ -7,20 +7,21 @@ permalink: /reference/authentication/ # Authentication SpecFact CLI supports device code authentication flows for GitHub and Azure DevOps to keep credentials out of scripts and CI logs. +When the backlog bundle is installed, authentication commands are available under `specfact backlog auth`. ## Quick Start ### GitHub (Device Code) ```bash -specfact auth github +specfact backlog auth github ``` Use a custom OAuth client or GitHub Enterprise host: ```bash -specfact auth github --client-id YOUR_CLIENT_ID -specfact auth github --base-url https://github.example.com +specfact backlog auth github --client-id YOUR_CLIENT_ID +specfact backlog auth github --base-url https://github.example.com ``` **Note:** The default client ID ships with the CLI and is only valid for `https://github.com`. For GitHub Enterprise, you must supply your own client ID via `--client-id` or `SPECFACT_GITHUB_CLIENT_ID`. @@ -28,14 +29,14 @@ specfact auth github --base-url https://github.example.com ### Azure DevOps (Device Code) ```bash -specfact auth azure-devops +specfact backlog auth azure-devops ``` **Note:** OAuth tokens expire after approximately 1 hour. For longer-lived authentication, use a Personal Access Token (PAT) with up to 1 year expiration: ```bash # Store PAT token (recommended for automation) -specfact auth azure-devops --pat your_pat_token +specfact backlog auth azure-devops --pat your_pat_token ``` ### Azure DevOps Token Resolution Priority @@ -44,7 +45,7 @@ When using Azure DevOps commands (e.g., `specfact backlog refine ado`, `specfact 1. **Explicit token parameter**: `--ado-token` CLI flag 2. **Environment variable**: `AZURE_DEVOPS_TOKEN` -3. **Stored token**: Token stored via `specfact auth azure-devops` (checked automatically) +3. **Stored token**: Token stored via `specfact backlog auth azure-devops` (checked automatically) 4. **Expired stored token**: If stored token is expired, a warning is shown with options to refresh **Example:** @@ -69,17 +70,17 @@ specfact backlog refine ado --ado-org myorg --ado-project myproject ## Check Status ```bash -specfact auth status +specfact backlog auth status ``` ## Clear Stored Tokens ```bash # Clear one provider -specfact auth clear --provider github +specfact backlog auth clear --provider github # Clear all providers -specfact auth clear +specfact backlog auth clear ``` ## Token Storage @@ -98,7 +99,7 @@ Adapters resolve tokens in this order: - Explicit token parameter (CLI flag or code) - Environment variable (e.g., `GITHUB_TOKEN`, `AZURE_DEVOPS_TOKEN`) -- Stored auth token (`specfact auth ...`) +- Stored auth token (`specfact backlog auth ...`) - GitHub CLI (`gh auth token`) for GitHub if enabled **Azure DevOps Specific:** @@ -109,20 +110,20 @@ For Azure DevOps commands, stored tokens are automatically used by: If a stored token is expired, you'll see a warning with options to: 1. Use a PAT token (recommended for longer expiration) -2. Re-authenticate via `specfact auth azure-devops` +2. Re-authenticate via `specfact backlog auth azure-devops` 3. Use `--ado-token` option with a valid token ## Troubleshooting ### Token Resolution Issues -**Problem**: "Azure DevOps token required" error even after running `specfact auth azure-devops` +**Problem**: "Azure DevOps token required" error even after running `specfact backlog auth azure-devops` **Solutions:** 1. **Check token expiration**: OAuth tokens expire after ~1 hour. Use a PAT token for longer expiration: ```bash - specfact auth azure-devops --pat your_pat_token + specfact backlog auth azure-devops --pat your_pat_token ``` 2. **Use explicit token**: Override with `--ado-token` flag: @@ -138,8 +139,8 @@ If a stored token is expired, you'll see a warning with options to: 4. **Re-authenticate**: Clear and re-authenticate: ```bash - specfact auth clear --provider azure-devops - specfact auth azure-devops + specfact backlog auth clear --provider azure-devops + specfact backlog auth azure-devops ``` For full adapter configuration details, see: diff --git a/openspec/changes/backlog-auth-01-backlog-auth-commands/tasks.md b/openspec/changes/backlog-auth-01-backlog-auth-commands/tasks.md index 3d60a89f..cc571dcf 100644 --- a/openspec/changes/backlog-auth-01-backlog-auth-commands/tasks.md +++ b/openspec/changes/backlog-auth-01-backlog-auth-commands/tasks.md @@ -8,31 +8,31 @@ ## 1. Branch and repo setup -- [ ] 1.1 In specfact-cli-modules (or the repo that hosts the backlog bundle), create a feature branch from the branch that has the post–migration-03 backlog bundle layout. -- [ ] 1.2 Ensure the backlog bundle depends on specfact-cli (so it can import `specfact_cli.utils.auth_tokens`). +- [x] 1.1 In specfact-cli-modules (or the repo that hosts the backlog bundle), create a feature branch from the branch that has the post–migration-03 backlog bundle layout. +- [x] 1.2 Ensure the backlog bundle depends on specfact-cli (so it can import `specfact_cli.utils.auth_tokens`). ## 2. Add backlog auth command group -- [ ] 2.1 In the backlog bundle's Typer app, add a subgroup: `auth_app = typer.Typer()` and register it as `backlog_app.add_typer(auth_app, name="auth")`. -- [ ] 2.2 Implement `specfact backlog auth azure-devops`: same behaviour as the former `specfact auth azure-devops` (PAT store, device code, interactive browser). Use `specfact_cli.utils.auth_tokens` for set_token/get_token. -- [ ] 2.3 Implement `specfact backlog auth github`: device code flow; use auth_tokens for storage. -- [ ] 2.4 Implement `specfact backlog auth status`: list stored providers (e.g. github, azure-devops) and show presence/expiry from get_token. -- [ ] 2.5 Implement `specfact backlog auth clear`: clear_token(provider) or clear_all_tokens(); support `--provider` to clear one. -- [ ] 2.6 Add `@beartype` and `@icontract` where appropriate on public entrypoints. -- [ ] 2.7 Re-use or adapt existing adapters (GitHub, Azure DevOps) in the bundle so they continue to call `get_token("github")` / `get_token("azure-devops")` from specfact_cli.utils.auth_tokens. +- [x] 2.1 In the backlog bundle's Typer app, add a subgroup: `auth_app = typer.Typer()` and register it as `backlog_app.add_typer(auth_app, name="auth")`. +- [x] 2.2 Implement `specfact backlog auth azure-devops`: same behaviour as the former `specfact auth azure-devops` (PAT store, device code, interactive browser). Use `specfact_cli.utils.auth_tokens` for set_token/get_token. +- [x] 2.3 Implement `specfact backlog auth github`: device code flow; use auth_tokens for storage. +- [x] 2.4 Implement `specfact backlog auth status`: list stored providers (e.g. github, azure-devops) and show presence/expiry from get_token. +- [x] 2.5 Implement `specfact backlog auth clear`: clear_token(provider) or clear_all_tokens(); support `--provider` to clear one. +- [x] 2.6 Add `@beartype` and `@icontract` where appropriate on public entrypoints. +- [x] 2.7 Re-use or adapt existing adapters (GitHub, Azure DevOps) in the bundle so they continue to call `get_token("github")` / `get_token("azure-devops")` from specfact_cli.utils.auth_tokens. ## 3. Tests -- [ ] 3.1 Unit tests: auth commands call auth_tokens (mock auth_tokens); assert set_token/get_token/clear_token invoked with correct provider ids. -- [ ] 3.2 Integration test: with real specfact-cli and backlog bundle installed, `specfact backlog auth status` shows empty or existing tokens; `specfact backlog auth azure-devops --pat test-token` then status shows azure-devops. +- [x] 3.1 Unit tests: auth commands call auth_tokens (mock auth_tokens); assert set_token/get_token/clear_token invoked with correct provider ids. +- [x] 3.2 Integration test: with real specfact-cli and backlog bundle installed, `specfact backlog auth status` shows empty or existing tokens; `specfact backlog auth azure-devops --pat test-token` then status shows azure-devops. ## 4. Documentation and release -- [ ] 4.1 Update specfact-cli `docs/reference/authentication.md` (or equivalent) to document `specfact backlog auth` as the canonical auth commands when the backlog bundle is installed. Remove or redirect references to `specfact auth`. -- [ ] 4.2 Changelog (specfact-cli-modules or specfact-cli): Added — auth commands under `specfact backlog auth` (azure-devops, github, status, clear) in the backlog bundle. -- [ ] 4.3 Bump backlog bundle version and re-sign manifest if required by project policy. +- [x] 4.1 Update specfact-cli `docs/reference/authentication.md` (or equivalent) to document `specfact backlog auth` as the canonical auth commands when the backlog bundle is installed. Remove or redirect references to `specfact auth`. +- [x] 4.2 Changelog (specfact-cli-modules or specfact-cli): Added — auth commands under `specfact backlog auth` (azure-devops, github, status, clear) in the backlog bundle. +- [x] 4.3 Bump backlog bundle version and re-sign manifest if required by project policy. (Version bumped to `0.40.12`; re-sign requires maintainer key during release/publish step.) ## 5. PR and merge -- [ ] 5.1 Open PR to the appropriate branch (e.g. dev) in specfact-cli-modules. -- [ ] 5.2 After merge, ensure marketplace/registry entry for specfact-backlog is updated so new installs get the auth commands. +- [ ] 5.1 Open PR to the appropriate branch (e.g. dev) in specfact-cli-modules. (Blocked in this session: network DNS resolution to GitHub is unavailable.) +- [ ] 5.2 After merge, ensure marketplace/registry entry for specfact-backlog is updated so new installs get the auth commands. (Pending 5.1 merge.)