docs: add phase 0 environment assessment and TODO
- 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>
This commit is contained in:
darbs-claude
parent
9600277897
commit
5fbe70d424
2 changed files with 241 additions and 0 deletions
193
FINDINGS.md
Normal file
193
FINDINGS.md
Normal file
|
|
@ -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 |
|
||||
48
TODO.md
Normal file
48
TODO.md
Normal file
|
|
@ -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
|
||||
Loading…
Add table
Reference in a new issue