cli-anything:validate Command

Validate a CLI harness against HARNESS.md standards and best practices.

CRITICAL: Read HARNESS.md First

Before validating, read ./HARNESS.md. It is the single source of truth for all validation checks below. Every check in this command maps to a requirement in HARNESS.md.

Usage

/cli-anything:validate <software-path-or-repo>

Arguments

<software-path-or-repo> - Required. Either:
- A local path to the software source code (e.g., /home/user/gimp, ./blender)
- A GitHub repository URL (e.g., https://github.com/GNOME/gimp, github.com/blender/blender)
If a GitHub URL is provided, the agent clones the repo locally first, then works on the local copy.

The software name is derived from the directory name. The agent locates the CLI harness at /root/cli-anything/<software-name>/agent-harness/.

What This Command Validates

1. Directory Structure

agent-harness/cli_anything/<software>/ exists (namespace sub-package)
cli_anything/ has NO __init__.py (PEP 420 namespace package)
<software>/ HAS __init__.py (regular sub-package)
core/, utils/, tests/ subdirectories present
setup.py in agent-harness/ uses find_namespace_packages

2. Required Files

README.md - Installation and usage guide
<software>_cli.py - Main CLI entry point
core/project.py - Project management
core/session.py - Undo/redo
core/export.py - Rendering/export
tests/TEST.md - Test plan and results
tests/test_core.py - Unit tests
tests/test_full_e2e.py - E2E tests
../<SOFTWARE>.md - Software-specific SOP

3. CLI Implementation Standards

Uses Click framework
Has command groups (not flat commands)
Implements --json flag for machine-readable output
Implements --project flag for project file
Has handle_error decorator for consistent error handling
Has REPL mode
Has global session state

4. Core Module Standards

project.py has: create, open, save, info, list_profiles
session.py has: Session class with undo/redo/snapshot
export.py has: render function and EXPORT_PRESETS
All modules have proper docstrings
All functions have type hints

5. Test Standards

TEST.md has both plan (Part 1) and results (Part 2)
Unit tests use synthetic data only
E2E tests use real files
Workflow tests simulate real-world scenarios
test_full_e2e.py has a TestCLISubprocess class
TestCLISubprocess uses _resolve_cli("cli-anything-<software>") (no hardcoded paths)
_resolve_cli prints which backend is used and supports CLI_ANYTHING_FORCE_INSTALLED
Subprocess _run does NOT set cwd (installed commands work from any directory)
All tests pass (100% pass rate)

6. Documentation Standards

README.md has: installation, usage, command reference, examples
<SOFTWARE>.md has: architecture analysis, command map, rendering gap assessment
No duplicate HARNESS.md (should reference plugin's HARNESS.md)
All commands documented with examples

7. PyPI Packaging Standards

setup.py uses find_namespace_packages(include=["cli_anything.*"])
Package name follows cli-anything-<software> convention
Entry point: cli-anything-<software>=cli_anything.<software>.<software>_cli:main
cli_anything/ has NO __init__.py (namespace package rule)
All imports use cli_anything.<software>.* prefix
Dependencies listed in install_requires
Python version requirement specified (>=3.10)

8. Code Quality

No syntax errors
No import errors
Follows PEP 8 style
No hardcoded paths (uses relative paths or config)
Proper error handling (no bare except:)

Validation Report

The command generates a detailed report:

CLI Harness Validation Report
Software: gimp
Path: /root/cli-anything/gimp/agent-harness/cli_anything/gimp

Directory Structure (5/5 checks passed)
Required Files (9/9 files present)
CLI Implementation (7/7 standards met)
Core Modules (5/5 standards met)
Test Standards (10/10 standards met)
Documentation (4/4 standards met)
PyPI Packaging (7/7 standards met)
Code Quality (5/5 checks passed)

Overall: PASS (52/52 checks)

Example

# Validate GIMP CLI
/cli-anything:validate /home/user/gimp

# Validate from GitHub repo
/cli-anything:validate https://github.com/blender/blender

4.3 KiB Raw Permalink Blame History