# Spec and build

## Configuration
- **Artifacts Path**: {@artifacts_path} → `.zenflow/tasks/{task_id}`

---

## Agent Instructions

Ask the user questions when anything is unclear or needs their input. This includes:
- Ambiguous or incomplete requirements
- Technical decisions that affect architecture or user experience
- Trade-offs that require business context

Do not make assumptions on important decisions — get clarification first.

---

## Workflow Steps

### [x] Step: Technical Specification
<!-- chat-id: b83b95ac-261e-4b28-a045-c33d3a34c73d -->

**Status**: Complete  
**Complexity**: Medium  
**Spec Location**: `.zenflow/tasks/add-web-based-authentication-to-074c/spec.md`

---

### [x] Step: Implement ENV Variable Token Support in auth.js
<!-- chat-id: 31bef641-87dc-4af1-805a-15810f520f43 -->

Modify `src/lib/auth.js` to support reading tokens from environment variables with proper precedence.

**Changes**:
- Add `getTokenFromEnv()` function to check `BILD_FIREBASE_TOKEN` and `FIREBASE_TOKEN`
- Add `validateToken()` function for basic JWT format validation
- Modify `getToken()` to check ENV vars before keychain
- Add `getTokenSource()` to identify where token came from
- Add `displayToken()` function to show current token

**Verification**:
- Test ENV var precedence over keychain
- Test token validation with valid/invalid tokens
- Test fallback to keychain when no ENV var set
- Run `npm run lint` on modified file

---

### [x] Step: Create Token Management Command
<!-- chat-id: 48d4dbe0-21d9-48dd-a29a-65dce78e66ab -->

Create new `src/commands/token.js` command for displaying and managing authentication tokens.

**Changes**:
- Create `src/commands/token.js` with command handler
- Support `--export` flag for shell-specific export syntax
- Support `--validate` flag to check token validity
- Support `--source` flag to show token source
- Auto-detect shell type (bash/zsh/fish/powershell) for export syntax

**Verification**:
- Test `bild token` displays current token
- Test `bild token --export` shows correct shell syntax
- Test `bild token --validate` validates correctly
- Test `bild token --source` shows correct source
- Run `npm run lint` on new file

---

### [x] Step: Update Login Command with ENV Support
<!-- chat-id: f1cc4ad9-a812-4664-b004-3033c0f29927 -->

Modify `src/commands/login.js` to support `--env` flag for displaying tokens after authentication.

**Changes**:
- Add `--env` option to login command
- Display token and export instructions when `--env` flag used
- Show shell-specific export commands
- Maintain existing keychain storage behavior

**Verification**:
- Test `bild login <url> --env` displays token
- Test token is still saved to keychain
- Test export command syntax is correct
- Run `npm run lint` on modified file

---

### [x] Step: Register Token Command and Update CLI
<!-- chat-id: 7208cb10-06e9-44b6-9469-90a7793b0469 -->

Modify `src/index.js` to register the new token command and update help text.

**Changes**:
- Import and register `token` command
- Add command description and options
- Update help text with ENV var documentation

**Verification**:
- Test `bild token --help` shows correct help
- Test `bild --help` lists token command
- Run `npm run lint` on modified file

---

### [x] Step: Enhance API Error Messages
<!-- chat-id: fd45be51-96b3-4ca9-aabd-20a4d88e41b8 -->

Update `src/lib/api.js` to provide better error messages mentioning ENV var option.

**Changes**:
- Enhance 401 error messages to mention ENV var option
- Update error handling to include token source info
- Improve "Not authenticated" error messages

**Verification**:
- Test error messages with invalid ENV token
- Test error messages with no token
- Run `npm run lint` on modified file

---

### [x] Step: Integration Testing and Verification
<!-- chat-id: aff26747-4779-404c-935f-fa5172f8aca5 -->

Perform comprehensive manual testing of all authentication scenarios.

**Test Cases**:
1. ENV var precedence (BILD_FIREBASE_TOKEN over FIREBASE_TOKEN over keychain)
2. Token command functionality (display, export, validate, source)
3. Login with --env flag
4. CI/CD workflow (ENV var only, no keychain)
5. Invalid token handling
6. Backward compatibility (keychain-only workflow)
7. Edge cases (empty ENV, whitespace, Bearer prefix)

**Verification**:
- Run `npm run lint` on all modified files
- Run `npm run lint:fix` if needed
- Test all scenarios manually
- Verify backward compatibility
- Create report at `.zenflow/tasks/add-web-based-authentication-to-074c/report.md`
