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

feature_map/__init__.py

@@ -0,0 +1,3 @@
+from feature_map._version import __version__
+
+__all__ = ["__version__"]

feature_map/__main__.py

@@ -0,0 +1,3 @@
+from feature_map.cli import main
+
+raise SystemExit(main())

feature_map/_version.py

@@ -0,0 +1 @@
+__version__ = "1.0.0"

feature_map/bootstrap.py

@@ -0,0 +1,189 @@
+"""Phase 2 repo bootstrap: deploy skill, config, AGENTS.md, and optional shim."""
+
+from __future__ import annotations
+
+import shutil
+from pathlib import Path
+
+from feature_map.paths import skill_dir as bundled_skill_dir
+
+AGENTS_MARKER = "<!-- feature-map:start -->"
+AGENTS_END = "<!-- feature-map:end -->"
+LEGACY_AGENTS_MARKERS = (
+    ("<!-- featuremap:start -->", "<!-- featuremap:end -->"),
+)
+
+AGENTS_BLOCK = f"""{AGENTS_MARKER}
+## Feature Map
+
+**ALWAYS** use Feature Map before feature work, debugging, PRDs, or plans.
+Do not implement from a cold grep when a map exists.
+
+```bash
+./bin/feature-map list
+./bin/feature-map search <keyword>
+./bin/feature-map find <path-fragment>
+./bin/feature-map <feature-name>
+```
+
+Maps in `.features/*.yaml` are the authoritative cross-app architecture source.
+Keep them dense: fields, not essays.
+
+If `list` is empty or search/find miss the area you are about to change,
+**scour the existing code and author maps first** (skill:
+`feature-map` → `references/existing-repos.md`). Cluster by user-visible
+capability, not by file. Prefer `entry_points` that exist on disk, then
+run `feature-map validate` and `feature-map check`.
+{AGENTS_END}
+"""
+
+SHIM_SCRIPT = """#!/usr/bin/env bash
+set -euo pipefail
+SELF="$(cd "$(dirname "$0")" && pwd)/$(basename "$0")"
+ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+
+if [ -x "$ROOT/.venv/bin/feature-map" ]; then
+  exec "$ROOT/.venv/bin/feature-map" "$@"
+fi
+
+# Global install, but not this shim (bin/ may be on PATH).
+if command -v feature-map >/dev/null 2>&1; then
+  CAND="$(command -v feature-map)"
+  CAND_ABS="$(cd "$(dirname "$CAND")" && pwd)/$(basename "$CAND")"
+  if [ "$CAND_ABS" != "$SELF" ]; then
+    exec "$CAND" "$@"
+  fi
+fi
+
+if python3 -c "import feature_map" >/dev/null 2>&1; then
+  exec python3 -m feature_map "$@"
+fi
+
+echo "feature-map is not installed. Try: pip install feature-map-cli" >&2
+exit 1
+"""
+
+DEFAULT_CONFIG = """# Feature Map CLI configuration
+features_dir: .features
+apps: []
+required_sections:
+  - purpose
+  - entry_points
+min_cli_version: "1.0.0"
+"""
+
+
+def detect_skill_parent(repo_root: Path) -> Path:
+    agents = repo_root / ".agents" / "skills"
+    grok = repo_root / ".grok" / "skills"
+    if grok.exists() and not agents.exists():
+        return grok
+    return agents
+
+
+def copy_skill(dest_parent: Path, force: bool = False) -> Path:
+    source = bundled_skill_dir()
+    dest = dest_parent / "feature-map"
+    dest.mkdir(parents=True, exist_ok=True)
+
+    if not source.is_dir():
+        raise FileNotFoundError(f"Bundled skill not found at {source}")
+
+    for path in source.rglob("*"):
+        if not path.is_file():
+            continue
+        relative = path.relative_to(source)
+        target = dest / relative
+        if target.exists() and not force:
+            continue
+        target.parent.mkdir(parents=True, exist_ok=True)
+        shutil.copy2(path, target)
+    return dest
+
+
+def write_config(repo_root: Path, force: bool = False) -> Path:
+    target = repo_root / ".feature-map.yaml"
+    if target.exists() and not force:
+        return target
+    target.write_text(DEFAULT_CONFIG, encoding="utf-8")
+    return target
+
+
+def write_shim(repo_root: Path, force: bool = False) -> Path:
+    bin_dir = repo_root / "bin"
+    bin_dir.mkdir(parents=True, exist_ok=True)
+    target = bin_dir / "feature-map"
+    if target.exists() and not force:
+        return target
+    target.write_text(SHIM_SCRIPT, encoding="utf-8")
+    target.chmod(target.stat().st_mode | 0o111)
+    return target
+
+
+def _replace_marked_block(text: str, block: str):
+    pairs = ((AGENTS_MARKER, AGENTS_END),) + LEGACY_AGENTS_MARKERS
+    for start_tok, end_tok in pairs:
+        if start_tok in text and end_tok in text:
+            start = text.index(start_tok)
+            end = text.index(end_tok) + len(end_tok)
+            new_text = text[:start] + block.rstrip() + text[end:]
+            if not new_text.endswith("\n"):
+                new_text += "\n"
+            return new_text
+        if start_tok in text:
+            return text
+    return None
+
+
+def append_agents_snippet(repo_root: Path) -> Path:
+    target = repo_root / "AGENTS.md"
+    block = AGENTS_BLOCK.strip() + "\n"
+    if target.exists():
+        text = target.read_text(encoding="utf-8")
+        replaced = _replace_marked_block(text, block)
+        if replaced is not None:
+            if replaced != text:
+                target.write_text(replaced, encoding="utf-8")
+            return target
+        if not text.endswith("\n"):
+            text += "\n"
+        target.write_text(text + "\n" + block, encoding="utf-8")
+    else:
+        target.write_text("# Agent instructions\n\n" + block, encoding="utf-8")
+    return target
+
+
+def ensure_features_dir(repo_root: Path, features_dir_name: str = ".features") -> Path:
+    features_dir = repo_root / features_dir_name
+    features_dir.mkdir(parents=True, exist_ok=True)
+    gitkeep = features_dir / ".gitkeep"
+    if not any(features_dir.glob("*.yaml")) and not gitkeep.exists():
+        gitkeep.write_text("", encoding="utf-8")
+    return features_dir
+
+
+def bootstrap_repo(
+    repo_root: Path,
+    *,
+    upgrade_skill: bool = False,
+    agents: bool = True,
+    shim: bool = True,
+    force: bool = False,
+) -> dict:
+    features_dir = ensure_features_dir(repo_root)
+    skill_parent = detect_skill_parent(repo_root)
+    skill_path = copy_skill(skill_parent, force=upgrade_skill or force)
+    config_path = write_config(repo_root, force=False)
+    shim_path = write_shim(repo_root, force=force) if shim else None
+    agents_path = append_agents_snippet(repo_root) if agents else None
+
+    return {
+        "ok": True,
+        "repo_root": str(repo_root),
+        "features_dir": str(features_dir),
+        "skill": str(skill_path),
+        "config": str(config_path),
+        "shim": str(shim_path) if shim_path else None,
+        "agents": str(agents_path) if agents_path else None,
+        "upgraded_skill": bool(upgrade_skill or force),
+    }

feature_map/cli.py

@@ -0,0 +1,273 @@
+import argparse
+import sys
+from pathlib import Path
+
+from feature_map._version import __version__
+from feature_map.commands.check_cmd import run_check
+from feature_map.commands.find_cmd import run_find
+from feature_map.commands.graph_cmd import run_graph
+from feature_map.commands.impact_cmd import run_impact
+from feature_map.commands.init_cmd import run_bootstrap, run_init_map
+from feature_map.commands.install_cmd import run_install
+from feature_map.commands.list_cmd import run_list
+from feature_map.commands.search_cmd import run_search
+from feature_map.commands.show_cmd import run_show
+from feature_map.commands.stats_cmd import run_stats
+from feature_map.commands.validate_cmd import run_validate
+from feature_map.config import load_config
+from feature_map.discover import find_features_dir, find_repo_root
+from feature_map.errors import CliError, FeaturesNotFoundError
+from feature_map.output import emit, emit_error
+
+COMMANDS = {
+    "list",
+    "show",
+    "search",
+    "find",
+    "graph",
+    "validate",
+    "check",
+    "impact",
+    "stats",
+    "init",
+    "install",
+}
+
+OPTIONAL_FEATURES_COMMANDS = {"init", "install"}
+
+
+def build_parser():
+    parser = argparse.ArgumentParser(
+        prog="feature-map",
+        description="Feature Map CLI — cross-app architecture research tool",
+    )
+    parser.add_argument("--json", action="store_true", help="Machine-readable JSON output")
+    parser.add_argument("--version", action="version", version=__version__)
+
+    subparsers = parser.add_subparsers(dest="command")
+
+    subparsers.add_parser("list", help="List all feature slugs")
+    subparsers.add_parser("install", help="Verify install and repo setup")
+
+    show_parser = subparsers.add_parser("show", help="Show a feature map")
+    show_parser.add_argument("name", help="Feature slug")
+    show_parser.add_argument("--section", help="Show a single top-level section")
+
+    search_parser = subparsers.add_parser("search", help="Full-text search across maps")
+    search_parser.add_argument("query", help="Search query")
+
+    find_parser = subparsers.add_parser("find", help="Find maps referencing a path fragment")
+    find_parser.add_argument("fragment", help="Path or file fragment")
+
+    graph_parser = subparsers.add_parser("graph", help="Related-features graph")
+    graph_parser.add_argument("name", nargs="?", help="Optional root feature for subgraph")
+    graph_parser.add_argument(
+        "--format",
+        choices=["mermaid", "json", "dot"],
+        default="mermaid",
+        help="Output format",
+    )
+
+    validate_parser = subparsers.add_parser("validate", help="Validate feature maps")
+    validate_parser.add_argument(
+        "--strict",
+        action="store_true",
+        help="Treat warnings as failures (exit 2)",
+    )
+
+    subparsers.add_parser("check", help="Check entry-point path staleness")
+
+    impact_parser = subparsers.add_parser("impact", help="Features referencing a file")
+    impact_parser.add_argument("file", help="File path fragment")
+    impact_parser.add_argument(
+        "--transitive",
+        action="store_true",
+        help="Include transitive related_features",
+    )
+
+    subparsers.add_parser("stats", help="Coverage statistics")
+
+    init_parser = subparsers.add_parser(
+        "init",
+        help="Bootstrap this repo, or scaffold a feature map when <name> is given",
+    )
+    init_parser.add_argument(
+        "name",
+        nargs="?",
+        help="Feature slug to scaffold (omit to bootstrap the repo)",
+    )
+    init_parser.add_argument("--force", action="store_true", help="Overwrite existing files")
+    init_parser.add_argument(
+        "--upgrade-skill",
+        action="store_true",
+        help="Refresh the agent skill from this package version",
+    )
+    init_parser.add_argument(
+        "--no-agents",
+        dest="agents",
+        action="store_false",
+        help="Do not write or update AGENTS.md",
+    )
+    init_parser.add_argument(
+        "--no-shim",
+        dest="shim",
+        action="store_false",
+        help="Do not write bin/feature-map",
+    )
+    init_parser.set_defaults(agents=True, shim=True)
+
+    parser.add_argument(
+        "bare_name",
+        nargs="?",
+        help="Feature name (show alias when no subcommand)",
+    )
+
+    return parser
+
+
+def resolve_context(optional=False):
+    start = Path.cwd()
+    repo_root = find_repo_root(start)
+    config = load_config(repo_root)
+    try:
+        features_dir = find_features_dir(start)
+    except FeaturesNotFoundError:
+        if optional:
+            features_dir = repo_root / config.get("features_dir", ".features")
+        else:
+            raise
+    return features_dir, repo_root, config
+
+
+def dispatch(args):
+    command = args.command
+    as_json = args.json
+    optional = command in OPTIONAL_FEATURES_COMMANDS
+    features_dir, repo_root, config = resolve_context(optional=optional)
+
+    if command is None and args.bare_name:
+        if args.bare_name in COMMANDS:
+            parser = build_parser()
+            parser.error(f'command "{args.bare_name}" requires explicit subcommand syntax')
+        command = "show"
+        args.name = args.bare_name
+
+    if command == "list":
+        return 0, run_list(features_dir, as_json=as_json)
+
+    if command == "install":
+        return 0, run_install(repo_root, as_json=as_json)
+
+    if command == "show":
+        return 0, run_show(features_dir, args.name, section=args.section, as_json=as_json)
+
+    if command == "search":
+        return 0, run_search(features_dir, args.query, as_json=as_json)
+
+    if command == "find":
+        return 0, run_find(features_dir, args.fragment, as_json=as_json)
+
+    if command == "graph":
+        result = run_graph(
+            features_dir,
+            name=getattr(args, "name", None),
+            fmt=getattr(args, "format", "mermaid"),
+            as_json=as_json,
+        )
+        return 0, result
+
+    if command == "validate":
+        result, exit_code = run_validate(features_dir, strict=args.strict, as_json=as_json)
+        return exit_code, result
+
+    if command == "check":
+        return 0, run_check(features_dir, repo_root, config.get("apps", []), as_json=as_json)
+
+    if command == "impact":
+        return 0, run_impact(
+            features_dir,
+            args.file,
+            transitive=args.transitive,
+            as_json=as_json,
+        )
+
+    if command == "stats":
+        return 0, run_stats(features_dir, as_json=as_json)
+
+    if command == "init":
+        if getattr(args, "name", None):
+            return 0, run_init_map(
+                features_dir,
+                args.name,
+                force=args.force,
+                as_json=as_json,
+            )
+        return 0, run_bootstrap(
+            repo_root,
+            upgrade_skill=args.upgrade_skill,
+            agents=args.agents,
+            shim=args.shim,
+            force=args.force,
+            as_json=as_json,
+        )
+
+    parser = build_parser()
+    parser.print_help()
+    return 1, None
+
+
+def preprocess_argv(argv):
+    argv = list(argv)
+    if not argv:
+        return argv
+
+    json_flag = False
+    cleaned = []
+    for arg in argv:
+        if arg == "--json":
+            json_flag = True
+        else:
+            cleaned.append(arg)
+    if json_flag:
+        cleaned.insert(0, "--json")
+    argv = cleaned
+
+    idx = 0
+    while idx < len(argv) and argv[idx].startswith("-"):
+        idx += 1
+    if idx < len(argv) and argv[idx] not in COMMANDS:
+        argv.insert(idx, "show")
+    return argv
+
+
+def main(argv=None):
+    argv = preprocess_argv(argv or sys.argv[1:])
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    as_json = args.json
+
+    if args.command is None and not args.bare_name:
+        parser.print_help()
+        return 1
+
+    try:
+        exit_code, result = dispatch(args)
+        if result is not None:
+            graph_json = (
+                args.command == "graph" and getattr(args, "format", None) == "json"
+            )
+            if as_json or graph_json:
+                emit(result, as_json=True)
+            elif isinstance(result, str):
+                sys.stdout.write(result)
+                if not result.endswith("\n"):
+                    sys.stdout.write("\n")
+            elif args.command == "list":
+                emit(result, as_json=False)
+        return exit_code
+    except (CliError, FeaturesNotFoundError) as exc:
+        return emit_error(exc, as_json=as_json)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

feature_map/commands/check_cmd.py

@@ -0,0 +1,23 @@
+from pathlib import Path
+
+from feature_map.path_extract import check_paths
+
+
+def run_check(features_dir: Path, repo_root: Path, apps, as_json: bool = False):
+    issues = check_paths(features_dir, repo_root, apps)
+    payload = {
+        "ok": True,
+        "issue_count": len(issues),
+        "issues": issues,
+    }
+
+    if as_json:
+        return payload
+
+    if not issues:
+        print("No stale paths detected.")
+        return payload
+
+    for issue in issues:
+        print(f"{issue['feature']}: missing {issue['path']}")
+    return payload

feature_map/commands/find_cmd.py

@@ -0,0 +1,36 @@
+from pathlib import Path
+
+from feature_map.loader import list_map_files
+
+
+def run_find(features_dir: Path, fragment: str, as_json: bool = False):
+    results = []
+    fragment_lower = fragment.lower()
+
+    for path in list_map_files(features_dir):
+        matches = []
+        for line_no, line in enumerate(path.read_text(encoding="utf-8").splitlines(), 1):
+            if fragment_lower in line.lower():
+                matches.append({"line": line_no, "text": line.strip()})
+        if matches:
+            results.append({"feature": path.stem, "matches": matches})
+
+    payload = {
+        "ok": True,
+        "fragment": fragment,
+        "count": len(results),
+        "results": results,
+    }
+
+    if as_json:
+        return payload
+
+    if not results:
+        print(f"No features reference '{fragment}'.")
+        return payload
+
+    for item in results:
+        print(item["feature"])
+        for match in item["matches"][:5]:
+            print(f"  L{match['line']}: {match['text']}")
+    return payload

feature_map/commands/graph_cmd.py

@@ -0,0 +1,18 @@
+from feature_map.graph import format_dot, format_mermaid, graph_data
+
+
+def run_graph(features_dir, name=None, fmt="mermaid", as_json=False):
+    data = graph_data(features_dir, root=name)
+
+    if fmt == "json" or as_json:
+        return {"ok": True, **data}
+
+    if fmt == "dot":
+        return format_dot(data)
+
+    if fmt == "mermaid":
+        return format_mermaid(data)
+
+    from feature_map.errors import CliError
+
+    raise CliError(f'Unknown graph format "{fmt}".', suggestion="Use mermaid, json, or dot.")

feature_map/commands/impact_cmd.py

@@ -0,0 +1,55 @@
+from pathlib import Path
+
+from feature_map.graph import build_graph
+from feature_map.loader import list_map_files
+
+
+def run_impact(
+    features_dir: Path,
+    file_fragment: str,
+    transitive: bool = False,
+    as_json: bool = False,
+):
+    fragment_lower = file_fragment.lower()
+    direct = []
+
+    for path in list_map_files(features_dir):
+        text = path.read_text(encoding="utf-8")
+        if fragment_lower in text.lower():
+            direct.append(path.stem)
+
+    affected = set(direct)
+    if transitive:
+        graph = build_graph(features_dir)
+        reverse = {}
+        for source, targets in graph.items():
+            for target in targets:
+                reverse.setdefault(target, []).append(source)
+
+        stack = list(direct)
+        while stack:
+            node = stack.pop()
+            for parent in reverse.get(node, []):
+                if parent not in affected:
+                    affected.add(parent)
+                    stack.append(parent)
+
+    results = sorted(affected)
+    payload = {
+        "ok": True,
+        "file": file_fragment,
+        "transitive": transitive,
+        "count": len(results),
+        "features": results,
+    }
+
+    if as_json:
+        return payload
+
+    if not results:
+        print(f"No features reference '{file_fragment}'.")
+        return payload
+
+    for feature in results:
+        print(feature)
+    return payload

feature_map/commands/init_cmd.py

@@ -0,0 +1,72 @@
+from pathlib import Path
+
+from feature_map.bootstrap import bootstrap_repo, ensure_features_dir
+from feature_map.errors import CliError
+from feature_map.loader import normalize_slug
+from feature_map.paths import template_path
+
+
+def run_init_map(features_dir: Path, name: str, force: bool = False, as_json: bool = False):
+    slug = normalize_slug(name)
+    if not slug:
+        raise CliError(f'Invalid feature name "{name}".')
+
+    features_dir.mkdir(parents=True, exist_ok=True)
+    target = features_dir / f"{slug}.yaml"
+    if target.exists() and not force:
+        raise CliError(
+            f"Feature map already exists: {target.name}",
+            suggestion="Use --force to overwrite.",
+        )
+
+    tpl = template_path()
+    if not tpl.is_file():
+        raise CliError("Template not found in the feature-map package.")
+
+    content = tpl.read_text(encoding="utf-8")
+    content = content.replace("{{feature_name}}", slug)
+    content = content.replace("{{FEATURE_TITLE}}", name.replace("_", " ").title())
+
+    target.write_text(content, encoding="utf-8")
+    payload = {"ok": True, "feature": slug, "path": str(target)}
+
+    if as_json:
+        return payload
+
+    print(f"Created {target}")
+    return payload
+
+
+def run_bootstrap(
+    repo_root: Path,
+    *,
+    upgrade_skill: bool = False,
+    agents: bool = True,
+    shim: bool = True,
+    force: bool = False,
+    as_json: bool = False,
+):
+    payload = bootstrap_repo(
+        repo_root,
+        upgrade_skill=upgrade_skill,
+        agents=agents,
+        shim=shim,
+        force=force,
+    )
+    if as_json:
+        return payload
+
+    print("Initialized Feature Map in this repository:")
+    print(f"  .features/: {payload['features_dir']}")
+    print(f"  skill: {payload['skill']}")
+    print(f"  config: {payload['config']}")
+    if payload.get("shim"):
+        print(f"  shim: {payload['shim']}")
+    if payload.get("agents"):
+        print(f"  AGENTS.md: {payload['agents']}")
+    return payload
+
+
+# Backward-compatible alias used by older call sites / tests
+def run_init(features_dir: Path, name: str, force: bool = False, as_json: bool = False):
+    return run_init_map(features_dir, name, force=force, as_json=as_json)