@danmoisan/drm-copilot-mcp 0.0.6 → 1.0.0

package/resources/scripts/dev_tools/resolve_hard_lock_prompt.py

@@ -1,444 +0,0 @@
-"""Resolve the execute-hard-lock prompt with the plan file path.
-
-Purpose:
-    This helper resolves the active plan file path from the target file,
-    substitutes the ${plan-path} variable into the execute-hard-lock.prompt.md
-    template, prints the result, and attempts to copy it to the clipboard for
-    pasting into Copilot Chat.
-
-Supported variables:
-    - ${plan-path}: Workspace-relative path to the target plan file (forward
-      slashes).
-
-Usage:
-    python resolve_hard_lock_prompt.py --target <path_to_plan_file>
-"""
-
-from __future__ import annotations
-
-import argparse
-import shutil
-import subprocess
-import sys
-from pathlib import Path
-
-from dev_tools.prompt_mode_contract import (
-    build_fallback_reason,
-    resolve_selected_work_mode,
-)
-
-
-def _resolve_template_name(template_kind: str) -> str:
-    """Map the CLI template-kind flag to a concrete template filename.
-
-    Purpose:
-        Keeps filename selection centralized so both root and bundled callers
-        resolve the same prompt asset names for `execute` and `resume` flows.
-
-    Args:
-        template_kind: CLI selector constrained to `execute` or `resume`.
-
-    Returns:
-        str: The prompt filename associated with the requested template kind.
-
-    Side Effects:
-        None.
-    """
-    return (
-        "execute-hard-lock.prompt.md"
-        if template_kind == "execute"
-        else "resume-hard-lock.prompt.md"
-    )
-
-
-def _resolve_template_path(
-    template_name: str,
-    workspace_root: Path,
-    template_root: Path | None,
-) -> tuple[Path | None, tuple[Path, ...]]:
-    """Resolve the first available prompt template path in deterministic order.
-
-    Purpose:
-        Supports bundled extension resources by checking an explicit template
-        root first while preserving the existing workspace `.github/codex`
-        fallback for repo-root usage.
-
-    Args:
-        template_name: Prompt filename to resolve.
-        workspace_root: Workspace root used for repo-local fallback lookup.
-        template_root: Optional explicit template directory to probe first.
-
-    Returns:
-        tuple[Path | None, tuple[Path, ...]]: The selected template path when
-        found, plus the ordered list of checked candidate paths.
-
-    Side Effects:
-        None.
-    """
-    candidates: list[Path] = []
-    if template_root is not None:
-        candidates.append(template_root / template_name)
-    candidates.append(workspace_root / ".github" / "codex" / template_name)
-
-    # Probe the explicit template root before the workspace fallback so bundled
-    # extension resources stay authoritative when they are intentionally passed.
-    for candidate in candidates:
-        if candidate.exists():
-            return candidate, tuple(candidates)
-
-    return None, tuple(candidates)
-
-
-def copy_to_clipboard(text: str) -> bool:
-    """Attempt to copy text to the clipboard using common tools.
-
-    Purpose:
-        Provides cross-platform clipboard support using either pyperclip
-        (if installed) or native system clipboard commands.
-
-    Args:
-        text: The text to copy to the clipboard.
-
-    Returns:
-        True on success, False if no supported clipboard mechanism is found.
-
-    Side Effects:
-        Writes to the system clipboard.
-        Prints error to stderr if pyperclip fails.
-    """
-    try:
-        import pyperclip  # type: ignore[import-untyped]
-    except ImportError:
-        pyperclip = None  # type: ignore[assignment]
-
-    pyperclip_error: Exception | None = None
-    if pyperclip is not None:
-        try:
-            pyperclip.copy(text)
-            return True
-        except Exception as error:  # noqa: BLE001 - CLI top-level error handling
-            pyperclip_error = error
-
-    # Fallback chain: try common clipboard commands across platforms
-    commands: tuple[list[str], ...] = (
-        ["pbcopy"],
-        ["wl-copy"],
-        ["xclip", "-selection", "clipboard"],
-        ["xsel", "--clipboard", "--input"],
-        ["clip"],
-        ["clip.exe"],
-    )
-
-    for command in commands:
-        executable = shutil.which(command[0])
-        if executable is None:
-            continue
-        try:
-            subprocess.run(  # noqa: S603 - static analysis can't verify runtime validation
-                [executable, *command[1:]],
-                input=text,
-                text=True,
-                check=True,
-            )
-            return True
-        except subprocess.CalledProcessError:
-            continue
-
-    if pyperclip_error is not None:
-        print(f"pyperclip copy failed: {pyperclip_error}", file=sys.stderr)
-
-    return False
-
-
-def _try_relative_to_workspace(path: Path, workspace_root: Path) -> Path:
-    """Return path relative to workspace_root when possible.
-
-    Args:
-        path: The path to make relative.
-        workspace_root: The workspace root directory.
-
-    Returns:
-        The relative path if possible, otherwise the original path.
-    """
-    try:
-        return path.resolve().relative_to(workspace_root.resolve())
-    except ValueError:
-        return path
-
-
-def _write_resolved_prompt(
-    resolved_prompt: str,
-    output_path: Path,
-    workspace_root: Path,
-) -> Path:
-    """Persist the resolved prompt text to a UTF-8 file, creating parents.
-
-    Purpose:
-        Provide a deterministic file-write side channel for non-interactive MCP
-        callers that cannot capture stdout from the wrapping ``executeScript``
-        invocation. Mirrors ``--target`` resolution: absolute paths are used
-        verbatim; relative paths resolve against ``workspace_root``.
-
-    Args:
-        resolved_prompt (str): Fully resolved prompt text to persist verbatim.
-        output_path (Path): Path supplied via ``--output`` (absolute or
-            workspace-relative).
-        workspace_root (Path): Active workspace root used to resolve relative
-            output paths against the same base used for ``--target``.
-
-    Returns:
-        Path: Absolute path that was actually written.
-
-    Raises:
-        OSError: When creating the parent directory or writing the file fails.
-
-    Side Effects:
-        Creates missing parent directories and writes the file as UTF-8 text
-        with no BOM.
-    """
-    # Absolute paths are honored verbatim; relative paths resolve against the
-    # workspace root to match how `--target` is resolved.
-    resolved_output = (
-        output_path if output_path.is_absolute() else workspace_root / output_path
-    )
-    # Create any missing parents so MCP callers can target deep directory paths
-    # without pre-staging. `exist_ok=True` keeps repeated writes idempotent.
-    resolved_output.parent.mkdir(parents=True, exist_ok=True)
-    resolved_output.write_text(resolved_prompt, encoding="utf-8")
-    return resolved_output
-
-
-def _resolve_issue_file_for_target(target_path: Path, workspace_root: Path) -> Path:
-    """Resolve the most likely issue.md path for a target plan file.
-
-    Purpose:
-        Hard-lock prompts are usually generated from a plan file located in a
-        feature folder (or a version subfolder like `v2`). This helper selects
-        the nearest deterministic `issue.md` candidate.
-
-    Args:
-        target_path: Path to the target plan file.
-        workspace_root: Workspace root for normalization.
-
-    Returns:
-        Path: Candidate issue.md path to parse for work-mode marker.
-    """
-    relative_target = _try_relative_to_workspace(target_path, workspace_root)
-    plan_dir = relative_target.parent
-    direct_issue = workspace_root / plan_dir / "issue.md"
-    if direct_issue.exists():
-        return direct_issue
-
-    if plan_dir.name.startswith("v") and len(plan_dir.parts) >= 2:
-        parent_issue = workspace_root / plan_dir.parent / "issue.md"
-        if parent_issue.exists():
-            return parent_issue
-
-    return direct_issue
-
-
-def _resolve_work_mode_from_issue(
-    target_path: Path, workspace_root: Path
-) -> tuple[str, str]:
-    """Resolve selected work mode from issue.md with fail-closed behavior.
-
-    Purpose:
-        Enforce deterministic mode selection for prompt templates by reading the
-        persisted issue marker first and failing closed to `full-feature` on
-        missing or malformed data.
-
-    Args:
-        target_path: Target plan file path.
-        workspace_root: Workspace root for path resolution.
-
-    Returns:
-        tuple[str, str]: Selected mode and fallback reason text.
-    """
-    issue_path = _resolve_issue_file_for_target(target_path, workspace_root)
-    if not issue_path.exists():
-        return resolve_selected_work_mode(None), build_fallback_reason(None)
-
-    try:
-        issue_content = issue_path.read_text(encoding="utf-8")
-    except OSError:
-        return (
-            resolve_selected_work_mode(None),
-            "issue.md unreadable; fail closed to full-feature",
-        )
-
-    return resolve_selected_work_mode(issue_content), build_fallback_reason(
-        issue_content
-    )
-
-
-def resolve_prompt(
-    template_content: str,
-    target_path: Path,
-    workspace_root: Path,
-    *,
-    work_mode: str | None = None,
-    fallback_reason: str | None = None,
-) -> str:
-    """Resolve ${plan-path} in the template with the target file path.
-
-    Purpose:
-        Substitutes the ${plan-path} variable with the workspace-relative path
-        to the target file, using forward slashes for consistency.
-
-    Args:
-        template_content: The raw template content containing ${plan-path}.
-        target_path: The path to the plan file.
-        workspace_root: The workspace root directory.
-
-    Returns:
-        The resolved template with ${plan-path} replaced.
-
-    Side Effects:
-        None. Pure function.
-    """
-    relative_target = _try_relative_to_workspace(target_path, workspace_root)
-    plan_path_value = relative_target.as_posix()
-
-    selected_mode, resolved_fallback_reason = _resolve_work_mode_from_issue(
-        target_path,
-        workspace_root,
-    )
-    mode_value = work_mode if work_mode is not None else selected_mode
-    fallback_value = (
-        fallback_reason if fallback_reason is not None else resolved_fallback_reason
-    )
-
-    resolved = template_content.replace("${plan-path}", plan_path_value)
-    resolved = resolved.replace("${work-mode}", mode_value)
-    resolved = resolved.replace("${fallback-reason}", fallback_value)
-
-    return resolved
-
-
-def main() -> int:
-    """Main CLI entry point.
-
-    Returns:
-        Exit code: 0 on success, 1 on error.
-
-    Side Effects:
-        Reads files, writes to clipboard, prints to stdout/stderr.
-    """
-    parser = argparse.ArgumentParser(
-        description="Resolve execute-hard-lock prompt with plan file path"
-    )
-    parser.add_argument(
-        "--target",
-        type=Path,
-        required=True,
-        help="Path to the plan file",
-    )
-    parser.add_argument(
-        "--workspace",
-        type=Path,
-        default=None,
-        help="Workspace root directory (default: current working directory)",
-    )
-    parser.add_argument(
-        "--template-kind",
-        choices=("execute", "resume"),
-        default="execute",
-        help="Hard-lock template kind to resolve.",
-    )
-    parser.add_argument(
-        "--template-root",
-        type=Path,
-        default=None,
-        help="Optional directory containing hard-lock prompt templates.",
-    )
-    parser.add_argument(
-        "--output",
-        type=Path,
-        default=None,
-        help=(
-            "Optional path to write the resolved prompt text as UTF-8. "
-            "Relative paths resolve against --workspace (or cwd when omitted). "
-            "Parent directories are created if missing."
-        ),
-    )
-    parser.add_argument(
-        "--quiet",
-        action="store_true",
-        default=False,
-        help=(
-            "Suppress stdout print and clipboard copy when --output is also "
-            "provided. Using --quiet without --output is a hard error because "
-            "it would produce no user-visible output."
-        ),
-    )
-
-    args = parser.parse_args()
-
-    # --quiet without --output would silently drop the resolved prompt; reject
-    # the combination explicitly so misconfigured callers see the failure.
-    if args.quiet and args.output is None:
-        print(
-            "Error: --quiet requires --output; --quiet alone would suppress all "
-            "output.",
-            file=sys.stderr,
-        )
-        return 1
-
-    workspace_root = args.workspace if args.workspace else Path.cwd()
-    template_name = _resolve_template_name(args.template_kind)
-    template_path, checked_paths = _resolve_template_path(
-        template_name,
-        workspace_root,
-        args.template_root,
-    )
-
-    if template_path is None:
-        checked_paths_text = "\n".join(f"- {candidate}" for candidate in checked_paths)
-        print(
-            "Error: Template "
-            f"'{template_name}' not found. Checked locations:\n{checked_paths_text}",
-            file=sys.stderr,
-        )
-        return 1
-
-    if not args.target.exists():
-        print(f"Error: Target file not found at {args.target}", file=sys.stderr)
-        return 1
-
-    try:
-        template_content = template_path.read_text(encoding="utf-8")
-    except OSError as error:
-        print(f"Error reading template: {error}", file=sys.stderr)
-        return 1
-
-    resolved_prompt = resolve_prompt(template_content, args.target, workspace_root)
-
-    # When --output is provided, persist the resolved prompt so MCP callers
-    # that cannot capture stdout still receive the full content.
-    if args.output is not None:
-        try:
-            _write_resolved_prompt(resolved_prompt, args.output, workspace_root)
-        except OSError as error:
-            print(f"Error writing output file: {error}", file=sys.stderr)
-            return 1
-
-    # --quiet combined with --output suppresses both stdout and clipboard so
-    # non-interactive callers produce only the file side channel.
-    if args.quiet:
-        return 0
-
-    print(resolved_prompt)
-
-    if copy_to_clipboard(resolved_prompt):
-        print("\n✓ Copied to clipboard", file=sys.stderr)
-    else:
-        print(
-            "\n✗ Could not copy to clipboard (no supported mechanism found)",
-            file=sys.stderr,
-        )
-
-    return 0
-
-
-if __name__ == "__main__":
-    sys.exit(main())

package/resources/scripts/dev_tools/validate_orchestration_artifacts.py

@@ -1,246 +0,0 @@
-"""Validate orchestration plan, review, and checkpoint artifacts.
-
-Purpose:
-    Provide the stable CLI entrypoint for deterministic orchestration artifact
-    validation while delegating review- and checkpoint-specific logic to smaller
-    modules that remain under the repository file-size limit.
-"""
-
-from __future__ import annotations
-
-import argparse
-import re
-import sys
-from pathlib import Path
-
-from dev_tools.validate_orchestration_review_artifacts import (
-    validate_code_review_text,
-    validate_feature_audit_text,
-)
-from dev_tools.validate_orchestrator_state import (
-    validate_orchestrator_state_text,
-)
-from dev_tools.validate_policy_audit_artifact import validate_policy_audit_text
-
-PLAN_PHASE_RE = re.compile(r"^### Phase (?P<phase>\d+) — (?P<title>.+)$")
-PLAN_TASK_RE = re.compile(
-    r"^- \[(?P<state>[ xX])\] \[P(?P<phase>\d+)-T(?P<task>\d+)\] (?P<title>.+)$"
-)
-
-
-def _read_text(path: Path) -> str:
-    """Read a UTF-8 artifact from disk.
-
-    Purpose:
-        Centralize file reading for the CLI dispatcher and monkeypatched unit
-        tests.
-
-    Args:
-        path (Path): Artifact path to read.
-
-    Returns:
-        str: UTF-8 text content for the requested artifact.
-
-    Raises:
-        OSError: Raised when the file cannot be read.
-
-    Side Effects:
-        Reads from disk.
-    """
-
-    return path.read_text(encoding="utf-8")
-
-
-def validate_plan_text(text: str) -> list[str]:
-    """Validate canonical atomic-plan structure.
-
-    Purpose:
-        Enforce the repository's required phase and task formatting for atomic
-        execution plans.
-
-    Args:
-        text (str): Full plan document text.
-
-    Returns:
-        list[str]: Validation errors describing any structural contract
-        violations.
-
-    Raises:
-        None.
-
-    Side Effects:
-        None.
-    """
-
-    errors: list[str] = []
-    current_phase: int | None = None
-    seen_phases: list[int] = []
-    expected_task_num: dict[int, int] = {}
-    found_task = False
-
-    # Walk the document in source order so numbering and phase mismatches are
-    # reported against the same line numbers a maintainer sees in the plan.
-    for line_number, line in enumerate(text.splitlines(), start=1):
-        if line.startswith("### Phase "):
-            match = PLAN_PHASE_RE.match(line)
-            if match is None:
-                errors.append(
-                    f"Line {line_number}: phase heading must match "
-                    "`### Phase N — <Title>`."
-                )
-                current_phase = None
-                continue
-            current_phase = int(match.group("phase"))
-            seen_phases.append(current_phase)
-            expected_task_num.setdefault(current_phase, 1)
-            continue
-
-        if line.startswith("- [") and "[P" in line and "-T" in line:
-            found_task = True
-            match = PLAN_TASK_RE.match(line)
-            if match is None:
-                errors.append(
-                    f"Line {line_number}: task line must match "
-                    "`- [ ] [P#-T#] <Title>`."
-                )
-                continue
-            task_phase = int(match.group("phase"))
-            task_num = int(match.group("task"))
-            if current_phase is None:
-                errors.append(
-                    "Line "
-                    f"{line_number}: task appears before a canonical phase "
-                    "heading."
-                )
-                continue
-            if task_phase != current_phase:
-                errors.append(
-                    f"Line {line_number}: task phase P{task_phase} does not match "
-                    f"current phase {current_phase}."
-                )
-            expected = expected_task_num.setdefault(task_phase, 1)
-            if task_num != expected:
-                errors.append(
-                    f"Line {line_number}: expected task number T{expected} for phase "
-                    f"{task_phase}, found T{task_num}."
-                )
-            expected_task_num[task_phase] = max(expected, task_num) + 1
-
-    if not seen_phases:
-        errors.append("Plan does not contain any canonical phase headings.")
-    if not found_task:
-        errors.append("Plan does not contain any canonical task lines.")
-    return errors
-
-
-def build_parser() -> argparse.ArgumentParser:
-    """Create the CLI parser.
-
-    Purpose:
-        Define the stable command-line contract for orchestration artifact
-        validation.
-
-    Args:
-        None.
-
-    Returns:
-        argparse.ArgumentParser: Configured parser for the supported artifact
-        types.
-
-    Raises:
-        None.
-
-    Side Effects:
-        None.
-    """
-
-    parser = argparse.ArgumentParser(
-        description="Validate deterministic orchestration artifacts."
-    )
-    subparsers = parser.add_subparsers(dest="artifact_type", required=True)
-
-    for artifact_type in ("plan", "policy-audit", "code-review", "feature-audit"):
-        artifact_parser = subparsers.add_parser(artifact_type)
-        artifact_parser.add_argument("path")
-
-    state_parser = subparsers.add_parser("orchestrator-state")
-    state_parser.add_argument("path")
-    state_parser.add_argument(
-        "--require-complete",
-        action="store_true",
-        help="Require all tracked statuses to be complete-state safe.",
-    )
-    return parser
-
-
-def _validate_from_args(args: argparse.Namespace) -> list[str]:
-    """Dispatch the requested validator.
-
-    Purpose:
-        Route the parsed CLI request to the correct validator without changing
-        the public artifact-type names accepted by the entrypoint.
-
-    Args:
-        args (argparse.Namespace): Parsed CLI arguments.
-
-    Returns:
-        list[str]: Validation errors produced by the selected validator.
-
-    Raises:
-        None.
-
-    Side Effects:
-        Reads the target artifact from disk.
-    """
-
-    path = Path(args.path)
-    text = _read_text(path)
-    if args.artifact_type == "plan":
-        return validate_plan_text(text)
-    if args.artifact_type == "policy-audit":
-        return validate_policy_audit_text(text)
-    if args.artifact_type == "code-review":
-        return validate_code_review_text(text)
-    if args.artifact_type == "feature-audit":
-        return validate_feature_audit_text(text)
-    if args.artifact_type == "orchestrator-state":
-        return validate_orchestrator_state_text(
-            text, require_complete=bool(args.require_complete)
-        )
-    return [f"Unsupported artifact type: {args.artifact_type}"]
-
-
-def main(argv: list[str] | None = None) -> int:
-    """Run the orchestration-artifact validator CLI.
-
-    Purpose:
-        Execute the stable CLI entrypoint that validates orchestration plans,
-        review artifacts, and checkpoint state.
-
-    Args:
-        argv (list[str] | None): Optional command-line arguments for testing or
-            programmatic invocation.
-
-    Returns:
-        int: Exit code `0` for success and `1` for validation failure.
-
-    Raises:
-        None.
-
-    Side Effects:
-        Reads files from disk and writes validation results to stdout/stderr.
-    """
-
-    parser = build_parser()
-    args = parser.parse_args(argv)
-    errors = _validate_from_args(args)
-    if errors:
-        for error in errors:
-            print(error, file=sys.stderr)
-        return 1
-    print(f"{args.artifact_type} validation passed: {args.path}")
-    return 0
-
-
-if __name__ == "__main__":
-    raise SystemExit(main())