243 lines
9.7 KiB
Markdown
243 lines
9.7 KiB
Markdown
# Session State
|
|
|
|
Last updated: 2026-01-03
|
|
|
|
## Current Status
|
|
|
|
**Stories #18-25 complete.** All qqq template system stories finished except #26 (merge mode). Ready for Story #26 or to start Epic #11 (qbit package management).
|
|
|
|
## Recently Completed
|
|
|
|
### Story #25 - Improve Error Messages (2026-01-04)
|
|
|
|
Implemented structured error handling with recovery suggestions:
|
|
- Created `SuggestionEngine` with Levenshtein distance for fuzzy matching
|
|
- Created `TemplateError` with categories mapped to exit codes
|
|
- Created `ErrorFormatter` for consistent ANSI-colored output
|
|
- Added "Did you mean?" suggestions for mistyped template names
|
|
- Added `--verbose` flag to show stack traces
|
|
- Added 27 unit tests (13 SuggestionEngine, 6 TemplateError, 8 ErrorFormatter)
|
|
- Updated InitCommand and ListCommand to use structured errors
|
|
|
|
### Story #24 - Add Prompt Validation (2026-01-03)
|
|
|
|
Implemented input validation with retry loop for template prompts:
|
|
- Created `PromptValidation` record for validation rules (pattern, length, range, enum)
|
|
- Created `PromptValidator` class with support for required, pattern, length, range, and enum validation
|
|
- Updated `PromptRunner` to validate input and re-prompt on failure
|
|
- Added validation for `--var` CLI overrides with fallback to interactive prompt
|
|
- Added `ConsoleUI` methods for validation feedback (error checkmark, success checkmark, warning)
|
|
- Added 20 unit tests for PromptValidator
|
|
|
|
Manifest schema now supports:
|
|
```yaml
|
|
prompts:
|
|
- name: packageName
|
|
message: "Java package"
|
|
required: true
|
|
validation:
|
|
pattern: "^[a-z][a-z0-9]*(\\.[a-z][a-z0-9]*)*$"
|
|
message: "Must be a valid Java package name"
|
|
```
|
|
|
|
### Story #23 - Voyage Mock API Integration (2026-01-03)
|
|
|
|
Implemented TemplateRegistry abstraction for template management:
|
|
- Created `TemplateRegistry` interface with list/get/download/refresh methods
|
|
- Created `TemplateInfo` record for template metadata
|
|
- Created `MockTemplateRegistry` with embedded template data
|
|
- Created `GitHubTemplateRegistry` wrapping existing TemplatesHub
|
|
- Created `TemplateRegistryFactory` for registry selection via env var
|
|
- Refactored `ListCommand` to use TemplateRegistry with `--refresh` flag
|
|
- Refactored `InitCommand` to use TemplateRegistry
|
|
- Added 13 unit tests for registry classes
|
|
- Added native-image reflection config for TemplateInfo
|
|
|
|
### Story #22 - Migrate templates-hub to Velocity (2026-01-03)
|
|
|
|
Completed migration of new-qqq-application-template:
|
|
- Restructured template repo with `template/` subdirectory
|
|
- Converted all Java files to Velocity syntax (`$variable`, `${variable}`)
|
|
- Fixed pom.xml with literal blocks (`#[[${maven.prop}]]#`) for Maven properties
|
|
- Added native-image reflection config for Velocity runtime classes
|
|
- Implemented verbatim file handling for shell scripts (mvnw, gradlew)
|
|
- Added Maven property detection to skip validation for `${prop.name}` patterns
|
|
- All changes pushed to both template repo and templates-hub
|
|
|
|
### Story #21 - Template Manifest Schema v2 (2026-01-03)
|
|
|
|
Updated manifest schema to v2 with backward compatibility:
|
|
- Added `schemaVersion` field (Integer) to TemplateManifest and TemplateEntry
|
|
- Added `minimumQctlVersion` field with version check in InitCommand
|
|
- Added `required` field (Boolean) to Prompt record
|
|
- Added `phase` field (String) to PostGenHook record
|
|
- Added `getEffectiveSchemaVersion()` helper method (defaults to 1)
|
|
- Added `isVersionSatisfied()` and `parseVersion()` helpers in InitCommand
|
|
- Updated TemplateEngineTest constructor calls (9 → 11 params)
|
|
|
|
Simplified scope (per user agreement):
|
|
- Deferred `prompts[].validation` to Story #24
|
|
- Deferred conditional fields to future story
|
|
|
|
### Story #20 - Directory Transforms (2026-01-03)
|
|
|
|
Implemented post-render file transforms for template processing:
|
|
- Created `Transform.java` record with type, pattern, replacement fields
|
|
- Created `TransformExecutor.java` for rename/delete operations using glob patterns
|
|
- Added `transforms` field to `TemplateManifest` and `TemplatesHub.TemplateEntry`
|
|
- Integrated transform execution in `InitCommand.java` after rendering
|
|
- Added 13 tests for TransformExecutor
|
|
|
|
Simplified scope (per user agreement):
|
|
- Only `rename` and `delete` transforms (dropped `move` as redundant with path variables)
|
|
- Glob pattern matching with `${varName}` substitution in replacement strings
|
|
|
|
Manifest schema now supports:
|
|
```yaml
|
|
transforms:
|
|
- type: rename
|
|
pattern: "**/*Template*.java"
|
|
replacement: "${appClassName}.java"
|
|
- type: delete
|
|
pattern: "**/.gitkeep"
|
|
```
|
|
|
|
### Story #19 - Computed Variables (2026-01-04)
|
|
|
|
Implemented computed variable support for template manifests:
|
|
- Added `replace()` method to `StringTool.java` for string substitution
|
|
- Created `ComputedVariable.java` record for manifest definitions
|
|
- Added `computed` field to `TemplateManifest` and `TemplatesHub.TemplateEntry`
|
|
- Added `evaluateComputed()` method to `TemplateEngine.java`
|
|
- Updated `InitCommand.java` to evaluate computed vars after prompts
|
|
- Added 16 new tests (9 ComputedVariable + 7 StringTool.replace)
|
|
|
|
Manifest schema now supports:
|
|
```yaml
|
|
computed:
|
|
- name: packagePath
|
|
expression: "$str.replace($packageName, '.', '/')"
|
|
- name: appClassName
|
|
expression: "$str.pascal($appName)"
|
|
```
|
|
|
|
### Story #18 - Velocity Engine (2026-01-04)
|
|
|
|
Implemented Apache Velocity template engine replacing Handlebars:
|
|
- Created `StringTool.java` with transformation methods ($str.camel(), etc.)
|
|
- Created `TemplateRenderException.java` for fail-fast error handling
|
|
- Refactored `TemplateEngine.java` to use VelocityEngine
|
|
- Added 51 unit tests (15 new + 36 existing)
|
|
- Updated native-image reflect-config.json for Velocity classes
|
|
|
|
### Epic #13-17 Story Details (2026-01-04)
|
|
|
|
Fleshed out all remaining stories for Epics #13-17:
|
|
- **Epic #13** (qrun Build & Publish): #36-42 - Jib integration, OCI packaging, publishing, labels, digest verification, release channels, rollback
|
|
- **Epic #14** (qrun Service Operations): #43-49 - Status, logs (SSE streaming), stop, start, restart, deployment history, scale
|
|
- **Epic #15** (qstudio AI Planning): #50-53 - Code indexing, plan generation (multi-LLM), path policies, plan ledger
|
|
- **Epic #16** (Authentication & Security): #54-57 - OIDC device flow, service accounts, signature verification (Sigstore/PGP), OS keychain integration
|
|
- **Epic #17** (Enterprise Features): #58-61 - SSO (SAML/OIDC), RBAC, audit logging, org/team management
|
|
|
|
### Epic #12 Story Details (2026-01-04)
|
|
|
|
Fleshed out all 9 stories for Epic #12 (qqq - Template System) with:
|
|
- User stories and design specs
|
|
- Architecture diagrams (current vs target state)
|
|
- Files to create/modify tables
|
|
- Implementation task checklists
|
|
- Acceptance criteria
|
|
|
|
Stories updated: #18-26 (Velocity, computed vars, transforms, manifest v2, templates migration, Voyage mock, validation, errors, merge mode)
|
|
|
|
### Epic #11 Story Details (2026-01-04)
|
|
|
|
Fleshed out all 9 stories for Epic #11 (qbit - Package Management) with:
|
|
- User stories and design specs
|
|
- Command interfaces with examples
|
|
- Files to create/modify tables
|
|
- Implementation task checklists
|
|
- Acceptance criteria
|
|
|
|
Stories updated: #27-35 (search, add, remove, update, list, SemVer, conflicts, vendor, integrity)
|
|
|
|
### Roadmap & Issue Creation (2026-01-03)
|
|
|
|
Created comprehensive roadmap and GitHub project structure:
|
|
|
|
1. **Roadmap document** - `docs/ROADMAP.md` with user journey focus
|
|
2. **Milestones** - v0.2.0, v0.3.0, v1.0.0
|
|
3. **Epics** - 7 epic issues (#11-#17) with proper labels
|
|
4. **Stories** - 44 story issues (#18-#61) linked as sub-issues
|
|
5. **Issue types** - Epic for #11-17, Feature for #18-61
|
|
6. **Sub-issues** - All stories linked to parent epics
|
|
|
|
### Epic Summary
|
|
|
|
| Epic | Milestone | Stories |
|
|
|------|-----------|---------|
|
|
| #11 qbit - Package Management | v0.2.0 | #27-35 (9) |
|
|
| #12 qqq - Template System | v0.2.0 | #18-26 (9) |
|
|
| #13 qrun - Build & Publish | v0.3.0 | #36-42 (7) |
|
|
| #14 qrun - Service Operations | v0.3.0 | #43-49 (7) |
|
|
| #15 qstudio - AI Planning | v1.0.0 | #50-53 (4) |
|
|
| #16 Authentication & Security | v1.0.0 | #54-57 (4) |
|
|
| #17 Enterprise Features | v1.0.0 | #58-61 (4) |
|
|
|
|
### Key Design Decisions
|
|
|
|
- **Template engine**: Apache Velocity (not Handlebars) for QQQ consistency
|
|
- **Voyage integration**: Mock APIs for now, real integration when ready
|
|
- **User journey focus**: Roadmap organized by concrete use cases
|
|
|
|
## Current Branch State
|
|
|
|
- **Branch**: `develop`
|
|
- **Clean**: Yes (no uncommitted changes)
|
|
|
|
## Next Steps / TODO
|
|
|
|
### v0.2.0 - Create & Manage (Priority)
|
|
|
|
**Epic #12 - qqq Template System** (in progress):
|
|
1. ~~#18 - Replace Handlebars with Apache Velocity~~ DONE
|
|
2. ~~#19 - Add computed variables support~~ DONE
|
|
3. ~~#20 - Implement directory transforms~~ DONE
|
|
4. ~~#21 - Update template manifest schema v2~~ DONE
|
|
5. ~~#22 - Migrate templates-hub to Velocity~~ DONE
|
|
6. ~~#23 - Integrate template listing with Voyage mock~~ DONE
|
|
7. ~~#24 - Add prompt validation~~ DONE
|
|
8. ~~#25 - Improve error messages~~ DONE
|
|
9. #26 - Implement --merge mode (next)
|
|
|
|
**Epic #11 - qbit Package Management** (after qqq):
|
|
1. #27 - qbit search command
|
|
2. #28 - qbit add with version constraints
|
|
3. #29 - qbit remove command
|
|
4. #30 - qbit update command
|
|
5. #31 - qbit list command
|
|
6. #32 - SemVer constraint resolution
|
|
7. #33 - Dependency conflict detection
|
|
8. #34 - Vendor directory layout
|
|
9. #35 - SHA-512 integrity verification
|
|
|
|
### Infrastructure
|
|
|
|
- GitHub project: https://github.com/orgs/QRun-IO/projects/12
|
|
|
|
## How to Continue
|
|
|
|
When starting a new session, say "continue from last session" and Claude will:
|
|
1. Read this file for context
|
|
2. Check git status for any pending work
|
|
3. Review GitHub project for current sprint
|
|
|
|
## Key Files
|
|
|
|
| File | Purpose |
|
|
|------|---------|
|
|
| `CLAUDE.md` | Project overview and build commands |
|
|
| `docs/ROADMAP.md` | User journey roadmap |
|
|
| `docs/internal/session-state.md` | This file - session continuity |
|
|
| `.github/workflows/build.yml` | CI/CD pipeline |
|