5fbe70d424
- FINDINGS.md: full assessment of core-devops architecture, PHP tooling gaps (no composer.json — meta repo), shell script syntax checks, security controls review, and dev vs main divergence summary - TODO.md: phased task list covering merge from dev, shellcheck/BATS integration, CI pipeline, and documentation improvements Closes #1 Co-Authored-By: Clotho <clotho@lthn.ai>
193 lines
6.4 KiB
Markdown
193 lines
6.4 KiB
Markdown
# 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 |
|