From f751b2eb4ee41864f0b5d321deffbda7ad795dfd Mon Sep 17 00:00:00 2001 From: James Maes Date: Wed, 31 Dec 2025 06:23:24 -0600 Subject: [PATCH] refactor: reorganize repository structure - Move design docs to docs/ - Move packaging files to packaging/ - Create GitHub issues and milestones for tracking - Update workflow and README references --- .claude/settings.local.json | 10 +- .github/workflows/build.yml | 23 ++-- CLAUDE.md | 15 +- README.md | 13 +- TODO.md | 130 ------------------ VISION.md => docs/architecture.md | 0 .../design/codegen-locks.md | 0 DESIGN-2.md => docs/design/design.md | 0 .../design/native-build.md | 0 .../design/requirements.txt | 0 cheaklist.md => docs/internal/checklist.md | 0 .../internal/prompt-resume.md | 0 {aur => packaging/aur}/PKGBUILD | 0 Dockerfile => packaging/docker/Dockerfile | 0 .../homebrew}/qctl.rb | 0 {scoop => packaging/scoop}/qctl.json | 0 16 files changed, 38 insertions(+), 153 deletions(-) delete mode 100644 TODO.md rename VISION.md => docs/architecture.md (100%) rename CODEGEN-LOCKS-V1.md => docs/design/codegen-locks.md (100%) rename DESIGN-2.md => docs/design/design.md (100%) rename NATIVE-BUILD.md => docs/design/native-build.md (100%) rename REQUIREMENTS-2.txt => docs/design/requirements.txt (100%) rename cheaklist.md => docs/internal/checklist.md (100%) rename PROMPT-RESUME.md => docs/internal/prompt-resume.md (100%) rename {aur => packaging/aur}/PKGBUILD (100%) rename Dockerfile => packaging/docker/Dockerfile (100%) rename {HomebrewFormula => packaging/homebrew}/qctl.rb (100%) rename {scoop => packaging/scoop}/qctl.json (100%) diff --git a/.claude/settings.local.json b/.claude/settings.local.json index 68ba84d..4b58f1f 100644 --- a/.claude/settings.local.json +++ b/.claude/settings.local.json @@ -20,7 +20,15 @@ "Bash(/Users/james.maes/Git.Local/QRunIO/qctl/qctl-core/target/qctl:*)", "Bash(gh run list:*)", "Bash(gh run view:*)", - "Bash(JAVA_HOME=/Library/Java/JavaVirtualMachines/graalvm-21.jdk/Contents/Home mvn spotless:apply:*)" + "Bash(JAVA_HOME=/Library/Java/JavaVirtualMachines/graalvm-21.jdk/Contents/Home mvn spotless:apply:*)", + "Bash(mkdir:*)", + "Bash(mv:*)", + "Bash(gh label list:*)", + "Bash(gh repo view:*)", + "Bash(gh issue create:*)", + "Bash(gh issue list:*)", + "Bash(gh api:*)", + "Bash(gh issue edit:*)" ] } } diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml index 0dae100..0a136ea 100644 --- a/.github/workflows/build.yml +++ b/.github/workflows/build.yml @@ -141,6 +141,7 @@ jobs: uses: docker/build-push-action@v6 with: context: . + file: packaging/docker/Dockerfile platforms: linux/amd64,linux/arm64 push: true tags: | @@ -176,25 +177,25 @@ jobs: SHA_WINDOWS=$(shasum -a 256 artifacts/qctl-windows-amd64.exe/qctl-windows-amd64.exe | cut -d' ' -f1) # Update Homebrew - sed -i "s/version \".*\"/version \"${VERSION}\"/" HomebrewFormula/qctl.rb - sed -i "s/PLACEHOLDER_ARM64_SHA256/${SHA_MACOS_ARM64}/" HomebrewFormula/qctl.rb - sed -i "s/PLACEHOLDER_AMD64_SHA256/${SHA_MACOS_AMD64}/" HomebrewFormula/qctl.rb - sed -i "s/PLACEHOLDER_LINUX_AMD64_SHA256/${SHA_LINUX_AMD64}/" HomebrewFormula/qctl.rb - sed -i "s/PLACEHOLDER_LINUX_ARM64_SHA256/${SHA_LINUX_ARM64}/" HomebrewFormula/qctl.rb + sed -i "s/version \".*\"/version \"${VERSION}\"/" packaging/homebrew/qctl.rb + sed -i "s/PLACEHOLDER_ARM64_SHA256/${SHA_MACOS_ARM64}/" packaging/homebrew/qctl.rb + sed -i "s/PLACEHOLDER_AMD64_SHA256/${SHA_MACOS_AMD64}/" packaging/homebrew/qctl.rb + sed -i "s/PLACEHOLDER_LINUX_AMD64_SHA256/${SHA_LINUX_AMD64}/" packaging/homebrew/qctl.rb + sed -i "s/PLACEHOLDER_LINUX_ARM64_SHA256/${SHA_LINUX_ARM64}/" packaging/homebrew/qctl.rb # Update Scoop - sed -i "s/\"version\": \".*\"/\"version\": \"${VERSION}\"/" scoop/qctl.json - sed -i "s|/v[0-9.]*\/|/v${VERSION}/|g" scoop/qctl.json - sed -i "s/PLACEHOLDER_WINDOWS_SHA256/${SHA_WINDOWS}/" scoop/qctl.json + sed -i "s/\"version\": \".*\"/\"version\": \"${VERSION}\"/" packaging/scoop/qctl.json + sed -i "s|/v[0-9.]*\/|/v${VERSION}/|g" packaging/scoop/qctl.json + sed -i "s/PLACEHOLDER_WINDOWS_SHA256/${SHA_WINDOWS}/" packaging/scoop/qctl.json # Update AUR - sed -i "s/pkgver=.*/pkgver=${VERSION}/" aur/PKGBUILD - sed -i "s/PLACEHOLDER_LINUX_SHA256/${SHA_LINUX_AMD64}/" aur/PKGBUILD + sed -i "s/pkgver=.*/pkgver=${VERSION}/" packaging/aur/PKGBUILD + sed -i "s/PLACEHOLDER_LINUX_SHA256/${SHA_LINUX_AMD64}/" packaging/aur/PKGBUILD - name: Commit package updates run: | git config user.name "github-actions[bot]" git config user.email "github-actions[bot]@users.noreply.github.com" - git add HomebrewFormula/qctl.rb scoop/qctl.json aur/PKGBUILD + git add packaging/homebrew/qctl.rb packaging/scoop/qctl.json packaging/aur/PKGBUILD git commit -m "chore(packages): update manifests to ${GITHUB_REF_NAME}" git push diff --git a/CLAUDE.md b/CLAUDE.md index ae67ec8..221f9a0 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -34,14 +34,17 @@ JAVA_HOME=/Library/Java/JavaVirtualMachines/graalvm-21.jdk/Contents/Home mvn cle ## Module Structure ``` -qctl-parent (reactor) +qctl/ ├── qctl-shared # DTOs, ExitCodes, SPI interfaces, utilities ├── qctl-core # Config, HTTP client, auth, cache, logging, Main entrypoint ├── qctl-qqq # Template scaffolding (init, list) with Handlebars ├── qctl-qbit # Package management commands, lockfile handling ├── qctl-qrun # OCI packaging and deployment commands ├── qctl-qstudio # AI planning commands (offline V1) -└── qctl-cli # Aggregator for native image build (only module with native profile) +├── qctl-cli # Aggregator for native image build (only module with native profile) +├── docs/ # Architecture and design documentation +├── packaging/ # Distribution manifests (Homebrew, Scoop, AUR, Docker) +└── codestyle/ # Checkstyle config and license headers ``` ## Architecture @@ -93,10 +96,10 @@ On tagged release (`git tag v1.0.0 && git push origin v1.0.0`): | Channel | Location | Auto-Updated | |---------|----------|--------------| -| Homebrew | `HomebrewFormula/qctl.rb` | Yes | -| Scoop | `scoop/qctl.json` | Yes | -| AUR | `aur/PKGBUILD` | Yes | -| Docker | `ghcr.io/qrun-io/qctl` | Yes | +| Homebrew | `packaging/homebrew/qctl.rb` | Yes | +| Scoop | `packaging/scoop/qctl.json` | Yes | +| AUR | `packaging/aur/PKGBUILD` | Yes | +| Docker | `packaging/docker/Dockerfile` | Yes | | GitHub | Releases | Yes | **Platforms**: Linux (x64, ARM64), macOS (Intel, Apple Silicon), Windows (x64) diff --git a/README.md b/README.md index 840589e..108650e 100644 --- a/README.md +++ b/README.md @@ -153,7 +153,10 @@ qctl/ ├── qctl-qqq/ # Scaffolding commands (init, list) ├── qctl-qbit/ # Package management commands ├── qctl-qrun/ # Deployment commands -└── qctl-qstudio/ # Planning commands +├── qctl-qstudio/ # Planning commands +├── docs/ # Architecture and design documentation +├── packaging/ # Distribution manifests (Homebrew, Scoop, AUR, Docker) +└── codestyle/ # Checkstyle config and license headers ``` ## Development @@ -190,10 +193,10 @@ This automatically: | Channel | Package | Auto-Updated | |---------|---------|--------------| -| Homebrew | `HomebrewFormula/qctl.rb` | Yes | -| Scoop | `scoop/qctl.json` | Yes | -| AUR | `aur/PKGBUILD` | Yes | -| Docker | `ghcr.io/qrun-io/qctl` | Yes | +| Homebrew | `packaging/homebrew/qctl.rb` | Yes | +| Scoop | `packaging/scoop/qctl.json` | Yes | +| AUR | `packaging/aur/PKGBUILD` | Yes | +| Docker | `packaging/docker/Dockerfile` | Yes | | GitHub | Releases page | Yes | ### Supported Platforms diff --git a/TODO.md b/TODO.md deleted file mode 100644 index 5b21963..0000000 --- a/TODO.md +++ /dev/null @@ -1,130 +0,0 @@ -# TODO - -## Completed - -### Phase 1: Framework Cleanup -- [x] Update dependencies to latest stable versions -- [x] Add ExitCodes constants class in qctl-shared -- [x] Update commands to use ExitCodes constants -- [x] Fix SystemPaths.ensureDir() logging -- [x] Remove duplicate Javadoc in JsonMerge.java -- [x] Add Handlebars dependency to qctl-qqq - -### Phase 2: qqq init Command -- [x] Create InitCommand with picocli structure -- [x] Create TemplateResolver for git/local/github sources -- [x] Create TemplateManifest parser -- [x] Create TemplateEngine with Handlebars rendering -- [x] Create PromptRunner for inquirer-style prompts -- [x] Create PostGenHookRunner for executing hooks -- [x] Create TemplatesHub to fetch templates.yaml from hub -- [x] Create ListCommand to list available templates -- [x] Fix Handlebars native image resource loading -- [x] Remove native profile from qctl-core (only qctl-cli builds) - -### Phase 3: CI/CD & Distribution -- [x] Create GitHub Actions workflow for multi-platform builds -- [x] Add Linux ARM64 build target -- [x] Fix macOS runner (macos-13 deprecated, use macos-15) -- [x] Add Homebrew formula with auto-update -- [x] Add Scoop manifest for Windows -- [x] Add AUR PKGBUILD for Arch Linux -- [x] Add Dockerfile for container distribution -- [x] Add Docker build/push to GHCR in workflow -- [x] Create comprehensive README -- [x] Verify GitHub Actions builds pass - -### Phase 4: Version & Interactive UX -- [x] Implement --version flag with build metadata (VersionProvider) -- [x] Add git-commit-id-maven-plugin for commit hash in version -- [x] Add version provider to qqq subcommand -- [x] Refactor init command to be interactive by default -- [x] Create ConsoleUI class for centralized console I/O -- [x] Update PromptRunner to use ConsoleUI -- [x] Template name defaults to new-qqq-application -- [x] Target directory prompts if not provided - -## Pending - -### Release -- [ ] Create first release (v0.1.0) -- [ ] Verify all distribution channels work -- [ ] Publish AUR package to aur.archlinux.org - -### Template System Enhancements -- [ ] Add template versioning (semver tags) -- [ ] Add template signature verification -- [ ] Add template caching for offline use -- [ ] Add `qctl qqq update` to check for template updates - -### qbit Commands -- [ ] Implement `qctl qbit add ` -- [ ] Implement `qctl qbit remove ` -- [ ] Implement `qctl qbit update` -- [ ] Implement lockfile integrity verification - -### qrun Commands -- [ ] Implement `qctl qrun deploy` -- [ ] Implement `qctl qrun logs` -- [ ] Implement `qctl qrun rollback` -- [ ] OCI image building - -### qstudio Commands -- [ ] Implement AI-assisted planning -- [ ] Integration with Claude API - -### Auth System -- [ ] OAuth2 device flow implementation -- [ ] Token refresh mechanism -- [ ] Secure credential storage (keychain integration) - -### Testing -- [ ] Add unit tests for TemplateEngine -- [ ] Add unit tests for TemplatesHub -- [ ] Add integration tests for init command -- [ ] Add golden tests for scaffolded projects - -### Documentation -- [ ] Add man pages -- [ ] Add shell completion scripts (bash, zsh, fish) -- [ ] Add examples directory with sample templates - -## Distribution Channels - -| Channel | Install Command | Manifest | -|---------|-----------------|----------| -| Homebrew | `brew tap QRun-IO/qctl && brew install qctl` | `HomebrewFormula/qctl.rb` | -| Scoop | `scoop bucket add qrun https://github.com/QRun-IO/qctl && scoop install qctl` | `scoop/qctl.json` | -| AUR | `yay -S qctl-bin` | `aur/PKGBUILD` | -| Docker | `docker run ghcr.io/qrun-io/qctl` | `Dockerfile` | -| GitHub | Download from Releases | `.github/workflows/build.yml` | - -## Supported Platforms - -| Platform | Architecture | Artifact | -|----------|--------------|----------| -| Linux | x64 | `qctl-linux-amd64` | -| Linux | ARM64 | `qctl-linux-arm64` | -| macOS | Intel | `qctl-macos-amd64` | -| macOS | Apple Silicon | `qctl-macos-arm64` | -| Windows | x64 | `qctl-windows-amd64.exe` | - -## Notes - -### Native Image Requirements -- GraalVM 21+ required -- Only `qctl-cli` module has native profile -- Handlebars requires `--initialize-at-run-time=com.github.jknack.handlebars.helper.DefaultHelperRegistry` -- Jackson requires reflection config for record types - -### Templates Hub -- Central registry: https://github.com/QRun-IO/templates-hub -- Templates defined in `templates.yaml` -- Each template references a git repo with Handlebars templates - -### Release Process -```bash -git tag v1.0.0 -git push origin v1.0.0 -``` -This triggers GitHub Actions to build, release, and update all package manifests. diff --git a/VISION.md b/docs/architecture.md similarity index 100% rename from VISION.md rename to docs/architecture.md diff --git a/CODEGEN-LOCKS-V1.md b/docs/design/codegen-locks.md similarity index 100% rename from CODEGEN-LOCKS-V1.md rename to docs/design/codegen-locks.md diff --git a/DESIGN-2.md b/docs/design/design.md similarity index 100% rename from DESIGN-2.md rename to docs/design/design.md diff --git a/NATIVE-BUILD.md b/docs/design/native-build.md similarity index 100% rename from NATIVE-BUILD.md rename to docs/design/native-build.md diff --git a/REQUIREMENTS-2.txt b/docs/design/requirements.txt similarity index 100% rename from REQUIREMENTS-2.txt rename to docs/design/requirements.txt diff --git a/cheaklist.md b/docs/internal/checklist.md similarity index 100% rename from cheaklist.md rename to docs/internal/checklist.md diff --git a/PROMPT-RESUME.md b/docs/internal/prompt-resume.md similarity index 100% rename from PROMPT-RESUME.md rename to docs/internal/prompt-resume.md diff --git a/aur/PKGBUILD b/packaging/aur/PKGBUILD similarity index 100% rename from aur/PKGBUILD rename to packaging/aur/PKGBUILD diff --git a/Dockerfile b/packaging/docker/Dockerfile similarity index 100% rename from Dockerfile rename to packaging/docker/Dockerfile diff --git a/HomebrewFormula/qctl.rb b/packaging/homebrew/qctl.rb similarity index 100% rename from HomebrewFormula/qctl.rb rename to packaging/homebrew/qctl.rb diff --git a/scoop/qctl.json b/packaging/scoop/qctl.json similarity index 100% rename from scoop/qctl.json rename to packaging/scoop/qctl.json