feature-map-cli 1.0.0__py3-none-any.whl

feature_map/commands/install_cmd.py

@@ -0,0 +1,54 @@
+import os
+import shutil
+from pathlib import Path
+
+from feature_map.paths import skill_dir as bundled_skill_dir
+
+
+def _detect_deployed_skill(repo_root: Path) -> Path:
+    candidates = [
+        repo_root / ".agents" / "skills" / "feature-map",
+        repo_root / ".grok" / "skills" / "feature-map",
+    ]
+    for path in candidates:
+        if (path / "SKILL.md").is_file():
+            return path
+    return candidates[0]
+
+
+def run_install(repo_root: Path, as_json: bool = False):
+    shim = repo_root / "bin" / "feature-map"
+    features_dir = repo_root / ".features"
+    config_file = repo_root / ".feature-map.yaml"
+    skill_path = _detect_deployed_skill(repo_root)
+    on_path = shutil.which("feature-map")
+
+    shim_ok = shim.is_file() and os.access(shim, os.X_OK)
+    skill_ok = (skill_path / "SKILL.md").is_file()
+    bundled_ok = (bundled_skill_dir() / "SKILL.md").is_file()
+    features_ok = features_dir.is_dir()
+    config_ok = config_file.is_file()
+
+    payload = {
+        "ok": bundled_ok and (shim_ok or bool(on_path)),
+        "cli_on_path": {"command": "feature-map", "path": on_path, "exists": bool(on_path)},
+        "shim": {"path": str(shim), "exists": shim.is_file(), "executable": shim_ok},
+        "skill": {"path": str(skill_path), "exists": skill_ok},
+        "bundled_skill": {"path": str(bundled_skill_dir()), "exists": bundled_ok},
+        "features_dir": {"path": str(features_dir), "exists": features_ok},
+        "config": {"path": str(config_file), "exists": config_ok},
+    }
+
+    if as_json:
+        return payload
+
+    print("Feature Map install status:")
+    print(f"  feature-map on PATH: {'ok' if on_path else 'missing'} ({on_path or 'not found'})")
+    print(f"  shim: {'ok' if shim_ok else 'missing or not executable'} ({shim})")
+    print(f"  skill: {'ok' if skill_ok else 'missing'} ({skill_path})")
+    print(f"  bundled skill: {'ok' if bundled_ok else 'missing'} ({bundled_skill_dir()})")
+    print(f"  .features/: {'ok' if features_ok else 'missing'} ({features_dir})")
+    print(f"  .feature-map.yaml: {'ok' if config_ok else 'missing'} ({config_file})")
+    if not features_ok:
+        print('Suggestion: run "feature-map init" to bootstrap this repository.')
+    return payload

feature_map/commands/list_cmd.py

@@ -0,0 +1,37 @@
+from datetime import datetime
+from pathlib import Path
+
+from feature_map.loader import list_map_files
+
+
+def run_list(features_dir: Path, as_json: bool = False):
+    files = list_map_files(features_dir)
+    slugs = [path.stem for path in files]
+
+    if as_json:
+        items = []
+        for path in files:
+            mtime = datetime.fromtimestamp(path.stat().st_mtime).isoformat()
+            apps_count = 0
+            try:
+                import yaml as yaml_lib
+
+                data = yaml_lib.safe_load(path.read_text(encoding="utf-8")) or {}
+                apps = data.get("apps")
+                if isinstance(apps, list):
+                    apps_count = len(apps)
+                elif isinstance(apps, dict):
+                    apps_count = len(apps)
+            except Exception:
+                pass
+            items.append(
+                {
+                    "slug": path.stem,
+                    "file": path.name,
+                    "mtime": mtime,
+                    "apps_count": apps_count,
+                }
+            )
+        return {"ok": True, "count": len(items), "features": items}
+
+    return {"features": slugs}

feature_map/commands/search_cmd.py

@@ -0,0 +1,21 @@
+from pathlib import Path
+
+from feature_map.text_index import search_maps
+
+
+def run_search(features_dir: Path, query: str, as_json: bool = False):
+    results = search_maps(features_dir, query)
+    payload = {"ok": True, "query": query, "count": len(results), "results": results}
+
+    if as_json:
+        return payload
+
+    if not results:
+        print(f"No features matched '{query}'.")
+        return payload
+
+    for item in results:
+        print(item["feature"])
+        for snippet in item.get("snippets", []):
+            print(f"  {snippet}")
+    return payload

feature_map/commands/show_cmd.py

@@ -0,0 +1,34 @@
+from pathlib import Path
+
+import yaml
+
+from feature_map.loader import load_map, load_map_text, resolve_map_path
+
+
+def run_show(features_dir: Path, name: str, section=None, as_json: bool = False):
+    path = resolve_map_path(features_dir, name)
+    if as_json:
+        data = load_map(path)
+        if section:
+            if section not in data:
+                from feature_map.errors import CliError
+
+                raise CliError(
+                    f'Section "{section}" not found in {path.stem}.',
+                    suggestion=f"Available keys: {', '.join(sorted(data.keys()))}",
+                )
+            return {"ok": True, "feature": path.stem, "section": section, "data": data[section]}
+        return {"ok": True, "feature": path.stem, "data": data}
+
+    if section:
+        data = load_map(path)
+        if section not in data:
+            from feature_map.errors import CliError
+
+            raise CliError(
+                f'Section "{section}" not found in {path.stem}.',
+                suggestion=f"Available keys: {', '.join(sorted(data.keys()))}",
+            )
+        return yaml.dump({section: data[section]}, sort_keys=False)
+
+    return load_map_text(path)

feature_map/commands/stats_cmd.py

@@ -0,0 +1,85 @@
+import re
+from collections import Counter
+from pathlib import Path
+from typing import Optional
+
+import yaml
+
+from feature_map.loader import all_slugs, extract_related_slug, list_map_files
+from feature_map.validate import RECOMMENDED_KEYS, REQUIRED_KEYS
+
+
+def normalize_app_name(app) -> Optional[str]:
+    if not isinstance(app, str):
+        return None
+    app = app.strip()
+    if not app or app.startswith("("):
+        return None
+    match = re.match(r'^["\']?([a-zA-Z0-9_-]+)', app)
+    if match:
+        return match.group(1)
+    return None
+
+
+def run_stats(features_dir: Path, as_json: bool = False):
+    slugs = all_slugs(features_dir)
+    apps_counter = Counter()
+    missing_sections = 0
+    broken_links = 0
+    parse_failures = 0
+
+    for path in list_map_files(features_dir):
+        try:
+            data = yaml.safe_load(path.read_text(encoding="utf-8")) or {}
+        except yaml.YAMLError:
+            parse_failures += 1
+            missing_sections += len(REQUIRED_KEYS) + len(RECOMMENDED_KEYS)
+            continue
+
+        if not isinstance(data, dict):
+            continue
+
+        for key in REQUIRED_KEYS + RECOMMENDED_KEYS:
+            if key not in data or data[key] in (None, "", []):
+                missing_sections += 1
+
+        apps = data.get("apps")
+        if isinstance(apps, list):
+            for app in apps:
+                name = normalize_app_name(app)
+                if name:
+                    apps_counter[name] += 1
+        elif isinstance(apps, dict):
+            for app in apps:
+                name = normalize_app_name(app)
+                if name:
+                    apps_counter[name] += 1
+
+        related = data.get("related_features") or []
+        if isinstance(related, list):
+            for entry in related:
+                slug = extract_related_slug(entry)
+                if slug and slug not in slugs:
+                    broken_links += 1
+
+    payload = {
+        "ok": True,
+        "map_count": len(list(list_map_files(features_dir))),
+        "parse_failures": parse_failures,
+        "missing_sections": missing_sections,
+        "broken_related_features": broken_links,
+        "maps_per_app": dict(sorted(apps_counter.items())),
+    }
+
+    if as_json:
+        return payload
+
+    print(f"Maps: {payload['map_count']}")
+    print(f"Parse failures: {payload['parse_failures']}")
+    print(f"Missing sections: {payload['missing_sections']}")
+    print(f"Broken related_features: {payload['broken_related_features']}")
+    if apps_counter:
+        print("Maps per app:")
+        for app, count in sorted(apps_counter.items()):
+            print(f"  {app}: {count}")
+    return payload

feature_map/commands/validate_cmd.py

@@ -0,0 +1,59 @@
+from pathlib import Path
+
+from feature_map.loader import all_slugs, list_map_files
+from feature_map.validate import validate_map_file
+
+
+def run_validate(features_dir: Path, strict: bool = False, as_json: bool = False):
+    slugs = all_slugs(features_dir)
+    all_errors = []
+    all_warnings = []
+    map_results = []
+
+    for path in list_map_files(features_dir):
+        errors, warnings = validate_map_file(path, slugs, strict=strict)
+        all_errors.extend(errors)
+        all_warnings.extend(warnings)
+        map_results.append(
+            {
+                "file": path.name,
+                "slug": path.stem,
+                "errors": errors,
+                "warnings": warnings,
+                "ok": len(errors) == 0,
+            }
+        )
+
+    result = {
+        "ok": len(all_errors) == 0 and (len(all_warnings) == 0 if strict else True),
+        "map_count": len(map_results),
+        "error_count": len(all_errors),
+        "warning_count": len(all_warnings),
+        "maps": map_results,
+        "errors": all_errors,
+        "warnings": all_warnings,
+    }
+
+    if not as_json:
+        if all_errors:
+            for err in all_errors:
+                print(f"ERROR: {err}")
+        if all_warnings:
+            for warn in all_warnings:
+                print(f"WARNING: {warn}")
+        if not all_errors and not all_warnings:
+            print(f"Validated {len(map_results)} feature maps: all passed.")
+        elif not all_errors:
+            print(
+                f"Validated {len(map_results)} feature maps: "
+                f"{len(all_warnings)} warning(s), 0 error(s)."
+            )
+
+    exit_code = 0
+    if all_errors:
+        exit_code = 2 if strict else 1
+    elif strict and all_warnings:
+        exit_code = 2
+
+    result["exit_code"] = exit_code
+    return result, exit_code

feature_map/config.py

@@ -0,0 +1,24 @@
+from pathlib import Path
+
+import yaml
+
+DEFAULT_APPS = []
+DEFAULT_REQUIRED_SECTIONS = ["purpose", "entry_points"]
+DEFAULT_FEATURES_DIR = ".features"
+
+
+def load_config(repo_root: Path) -> dict:
+    config_path = repo_root / ".feature-map.yaml"
+    config = {
+        "features_dir": DEFAULT_FEATURES_DIR,
+        "apps": list(DEFAULT_APPS),
+        "required_sections": list(DEFAULT_REQUIRED_SECTIONS),
+    }
+    if config_path.is_file():
+        with config_path.open(encoding="utf-8") as handle:
+            loaded = yaml.safe_load(handle) or {}
+        if isinstance(loaded, dict):
+            config.update(loaded)
+    if not isinstance(config.get("apps"), list):
+        config["apps"] = list(DEFAULT_APPS)
+    return config

feature_map/discover.py

@@ -0,0 +1,59 @@
+import subprocess
+from pathlib import Path
+
+from feature_map.errors import FeaturesNotFoundError
+
+
+def _is_git_root(path: Path) -> bool:
+    return (path / ".git").exists()
+
+
+def find_repo_root(start: Path) -> Path:
+    start = start.resolve()
+    try:
+        result = subprocess.run(
+            ["git", "rev-parse", "--show-toplevel"],
+            capture_output=True,
+            text=True,
+            check=True,
+            cwd=start,
+        )
+        toplevel = result.stdout.strip()
+        if toplevel:
+            return Path(toplevel)
+    except (subprocess.CalledProcessError, FileNotFoundError):
+        pass
+
+    current = start
+    while current != current.parent:
+        if _is_git_root(current):
+            return current
+        current = current.parent
+    return start
+
+
+def find_features_dir(start: Path) -> Path:
+    start = start.resolve()
+    repo_root = find_repo_root(start)
+
+    if _is_git_root(repo_root):
+        root_candidate = repo_root / ".features"
+        if root_candidate.is_dir():
+            return root_candidate
+
+    current = start
+    while True:
+        candidate = current / ".features"
+        if candidate.is_dir():
+            return candidate
+        if _is_git_root(current):
+            break
+        if current.parent == current:
+            break
+        current = current.parent
+
+    root_candidate = repo_root / ".features"
+    if root_candidate.is_dir():
+        return root_candidate
+
+    raise FeaturesNotFoundError()

feature_map/errors.py

@@ -0,0 +1,17 @@
+class FeaturesNotFoundError(Exception):
+    def __init__(self, message=None, suggestion=None):
+        self.message = message or (
+            "No .features/ found. Run `feature-map init` from the repo root."
+        )
+        self.suggestion = suggestion or (
+            'Run "feature-map init" to scaffold .features/, the agent skill, and a bin shim.'
+        )
+        super().__init__(self.message)
+
+
+class CliError(Exception):
+    def __init__(self, message, suggestion=None, exit_code=1):
+        self.message = message
+        self.suggestion = suggestion
+        self.exit_code = exit_code
+        super().__init__(message)

feature_map/graph.py

@@ -0,0 +1,79 @@
+from pathlib import Path
+from typing import Dict, List, Optional, Set
+
+import yaml
+
+from feature_map.loader import extract_related_slug, list_map_files
+
+
+def build_graph(features_dir: Path) -> Dict[str, List[str]]:
+    graph: Dict[str, List[str]] = {}
+    for path in list_map_files(features_dir):
+        slug = path.stem
+        graph.setdefault(slug, [])
+        try:
+            data = yaml.safe_load(path.read_text(encoding="utf-8")) or {}
+        except yaml.YAMLError:
+            continue
+        related = data.get("related_features") or []
+        if not isinstance(related, list):
+            continue
+        for entry in related:
+            target = extract_related_slug(entry)
+            if target:
+                graph[slug].append(target)
+    return graph
+
+
+def graph_data(
+    features_dir: Path,
+    root: Optional[str] = None,
+) -> dict:
+    full_graph = build_graph(features_dir)
+    nodes: Set[str] = set()
+    edges = []
+
+    if root:
+        root = root.replace(".yaml", "")
+        visited = set()
+        stack = [root]
+
+        def visit(node):
+            if node in visited:
+                return
+            visited.add(node)
+            nodes.add(node)
+            for target in full_graph.get(node, []):
+                edges.append({"from": node, "to": target})
+                visit(target)
+
+        visit(root)
+        for edge in edges:
+            nodes.add(edge["to"])
+    else:
+        nodes = set(full_graph.keys())
+        for source, targets in full_graph.items():
+            nodes.add(source)
+            for target in targets:
+                nodes.add(target)
+                edges.append({"from": source, "to": target})
+
+    return {
+        "nodes": sorted(nodes),
+        "edges": edges,
+    }
+
+
+def format_mermaid(data: dict) -> str:
+    lines = ["graph LR"]
+    for edge in data.get("edges", []):
+        lines.append(f"  {edge['from']} --> {edge['to']}")
+    return "\n".join(lines) + "\n"
+
+
+def format_dot(data: dict) -> str:
+    lines = ["digraph feature_map {"]
+    for edge in data.get("edges", []):
+        lines.append(f'  "{edge["from"]}" -> "{edge["to"]}";')
+    lines.append("}")
+    return "\n".join(lines) + "\n"

feature_map/loader.py

@@ -0,0 +1,62 @@
+from __future__ import annotations
+
+import re
+from pathlib import Path
+from typing import Optional
+
+import yaml
+
+from feature_map.errors import CliError
+
+
+def normalize_slug(name: str) -> str:
+    return name.lower().replace(" ", "_").replace("-", "_")
+
+
+def list_map_files(features_dir: Path):
+    return sorted(features_dir.glob("*.yaml"))
+
+
+def resolve_map_path(features_dir: Path, name: str) -> Path:
+    slug = normalize_slug(name)
+    exact = features_dir / f"{slug}.yaml"
+    if exact.exists():
+        return exact
+    fallback = features_dir / f"{name}.yaml"
+    if fallback.exists():
+        return fallback
+    for path in features_dir.glob("*.yaml"):
+        if path.stem == slug or path.stem == name:
+            return path
+    raise CliError(
+        f'Feature "{name}" not found.',
+        suggestion='Run "feature-map list" to see available features.',
+    )
+
+
+def load_map(path: Path) -> dict:
+    text = path.read_text(encoding="utf-8")
+    try:
+        data = yaml.safe_load(text)
+    except yaml.YAMLError as exc:
+        raise CliError(f"Failed to parse {path.name}: {exc}") from exc
+    if not isinstance(data, dict):
+        raise CliError(f"Feature map {path.name} must be a YAML mapping.")
+    return data
+
+
+def load_map_text(path: Path) -> str:
+    return path.read_text(encoding="utf-8")
+
+
+def extract_related_slug(entry) -> Optional[str]:
+    if not isinstance(entry, str):
+        return None
+    match = re.match(r'^["\']?([a-zA-Z0-9_-]+)', entry.strip())
+    if not match:
+        return None
+    return normalize_slug(match.group(1))
+
+
+def all_slugs(features_dir: Path) -> set[str]:
+    return {path.stem for path in list_map_files(features_dir)}

feature_map/output.py

@@ -0,0 +1,54 @@
+import json
+import sys
+
+import yaml
+
+from feature_map.errors import CliError, FeaturesNotFoundError
+
+
+def emit(data, as_json=False, stream=None):
+    stream = stream or sys.stdout
+    if as_json:
+        json.dump(data, stream, indent=2, default=str)
+        stream.write("\n")
+    elif isinstance(data, str):
+        stream.write(data)
+        if not data.endswith("\n"):
+            stream.write("\n")
+    elif isinstance(data, dict) and "features" in data and len(data) == 1:
+        yaml.dump(data, stream, default_flow_style=False)
+    else:
+        yaml.dump(data, stream, default_flow_style=False, sort_keys=False)
+
+
+def emit_error(error, as_json=False, stream=None):
+    stream = stream or (sys.stdout if as_json else sys.stderr)
+    if isinstance(error, CliError):
+        message = error.message
+        suggestion = error.suggestion
+        exit_code = error.exit_code
+    elif isinstance(error, FeaturesNotFoundError):
+        message = error.message
+        suggestion = error.suggestion
+        exit_code = 1
+    else:
+        message = str(error)
+        suggestion = None
+        exit_code = 1
+
+    if as_json:
+        payload = {
+            "ok": False,
+            "error": message,
+            "exit_code": exit_code,
+        }
+        if suggestion:
+            payload["suggestion"] = suggestion
+        json.dump(payload, stream, indent=2)
+        stream.write("\n")
+    else:
+        stream.write(f"Error: {message}\n")
+        if suggestion:
+            stream.write(f"Suggestion: {suggestion}\n")
+    return exit_code
+