refactoring

Author: tom-sapletta-com

.gitignore

@@ -103,3 +103,4 @@ htmlcov/
 # Backup files
 *.bak
 *.backup
+examples/workspace/report.csv

CHANGELOG.md

@@ -1,5 +1,59 @@
 ## [Unreleased]
 
+### Fixed
+- `workspace compare`: do not flag `import-makefile-hint` as a missing
+  common task/workflow in projects without a `Makefile` — the hint is
+  meaningless there (it only echoes a tip to run `taskfile import Makefile`).
+  Eliminates false-positive recommendations in mixed-project workspaces.
+
+### Added — `taskfile workspace` (multi-project group operations)
+- New module `taskfile.workspace` providing discovery, filtering, and group
+  operations across many local projects under a given path.
+- New CLI command tree `taskfile workspace`:
+  - `list` — list matching projects with filters (`--has-task`,
+    `--has-workflow`, `--taskfile-only`, `--doql-only`, `--docker-only`,
+    `--name REGEX`).
+  - `status` — one-row-per-project overview (git, Taskfile, doql, Docker).
+  - `tasks` / `workflows` — frequency tables across projects.
+  - `validate` — report manifest issues (empty workflows, missing `app{}`, …).
+  - `analyze [-o FILE.csv]` — full metrics + issues + recommendations.
+  - `compare -r ROOT [-r ROOT …] [-o FILE.csv]` — peer-benchmarked
+    comparison across multiple roots (missing common tasks/workflows,
+    sync issues, median delta).
+  - `fix [--dry-run]` — repair manifests (remove `import-makefile-hint`
+    when no Makefile, fill empty workflows, drop orphans, add missing
+    workflows from Taskfile tasks).
+  - `run TASK [--dry-run --fail-fast --name REGEX]` — run a task in every
+    project that has it.
+  - `doctor` — run `taskfile doctor` in every project.
+  - `deploy` — group `taskfile up` / `docker compose up -d`.
+- Python API: `discover_projects`, `filter_projects`, `validate_project`,
+  `analyze_project`, `compare_projects`, `fix_project`, `run_in_project`,
+  `run_task_in_projects`, `Project`, `CommandResult`, `FixResult`.
+- Respects `--depth N` (default 2) and a fixed exclusion list
+  (`venv`, `.venv`, `node_modules`, `dist`, `build`, hidden dirs, …).
+- New docs: `docs/WORKSPACE.md` with full command reference, Python API
+  reference, and CSV column spec for `compare`.
+
+### Added — `doql workspace` (companion command)
+- The sister project `doql` now exposes an equivalent `workspace` command
+  focused on `app.doql.css` manifests. Core commands
+  (`list`/`analyze`/`validate`/`run`) work without external dependencies;
+  `fix` delegates to `taskfile.workspace` when `taskfile` is installed.
+- Analysis columns surface DOQL-specific data: workflows, entities,
+  databases, interfaces.
+
+### Docs
+- `README.md` + `docs/WORKSPACE.md`: new "Workspace" section + Python API
+  examples + full CSV column reference.
+- `docs/WORKSPACE.md`: sibling command note for `doql workspace`.
+
+### Removed
+- Dropped ad-hoc scripts `analyze_projects.py`, `fix_projects.py`,
+  `update_projects.py`, and the generated `projects_analysis.csv` —
+  functionality now lives in `taskfile.workspace` and `taskfile workspace`
+  CLI.
+
 ## [0.3.88] - 2026-04-17
 
 ### Docs

README.md

@@ -903,6 +903,11 @@ taskfile workspace validate --root ~/github/semcod
 # Generate CSV analysis report
 taskfile workspace analyze --root ~/github/semcod -o semcod_analysis.csv
 
+# Peer-benchmarked comparison across MULTIPLE roots (missing common tasks,
+# sync issues, median comparison) — CSV is the intended source of truth
+taskfile workspace compare -r ~/github/semcod -r ~/github/oqlos \
+  -o ~/github/projects_report.csv
+
 # Fix manifest errors (empty workflows, orphan workflows, …)
 taskfile workspace fix --root ~/github/semcod --dry-run
 taskfile workspace fix --root ~/github/semcod
@@ -1254,7 +1259,7 @@ my-project/
 
 ---
 
-## Examples (24 total)
+## Examples (56 total)
 
 ### Getting Started
 
@@ -1264,6 +1269,8 @@ my-project/
 | [saas-app](examples/saas-app/) | ⭐⭐ | local/staging/prod with pipeline |
 | [multiplatform](examples/multiplatform/) | ⭐⭐⭐ | Web + Desktop, CI/CD generation |
 | [codereview.pl](examples/codereview.pl/) | ⭐⭐⭐⭐ | 6 CI platforms, Quadlet, docker-compose |
+| [workspace](examples/workspace/) | ⭐⭐ | `taskfile workspace` — multi-project operations |
+| [enhanced-error-reporting](examples/enhanced-error-reporting/) | ⭐⭐ | `--teach`, `--explain`, error diagnostics |
 
 ### Publishing
 
@@ -1274,6 +1281,8 @@ my-project/
 | [publish-cargo](examples/publish-cargo/) | crates.io | Rust |
 | [publish-docker](examples/publish-docker/) | GHCR + Docker Hub | any (multi-arch) |
 | [publish-github](examples/publish-github/) | GitHub Releases | Go (binaries + checksums) |
+| [publish-desktop](examples/publish-desktop/) | AppImage / .deb / .dmg / .msi | Electron / Tauri |
+| [publish-mobile](examples/publish-mobile/) | App Store + Google Play | React Native / Flutter |
 | [multi-artifact](examples/multi-artifact/) | 5 registries | Python + Rust + Node.js + Docker |
 
 ### Fleet & IoT
@@ -1283,15 +1292,35 @@ my-project/
 | [fleet-rpi](examples/fleet-rpi/) | 6 RPi, `hosts:` shorthand, rolling/canary groups |
 | [edge-iot](examples/edge-iot/) | IoT gateways, `hosts:`, `ssh_port: 2200`, all 3 group strategies, `condition` |
 
-### Infrastructure & Cloud
+### Infrastructure & Cloud (IaC)
 
 | Example | Features |
 |---------|----------|
 | [ci-pipeline](examples/ci-pipeline/) | `pipeline` section, `stage` field, `taskfile ci generate/run/preview`, `condition`, `silent` |
 | [kubernetes-deploy](examples/kubernetes-deploy/) | Helm, multi-cluster (staging + prod-eu + prod-us), canary groups |
-| [iac-terraform](examples/iac-terraform/) | `dir` (working_dir), `env_file`, Terraform plan/apply/destroy, `condition` |
-| [cloud-aws](examples/cloud-aws/) | Lambda + ECS + S3, multi-region, `env_file`, `environment_groups` |
-| [quadlet-podman](examples/quadlet-podman/) | `service_manager: quadlet`, `compose` section, `ssh_port: 2222`, `taskfile deploy/setup` |
+| [iac-terraform](examples/iac-terraform/) | Terraform plan/apply/destroy, `dir`, `env_file`, `condition` |
+| [iac-opentofu](examples/iac-opentofu/) | OpenTofu (open-source Terraform fork) |
+| [iac-terragrunt](examples/iac-terragrunt/) | Terragrunt multi-module IaC |
+| [iac-pulumi](examples/iac-pulumi/) | Pulumi IaC (TypeScript/Python/Go) |
+| [iac-ansible](examples/iac-ansible/) | Ansible playbook integration |
+| [iac-cloudformation](examples/iac-cloudformation/) | AWS CloudFormation stacks |
+| [iac-cdk-aws](examples/iac-aws-cdk/) | AWS CDK (Cloud Development Kit) |
+| [iac-cdktf](examples/iac-cdktf/) | CDK for Terraform |
+| [iac-bicep](examples/iac-bicep/) | Azure Bicep deployments |
+| [iac-helm](examples/iac-helm/) | Helm chart management |
+| [iac-kustomize](examples/iac-kustomize/) | Kustomize overlays |
+| [iac-argocd](examples/iac-argocd/) | ArgoCD GitOps |
+| [iac-fluxcd](examples/iac-fluxcd/) | FluxCD GitOps |
+| [iac-crossplane](examples/iac-crossplane/) | Crossplane Kubernetes-native IaC |
+| [iac-nomad](examples/iac-nomad/) | HashiCorp Nomad jobs |
+| [iac-serverless](examples/iac-serverless/) | Serverless Framework (AWS Lambda) |
+| [iac-packer](examples/iac-packer/) | Packer image builds |
+| [iac-vagrant](examples/iac-vagrant/) | Vagrant VM management |
+| [iac-nixos](examples/iac-nixos/) | NixOS declarative config |
+| [iac-docker-compose](examples/iac-docker-compose/) | Docker Compose multi-env |
+| [iac-gcp-deployment-manager](examples/iac-gcp-deployment-manager/) | GCP Deployment Manager |
+| [cloud-aws](examples/cloud-aws/) | Lambda + ECS + S3, multi-region, `environment_groups` |
+| [quadlet-podman](examples/quadlet-podman/) | `service_manager: quadlet`, Podman → systemd |
 
 ### Patterns & Import
 
@@ -1309,8 +1338,21 @@ my-project/
 |---------|----------|
 | [monorepo-microservices](examples/monorepo-microservices/) | `platforms`, `build_cmd`/`deploy_cmd`, `condition`, `dir`, `stage`, `platform` filter |
 | [fullstack-deploy](examples/fullstack-deploy/) | **ALL CLI commands**: deploy, setup, release, init, validate, info, ci, --dry-run |
+| [mega-saas](examples/mega-saas/) | Large SaaS with full pipeline, environments, groups |
 | [mega-saas-v2](examples/mega-saas-v2/) | `hosts:`, `deploy:`, `addons:`, smart defaults — **70% less YAML** vs mega-saas |
 
+### 🤖 AI Tools
+
+| Example | Tool |
+|---------|------|
+| [ai-aider](examples/ai-aider/) | Aider — TDD, review, lint-fix |
+| [ai-claude-code](examples/ai-claude-code/) | Claude Code — piped review, refactor |
+| [ai-codex](examples/ai-codex/) | OpenAI Codex — autonomous, sandbox |
+| [ai-copilot](examples/ai-copilot/) | GitHub Copilot — explain, suggest, PR |
+| [ai-cursor](examples/ai-cursor/) | Cursor — rules, Composer, workflows |
+| [ai-windsurf](examples/ai-windsurf/) | Windsurf — rules, Cascade workflows |
+| [ai-gemini-cli](examples/ai-gemini-cli/) | Gemini CLI — multimodal, piped review |
+
 ```bash
 # CI pipeline — generate + run locally
 cd examples/ci-pipeline
@@ -1626,7 +1668,7 @@ taskfile/
 │   ├── scaffold/          # Template generation
 │   └── cigen/             # CI/CD generators
 ├── tests/                  # Test suite
-├── examples/               # Example configurations (24 examples)
+├── examples/               # Example configurations (56 examples)
 ├── docs/                   # Documentation
 └── Taskfile.yml           # Project's own tasks
 ```
@@ -1685,7 +1727,7 @@ pytest --cov=taskfile -m "not slow"
 
 ### Test Performance Summary
 
-- **Full suite**: ~24s (876 tests including e2e SSH tests)
+- **Full suite**: ~22s (918 tests including e2e SSH tests)
 - **Fast tests only**: ~15s (skips slow SSH integration tests)
 - **Slow tests**: e2e SSH connectivity tests (5+ seconds each)
 

ROADMAP.md

@@ -0,0 +1,108 @@
+# Roadmap
+
+The high-level direction for `taskfile`. For day-to-day follow-ups see
+[`TODO.md`](TODO.md). For shipped items see
+[`CHANGELOG.md`](CHANGELOG.md).
+
+## Principles
+
+- **One YAML file** describes environments, tasks, groups, and deploy targets.
+- **Zero new DSL** — leans on existing YAML + familiar shell.
+- **Local first** — everything works offline before it reaches CI.
+- **Incremental adoption** — you can import Makefiles, GitHub Actions,
+  GitLab CI, and shell scripts instead of rewriting them.
+- **Group operations** — a single command should scale from one project
+  to a folder full of them.
+
+---
+
+## Shipped (highlights)
+
+### 0.3.x
+- Environments, tasks, environment groups, fleet management.
+- Multi-platform deploy (Docker Compose, Podman Quadlet, Kubernetes).
+- CI/CD generation (GitHub Actions, GitLab CI, Jenkins, CircleCI, Drone).
+- Registry authentication and multi-registry publishing.
+- Scaffold templates (`taskfile scaffold <name>`).
+- Diagnostics (`taskfile doctor`, `taskfile validate`, `taskfile watch`,
+  `taskfile graph`).
+- REST API server (`taskfile serve`).
+- Package management (`taskfile pkg install / search`).
+- Interactive mode, tab completion, colorised output.
+
+### Current (Unreleased)
+- **`taskfile workspace`** — multi-project group operations
+  (`list`, `status`, `tasks`, `workflows`, `validate`, `analyze`, `compare`,
+  `fix`, `run`, `doctor`, `deploy`).
+- **`doql workspace`** — companion command focused on `.doql.css`.
+- Peer-benchmarking across multiple roots with CSV export.
+- Manifest fixing (empty workflows, orphans, missing workflows).
+
+---
+
+## Near-term (next minor)
+
+### Workspace
+- `workspace run --parallel N` — parallel execution across projects.
+- `workspace graph` — dependency graph across projects (mermaid/DOT).
+- `workspace compare --format {json,markdown}` — richer output formats.
+- `workspace search QUERY` — grep across task commands and workflow bodies.
+- Per-project "score" column (0–100) summarising health + peer conformance.
+
+### Core
+- First-class JSON output for `doctor` (needed by `workspace doctor`).
+- Structured logs (`--log-format json`) for all commands.
+- Better error messages when Taskfile references undefined environments.
+
+### Docs
+- Dedicated "Recipes" section in `docs/WORKSPACE.md` (common multi-root
+  flows, rollback, staged rollout across many services).
+- Asciinema demos: workspace compare, fleet rolling deploy.
+
+---
+
+## Medium-term
+
+### Workspace
+- `workspace sync-manifests` — interactive: propagate common tasks from
+  peers back into outliers.
+- `workspace install` — parallel bootstrap (`pip install -e .`,
+  `npm install`, `cargo fetch`) for a folder of freshly cloned projects.
+- Plugin system for custom analyzers (e.g. security scan, license check)
+  that appear as extra columns in `workspace compare` output.
+
+### Core
+- OpenAPI 3.1 generator for `taskfile serve` (separate from the existing
+  informal REST API).
+- Native Windows support (currently Linux/macOS-first; some shell-isms).
+- Task-level caching with explicit cache keys (like Turbo/Nx).
+
+### Ecosystem
+- VS Code extension: inline `taskfile` runner + environment switcher +
+  workspace explorer view.
+- pre-commit hooks that run `workspace validate` automatically.
+
+---
+
+## Long-term / exploratory
+
+- **Distributed execution** — run the same task across a fleet of dev
+  machines or CI runners with a single command.
+- **Task marketplace** — `taskfile pkg install` already works; a curated
+  registry of reusable task bundles (lint, test, deploy-to-k8s, …) would
+  accelerate adoption.
+- **Self-hosted web UI** — on top of `taskfile serve` with environment
+  groups, fleet status, and workspace reports.
+- **Speculative execution** — for `workspace compare` style analyses,
+  compute against a snapshot instead of re-scanning every project.
+
+---
+
+## Non-goals
+
+- Replacing Make/CMake/Bazel for heavy build orchestration —
+  `taskfile` is a glue layer, not a build system.
+- Implementing a new DSL; YAML + shell + embedded functions is enough.
+- Becoming a CI system — we generate CI configs, we don't host runners.
+- Package-manager semantics — `taskfile pkg` installs task bundles, not
+  application dependencies.

TODO.md

@@ -1,8 +1,50 @@
 # TODO
 
-**Generated by:** prefact v0.1.41
-**Generated on:** 2026-04-17T12:56:29.759225
-**Total issues:** 0 active, 0 completed
+Active follow-ups for the `taskfile` package.
 
 ---
 
+## Workspace (multi-project operations)
+
+### Stability
+- [ ] `workspace run` — add `--parallel N` to run tasks in parallel across
+      multiple projects (current impl is serial).
+- [ ] `workspace run` — honor per-project timeout overrides from
+      Taskfile (`env.timeout` or task metadata).
+- [ ] `workspace doctor` — parse structured output from `taskfile doctor`
+      (JSON mode) instead of string-matching keywords.
+
+### Features
+- [ ] `workspace graph` — render a DOT/mermaid graph of task dependencies
+      across many projects; highlight shared/unique tasks.
+- [ ] `workspace install` — run `pip install -e .` / `npm install` in every
+      project in parallel (bootstrap a fresh clone).
+- [ ] `workspace sync-manifests` — inverse of `fix`: propagate tasks that
+      exist in most peers back into outliers (interactive).
+- [ ] `workspace search QUERY` — grep task commands, descriptions, and
+      workflow bodies across all projects.
+
+### CSV / reporting
+- [ ] `workspace compare` — add `--format json` and `--format markdown` in
+      addition to CSV.
+- [ ] `workspace compare` — emit a per-project recommendations file
+      (`<project>/WORKSPACE_RECS.md`) when `--write-recs` is passed.
+- [ ] `workspace analyze` / `compare` — add a "score" column (0–100) based
+      on completeness + peer conformance.
+
+### Documentation / examples
+- [ ] Add `examples/workspace/` with multiple tiny projects + a Makefile
+      target that runs the full workspace flow.  ← DONE
+- [ ] Add `docs/WORKSPACE.md` section "Recipes": common multi-root flows.
+- [ ] Record an asciinema demo of `workspace compare` producing a CSV.
+
+## doql companion command
+- [ ] Add `doql workspace doctor` that runs `doql validate` in each project
+      and aggregates errors.
+- [ ] Add `doql workspace build --parallel` for monorepo-scale builds.
+
+## Tests
+- [ ] Add end-to-end test that spins up 3 fake projects in `tmp_path`,
+      runs `workspace compare`, and asserts CSV header + row count.
+- [ ] Smoke-test `workspace compare` against `~/github/semcod` in CI when
+      the folder is present (skip otherwise).