CLI-Anything/opencode-commands/cli-anything-validate.md

description

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

cli-anything-validate Command

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

Target software: $1

CRITICAL: Read HARNESS.md First

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

Arguments

• $1 is the software path or repo URL (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, clone the repo locally first, then work 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)