diff --git a/FINDINGS.md b/FINDINGS.md new file mode 100644 index 0000000..3fb20be --- /dev/null +++ b/FINDINGS.md @@ -0,0 +1,193 @@ +# Phase 0 Findings — core-devops + +**Date:** 2026-02-21 +**Issue:** #1 — phase 0: environment assessment + test baseline +**Branch:** main (assessed from `feat/phase-0-assessment`) + +--- + +## 1. Repository Classification + +This is a **workspace orchestrator (meta package)**, not a PHP package. + +| Attribute | Value | +|-----------|-------| +| Type | `meta` (as defined in `repos.yaml`) | +| Purpose | Developer workspace bootstrap for 18 Laravel packages | +| Primary languages | Bash, PowerShell, YAML | +| PHP code at root | **None** | +| `composer.json` | **Absent** | +| Packages directory | `packages/` — git-ignored, populated at runtime | + +--- + +## 2. PHP Tooling Assessment + +All standard PHP tooling tasks were attempted. Results below. + +### 2.1 `git checkout dev && composer install --no-interaction` + +``` +Composer could not find a composer.json file in /path/to/php-devops +To initialise a project, please create a composer.json file. +``` + +**Finding:** No `composer.json` exists at the repo root. This is expected — `core-devops` contains only +shell scripts and YAML configuration. PHP tools are not applicable here; they belong in +`packages/core-php/` and other individual packages. + +### 2.2 `vendor/bin/phpunit --testdox` + +``` +/bin/bash: vendor/bin/phpunit: No such file or directory +``` + +**Finding:** No test suite. No vendor directory. Not applicable. + +### 2.3 `vendor/bin/pint --test` + +``` +/bin/bash: vendor/bin/pint: No such file or directory +``` + +**Finding:** No linter. Not applicable. + +### 2.4 `vendor/bin/phpstan analyse --memory-limit=512M` + +``` +/bin/bash: vendor/bin/phpstan: No such file or directory +``` + +**Finding:** No static analysis. Not applicable. + +--- + +## 3. Shell Script Assessment + +Shell scripts constitute the core deliverable of this repo. + +### 3.1 Syntax validation + +``` +bash -n scripts/install-deps.sh → OK +bash -n scripts/install-core.sh → OK +``` + +**Finding:** Both Bash scripts pass syntax validation. + +### 3.2 `shellcheck` availability + +``` +shellcheck: command not found +``` + +**Finding:** `shellcheck` is not installed in this environment. Static analysis of shell scripts +cannot be completed without it. See TODO section. + +### 3.3 Identified issues + +| File | Issue | Severity | +|------|-------|----------| +| `scripts/install-core.sh` | `VERSION="v0.1.0"` hardcoded — stale | Medium | +| `scripts/install-deps.sh` | `COMPOSER_EXPECTED_SIG` — pinned hash may be stale | Medium | +| `scripts/install-deps.sh` | `GO_VERSION="1.22.0"` — pinned, not latest 1.24.x | Low | +| `scripts/install-core.sh` | `${actual_hash,,}` — bash 4+ only, fails on bash 3 (macOS) | Medium | + +> **Note:** The `dev` branch has a commit (`fix(install): use latest release instead of hardcoded version`) +> that resolves the `VERSION` hardcoding and the bash 3 compatibility issue. `main` has not received +> these fixes. + +--- + +## 4. Architecture Patterns + +### 4.1 Package registry (`repos.yaml`) + +Canonical list of 18 packages with type, dependencies, and metadata. Consumed by the `core` CLI +for cloning and workspace management. Package types: `foundation`, `module`, `product`, `template`, `meta`. + +### 4.2 `.core/` folder system + +Standardised workspace configuration folder: + +``` +.core/ +├── workspace.yaml # Active package, clone defaults, paths +├── plugin/ +│ ├── plugin.json # Claude Code manifest with skills + hooks +│ ├── skills/ # Context-aware guidance files +│ └── hooks/ # prefer-core.sh — informational hints +└── docs/ + └── core-folder-spec.md # Specification for per-package .core/ +``` + +Used both by this orchestrator repo and by each package. Specification lives in `.core/docs/core-folder-spec.md`. + +### 4.3 `core` CLI (external Go binary) + +Multi-repo management tool (`github.com/host-uk/core`). Not included in this repo. +Downloaded or built via `scripts/install-core.sh`. Provides `core health`, `core php test`, +`core commit`, etc. Workspace root commands delegate to active package. + +### 4.4 Cross-platform setup scripts + +| Script | Platform | Function | +|--------|----------|----------| +| `scripts/install-deps.sh` | Unix (macOS/Linux) | Installs Git, Go, PHP, Composer, Node, pnpm | +| `scripts/install-deps.ps1` | Windows | Same via Chocolatey | +| `scripts/install-core.sh` | Unix | Downloads or builds `core` CLI binary | +| `scripts/install-core.ps1` | Windows | Same for Windows | + +### 4.5 Security controls + +Both `install-core.sh` and `install-core.ps1` implement: +- Version pinning to prevent supply chain attacks +- SHA256 hash verification before installation +- Symlink detection to prevent directory traversal +- GPG tag signature verification (optional, skips gracefully if GPG absent) +- Secure temp directory creation (`mktemp` with restrictive permissions) +- Trap-based cleanup on interrupt + +Known limitations (documented in scripts): +- Checksums fetched from same origin as binaries (single trust root) +- No TLS certificate pinning (relies on system CA store) + +### 4.6 Claude Code integration + +`plugin.json` registers three skills (`workspace`, `switch-package`, `package-status`) and a +`pre_command` hook that suggests `core` CLI equivalents when raw `git` or `composer` commands +are detected. The hook is informational only (`exit 0`). + +--- + +## 5. Divergence: `main` vs `dev` + +`main` is behind `dev` by at least 20+ commits. `dev` contains: + +- GitHub Actions workflows (auto-label, CodeQL, free-tier scanners, AI worker) +- Issue and PR templates +- JetBrains IDE configuration +- VitePress documentation site +- `CONTRIBUTING.md`, `SECURITY.md`, `TEMPLATE_SETUP.md` +- `docker-compose.yml`, `.devcontainer/` +- Additional skills (`go-agent.md`, `php-agent.md`) +- `TODO.md` (session summary from 2026-02-01) + +**Finding:** `main` should receive a merge from `dev` after review. Most `dev` content is +additive (documentation, CI workflows, IDE config) and does not risk regressions. + +--- + +## 6. Summary + +| Check | Status | Notes | +|-------|--------|-------| +| `composer install` | N/A — no `composer.json` | Meta repo, not a PHP package | +| PHPUnit tests | N/A | Not applicable | +| Pint lint | N/A | Not applicable | +| PHPStan analysis | N/A | Not applicable | +| Shell syntax check | Pass | Both scripts pass `bash -n` | +| `shellcheck` | Not run | Not installed | +| Security controls | Present | SHA256, symlink detection, GPG | +| Stale pinned versions | Found | `VERSION`, `GO_VERSION`, `COMPOSER_EXPECTED_SIG` on `main` | +| `dev` → `main` merge | Pending | `dev` is ahead by 20+ commits | diff --git a/TODO.md b/TODO.md new file mode 100644 index 0000000..b5f5779 --- /dev/null +++ b/TODO.md @@ -0,0 +1,48 @@ +# TODO — core-devops + +**Updated:** 2026-02-21 (Phase 0 assessment) +**See:** [FINDINGS.md](FINDINGS.md) for full assessment details. + +--- + +## Phase 1 — Immediate (main branch health) + +- [ ] Merge `dev` → `main` after review (dev is 20+ commits ahead) +- [ ] Update `VERSION` in `scripts/install-core.sh` to auto-detect latest release (fix is on `dev`) +- [ ] Verify `COMPOSER_EXPECTED_SIG` in `scripts/install-deps.sh` is current +- [ ] Update `GO_VERSION` in `scripts/install-deps.sh` to 1.24.x + +## Phase 2 — Shell script quality + +- [ ] Install `shellcheck` in CI and run against all `.sh` files +- [ ] Add BATS (Bash Automated Testing System) tests for `install-deps.sh` and `install-core.sh` +- [ ] Fix `${var,,}` bash 4+ syntax in `install-core.sh` for macOS bash 3 compatibility (fix on `dev`) +- [ ] Add GitHub Actions workflow to lint shell scripts on push + +## Phase 3 — CI/CD for this repo + +- [ ] Add `.github/workflows/ci.yml` to run `shellcheck` and BATS tests +- [ ] Add `scripts/install-core.sh` smoke test in CI (build-from-source path) +- [ ] Enable CodeQL scanning (workflow exists on `dev`) +- [ ] Add Trivy/Gitleaks security scanning (workflows on `dev`) + +## Phase 4 — Documentation + +- [ ] Merge VitePress docs site from `dev` (`.vitepress/`, `doc/`) +- [ ] Add architecture diagram to README +- [ ] Document `.core/` folder spec for package maintainers +- [ ] Add SECURITY.md (exists on `dev`) +- [ ] Add CONTRIBUTING.md (exists on `dev`) + +## Phase 5 — Workspace tooling + +- [ ] Confirm `core` CLI v0.1.0 is released and binaries are available on GitHub +- [ ] Add `core doctor --fix` smoke test to CI +- [ ] Validate `repos.yaml` schema in CI (YAML lint + custom validation) +- [ ] Add `make test` target that runs shell script tests + +## Deferred + +- [ ] TLS certificate pinning for script downloads (currently relies on system CA store) +- [ ] Separate trust root for binary checksums (currently same origin as binaries) +- [ ] GPG signing of `core` CLI release tags