bmad-module-skill-forge 1.2.0 → 1.4.0

package/src/shared/scripts/skf-detect-language.py

@@ -0,0 +1,277 @@
+# /// script
+# requires-python = ">=3.9"
+# dependencies = []
+# ///
+"""SKF Detect Language — deterministic primary-language detection from a flat file tree.
+
+Single source of truth for the language-detection rule table that
+skf-brief-skill step-02 §3 applies. The rule walk is purely deterministic:
+manifest-file presence first (Cargo.toml → rust, package.json → js/ts,
+etc.), then extension-frequency fallback. Moving it into a shared script
+saves ~150-250 tokens per workflow invocation and removes a quiet drift
+seam — the JS-vs-TS disambiguation in particular benefits from being
+co-located with a deterministic rule rather than restated in prose.
+
+Detection rules (apply in order, first match wins):
+
+  1. package.json (with optional tsconfig.json companion):
+       tsconfig.json present → typescript (high)
+       tsconfig.json absent  → javascript (high)
+  2. Cargo.toml          → rust (high)
+  3. pyproject.toml | setup.py | setup.cfg → python (high)
+  4. go.mod              → go (high)
+  5. pom.xml             → java (high)
+  6. build.gradle.kts    → kotlin (high)
+  7. build.gradle (Groovy) — check tree:
+       src/main/kotlin/  → kotlin (medium)
+       else              → java (medium)
+  8. *.csproj | *.sln    → csharp (high)
+  9. Gemfile             → ruby (high)
+ 10. Extension-frequency fallback over the full tree.
+       dominant extension >= 50% of code files → that language (medium)
+       no clear winner                        → unknown (low)
+
+CLI:
+  echo '{"tree": ["path1", "path2", ...]}' | uv run skf-detect-language.py
+  uv run skf-detect-language.py --json '{"tree": [...]}'
+
+Input (JSON object on stdin or via --json):
+  tree — list of repo-relative file paths (required, non-empty)
+
+Output (JSON on stdout):
+  language          — javascript | typescript | rust | python | go
+                       | java | kotlin | csharp | ruby | swift | php
+                       | unknown
+  confidence        — "high" | "medium" | "low"
+  detection_source  — human-readable string naming what fired (manifest
+                       basename, extension share, etc.)
+  fallback_to_extension_frequency — bool (true when rule 10 fired)
+
+Exit codes:
+  0 — recommendation produced (even when language is "unknown")
+  2 — internal error (bad JSON input, IO failure)
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from collections import Counter
+from typing import Any
+
+# Manifest basenames the rule table checks. Kept tight — tree-wide pattern
+# matches (e.g. *.csproj) are handled separately to avoid false positives
+# from generated artifacts under build/ or dist/.
+_MANIFEST_RULES: list[tuple[str, str, str]] = [
+    # (basename, language, detection_source)
+    ("Cargo.toml", "rust", "Cargo.toml present"),
+    ("pyproject.toml", "python", "pyproject.toml present"),
+    ("setup.py", "python", "setup.py present"),
+    ("setup.cfg", "python", "setup.cfg present"),
+    ("go.mod", "go", "go.mod present"),
+    ("pom.xml", "java", "pom.xml present"),
+    ("build.gradle.kts", "kotlin", "build.gradle.kts present"),
+    ("Gemfile", "ruby", "Gemfile present"),
+]
+
+# Glob-style suffix rules — matches anywhere in the tree. csproj/sln are
+# C#-specific. Ordered so the first hit wins.
+_SUFFIX_RULES: list[tuple[str, str, str]] = [
+    (".csproj", "csharp", ".csproj project file present"),
+    (".sln", "csharp", ".sln solution file present"),
+]
+
+# Extension → language for the frequency fallback. Tightly limited to source
+# extensions; keeping this small avoids the fallback being skewed by
+# auto-generated assets (.json, .md, .yaml, etc.).
+_EXTENSION_TO_LANGUAGE: dict[str, str] = {
+    ".py": "python",
+    ".js": "javascript",
+    ".jsx": "javascript",
+    ".mjs": "javascript",
+    ".cjs": "javascript",
+    ".ts": "typescript",
+    ".tsx": "typescript",
+    ".rs": "rust",
+    ".go": "go",
+    ".java": "java",
+    ".kt": "kotlin",
+    ".kts": "kotlin",
+    ".cs": "csharp",
+    ".rb": "ruby",
+    ".swift": "swift",
+    ".php": "php",
+}
+
+_DOMINANCE_THRESHOLD = 0.50
+
+
+def _die(message: str, code: int = 2) -> None:
+    sys.stderr.write(f"skf-detect-language: {message}\n")
+    sys.exit(code)
+
+
+def _basename(path: str) -> str:
+    return path.rsplit("/", 1)[-1]
+
+
+def _has_basename(tree: list[str], basename: str) -> bool:
+    return any(_basename(p) == basename for p in tree)
+
+
+def _has_suffix(tree: list[str], suffix: str) -> bool:
+    return any(p.endswith(suffix) for p in tree)
+
+
+def _has_path_segment(tree: list[str], segment: str) -> bool:
+    """True when any path contains the given segment (e.g. 'src/main/kotlin/')."""
+    return any(segment in p for p in tree)
+
+
+def _extension(path: str) -> str:
+    """Return the lowercased file extension including the leading dot, or empty string."""
+    base = _basename(path)
+    if "." not in base or base.startswith("."):
+        return ""
+    return "." + base.rsplit(".", 1)[-1].lower()
+
+
+def _frequency_fallback(tree: list[str]) -> dict[str, Any]:
+    """Score the tree by source-extension frequency. Returns the result envelope."""
+    counter: Counter[str] = Counter()
+    for path in tree:
+        ext = _extension(path)
+        if ext in _EXTENSION_TO_LANGUAGE:
+            counter[ext] += 1
+
+    total = sum(counter.values())
+    if total == 0:
+        return {
+            "language": "unknown",
+            "confidence": "low",
+            "detection_source": "no recognized source extensions in tree",
+            "fallback_to_extension_frequency": True,
+        }
+
+    # Largest-share extension wins. Ties (e.g. equal counts) broken by
+    # the natural order of _EXTENSION_TO_LANGUAGE — Counter.most_common
+    # is stable for equal counts and we don't rely on which loses.
+    top_ext, top_count = counter.most_common(1)[0]
+    share = top_count / total
+    language = _EXTENSION_TO_LANGUAGE[top_ext]
+
+    if share >= _DOMINANCE_THRESHOLD:
+        confidence = "medium"
+        source = f"extension frequency: {top_ext} is {top_count}/{total} of source files ({share:.0%})"
+    else:
+        confidence = "low"
+        source = f"no dominant extension: top is {top_ext} at {top_count}/{total} ({share:.0%}, threshold {int(_DOMINANCE_THRESHOLD * 100)}%)"
+        # Still surface the best-guess language; caller / step-03 §4 lets
+        # the user override on low confidence.
+    return {
+        "language": language,
+        "confidence": confidence,
+        "detection_source": source,
+        "fallback_to_extension_frequency": True,
+    }
+
+
+def detect(payload: dict[str, Any]) -> dict[str, Any]:
+    """Apply the documented rule walk. Always returns a recommendation."""
+    tree = payload.get("tree")
+    if not isinstance(tree, list):
+        _die("payload.tree must be an array of repo-relative file paths")
+    if len(tree) == 0:
+        _die("payload.tree must be non-empty")
+
+    # Rule 1 — package.json (with tsconfig.json disambiguation)
+    if _has_basename(tree, "package.json"):
+        if _has_basename(tree, "tsconfig.json"):
+            return {
+                "language": "typescript",
+                "confidence": "high",
+                "detection_source": "package.json + tsconfig.json present",
+                "fallback_to_extension_frequency": False,
+            }
+        return {
+            "language": "javascript",
+            "confidence": "high",
+            "detection_source": "package.json present (no tsconfig.json)",
+            "fallback_to_extension_frequency": False,
+        }
+
+    # Rules 2-6 — single-basename manifests walked in priority order. Note
+    # that build.gradle (Groovy DSL) is NOT in this table; it requires
+    # tree-aware Java/Kotlin disambiguation handled in Rule 7b below.
+    # build.gradle.kts IS in the table (returns kotlin high) and fires
+    # here before the Groovy variant is considered.
+    for basename, language, source in _MANIFEST_RULES:
+        if _has_basename(tree, basename):
+            return {
+                "language": language,
+                "confidence": "high",
+                "detection_source": source,
+                "fallback_to_extension_frequency": False,
+            }
+
+    # Rule 7b — build.gradle (Groovy DSL): check src/main/kotlin/ to disambiguate.
+    # This rule sits *after* the basename loop because build.gradle.kts is
+    # already covered by the loop and we don't want it to pre-empt that match.
+    if _has_basename(tree, "build.gradle"):
+        if _has_path_segment(tree, "src/main/kotlin/"):
+            return {
+                "language": "kotlin",
+                "confidence": "medium",
+                "detection_source": "build.gradle (Groovy) + src/main/kotlin/ present",
+                "fallback_to_extension_frequency": False,
+            }
+        return {
+            "language": "java",
+            "confidence": "medium",
+            "detection_source": "build.gradle (Groovy) present without src/main/kotlin/ — defaulting to java",
+            "fallback_to_extension_frequency": False,
+        }
+
+    # Rules 8-9 — suffix-based (csproj, sln)
+    for suffix, language, source in _SUFFIX_RULES:
+        if _has_suffix(tree, suffix):
+            return {
+                "language": language,
+                "confidence": "high",
+                "detection_source": source,
+                "fallback_to_extension_frequency": False,
+            }
+
+    # Rule 10 — extension-frequency fallback
+    return _frequency_fallback(tree)
+
+
+def _parse_argv(argv: list[str]) -> dict:
+    parser = argparse.ArgumentParser(
+        description="Detect primary language from a flat repo file tree by walking the documented rule table.",
+    )
+    parser.add_argument("--json", help="JSON payload (alternative to stdin)")
+    args = parser.parse_args(argv)
+    raw = args.json if args.json is not None else sys.stdin.read()
+    if not raw or not raw.strip():
+        _die("empty input (expected JSON payload on stdin or via --json)")
+    try:
+        payload = json.loads(raw)
+    except json.JSONDecodeError as e:
+        _die(f"invalid JSON input: {e}")
+    if not isinstance(payload, dict):
+        _die("payload must be a JSON object")
+    return payload
+
+
+def main(argv: list[str]) -> int:
+    payload = _parse_argv(argv)
+    result = detect(payload)
+    json.dump(result, sys.stdout, ensure_ascii=False)
+    sys.stdout.write("\n")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv[1:]))

package/src/shared/scripts/skf-detect-workspaces.py

@@ -0,0 +1,427 @@
+# /// script
+# requires-python = ">=3.11"
+# dependencies = ["pyyaml"]
+# ///
+"""SKF Detect Workspaces — pure detector for monorepo / multi-package layouts.
+
+Takes a JSON payload on stdin describing a target repo's file tree plus the
+contents of a small set of root manifests, and returns whether a workspace
+layout is present, which manifest kind drives it, and the list of resolved
+workspaces. The helper does NO file I/O — the caller (typically
+skf-brief-skill step-02 §1b) fetches files via `gh api` / local filesystem
+and pipes the relevant content in.
+
+Detection runs in priority order; the first matching detector wins:
+
+  1. npm-workspaces       package.json has `workspaces: [...]` or `{packages: [...]}`
+  2. pnpm-workspaces      pnpm-workspace.yaml exists with a `packages:` list
+  3. lerna                lerna.json exists (`packages` field optional, defaults to `packages/*`)
+  4. cargo-workspace      Cargo.toml has `[workspace]` with `members = [...]`
+  5. python-multi-package multiple pyproject.toml under packages/* or apps/*
+  6. generic-folders      apps/, packages/, libs/, or code/ each with subdirs
+                          containing a recognisable manifest
+
+Glob members (`packages/*`, `apps/*`, etc.) are resolved against the supplied
+file tree; only directories whose recognisable manifest is present in the tree
+become workspaces. A detector that finds zero non-excluded matches falls
+through to the next detector instead of returning is_monorepo: true with an
+empty list.
+
+Input JSON shape (stdin):
+
+  {
+    "tree": ["package.json", "packages/foo/package.json", "packages/foo/src/index.js", ...],
+    "manifests": {
+      "package.json":        "<raw text>",
+      "Cargo.toml":          "<raw text>",
+      "pnpm-workspace.yaml": "<raw text>",
+      "lerna.json":          "<raw text>"
+    }
+  }
+
+  - `tree` is a flat list of repository-relative file paths (POSIX separators).
+    Per-workspace child manifests (e.g. `packages/foo/package.json`) MUST appear
+    here for glob resolution; their contents are optional.
+  - `manifests` is a dict keyed by repository-relative path; only root-level
+    manifests must be supplied. Per-workspace manifest contents may be
+    included to populate the workspace `name` field, but absence is fine
+    (the path basename is used as a fallback).
+
+Output JSON shape (stdout):
+
+  {
+    "is_monorepo":   true | false,
+    "manifest_kind": "npm-workspaces" | "pnpm-workspaces" | "lerna"
+                   | "cargo-workspace" | "python-multi-package"
+                   | "generic-folders" | null,
+    "workspaces":    [
+      {"name": "foo", "path": "packages/foo", "manifest": "packages/foo/package.json"},
+      ...
+    ],
+    "warnings":      ["..."]
+  }
+
+Exit codes:
+
+  0  success (regardless of is_monorepo value)
+  1  payload error (malformed top-level JSON shape)
+  2  stdin / argparse / JSON-decode error
+"""
+
+from __future__ import annotations
+
+import argparse
+import fnmatch
+import json
+import re
+import sys
+import tomllib
+from typing import Optional
+
+
+GENERIC_PARENTS = ("apps", "packages", "libs", "code")
+RECOGNISED_MANIFESTS = (
+    "package.json",
+    "Cargo.toml",
+    "pyproject.toml",
+    "setup.py",
+    "go.mod",
+    "build.gradle",
+    "build.gradle.kts",
+    "pom.xml",
+)
+
+
+# --------------------------------------------------------------------------
+# Helpers
+# --------------------------------------------------------------------------
+
+
+def _normalise_path(path: str) -> str:
+    """Strip leading './' and trailing '/' so comparisons are stable."""
+    while path.startswith("./"):
+        path = path[2:]
+    return path.rstrip("/")
+
+
+def _match_globs(tree: set[str], globs: list[str]) -> list[str]:
+    """Resolve workspace globs against the tree.
+
+    Returns the sorted list of *directory paths* that have at least one matching
+    manifest under them. Patterns starting with `!` are exclusions applied after
+    the inclusion pass. Brace expansion is not supported (npm/pnpm rarely use
+    it in published configs); a literal pattern without `*` is treated as a
+    literal directory path.
+    """
+    includes: list[str] = []
+    excludes: list[str] = []
+    for raw in globs:
+        if not isinstance(raw, str) or not raw.strip():
+            continue
+        cleaned = _normalise_path(raw.strip())
+        if cleaned.startswith("!"):
+            excludes.append(cleaned[1:])
+        else:
+            includes.append(cleaned)
+
+    candidate_dirs: set[str] = set()
+    for pat in includes:
+        if "*" in pat:
+            for path in tree:
+                # match the directory portion of every file path against the glob
+                parts = path.split("/")
+                for depth in range(1, len(parts)):
+                    candidate = "/".join(parts[:depth])
+                    if fnmatch.fnmatchcase(candidate, pat):
+                        candidate_dirs.add(candidate)
+        else:
+            # literal directory; include only if the tree contains a manifest under it
+            candidate_dirs.add(pat)
+
+    # Apply excludes
+    survivors: set[str] = set()
+    for cand in candidate_dirs:
+        if any(fnmatch.fnmatchcase(cand, ex) or cand == ex for ex in excludes):
+            continue
+        survivors.add(cand)
+
+    return sorted(survivors)
+
+
+def _find_workspace_manifest(workspace_path: str, tree: set[str]) -> Optional[str]:
+    """Return the first recognised manifest under `workspace_path`, or None."""
+    for manifest in RECOGNISED_MANIFESTS:
+        candidate = f"{workspace_path}/{manifest}"
+        if candidate in tree:
+            return candidate
+    return None
+
+
+def _read_workspace_name(manifest_path: str, manifests: dict[str, str], fallback: str) -> str:
+    """Extract a sensible name from a workspace's manifest.
+
+    Best-effort: returns the manifest's declared package name when parseable,
+    otherwise the directory basename.
+    """
+    content = manifests.get(manifest_path)
+    if content is None:
+        return fallback
+    if manifest_path.endswith("package.json"):
+        try:
+            data = json.loads(content)
+            name = data.get("name")
+            if isinstance(name, str) and name:
+                return name
+        except (json.JSONDecodeError, AttributeError):
+            pass
+    elif manifest_path.endswith("Cargo.toml"):
+        try:
+            data = tomllib.loads(content)
+            name = data.get("package", {}).get("name")
+            if isinstance(name, str) and name:
+                return name
+        except tomllib.TOMLDecodeError:
+            pass
+    elif manifest_path.endswith("pyproject.toml"):
+        try:
+            data = tomllib.loads(content)
+            name = data.get("project", {}).get("name")
+            if isinstance(name, str) and name:
+                return name
+        except tomllib.TOMLDecodeError:
+            pass
+    return fallback
+
+
+def _build_workspaces(
+    workspace_dirs: list[str],
+    tree: set[str],
+    manifests: dict[str, str],
+) -> list[dict]:
+    """Resolve each workspace dir to its manifest + name, drop dirs without a manifest."""
+    out: list[dict] = []
+    for ws_path in workspace_dirs:
+        manifest = _find_workspace_manifest(ws_path, tree)
+        if manifest is None:
+            continue
+        fallback_name = ws_path.rsplit("/", 1)[-1] or ws_path
+        name = _read_workspace_name(manifest, manifests, fallback_name)
+        out.append({"name": name, "path": ws_path, "manifest": manifest})
+    return out
+
+
+# --------------------------------------------------------------------------
+# Detectors
+# --------------------------------------------------------------------------
+
+
+def detect_npm_workspaces(
+    tree: set[str], manifests: dict[str, str], warnings: list[str]
+) -> Optional[list[dict]]:
+    content = manifests.get("package.json")
+    if content is None:
+        return None
+    try:
+        data = json.loads(content)
+    except json.JSONDecodeError as e:
+        warnings.append(f"package.json JSON parse error: {e}")
+        return None
+    if not isinstance(data, dict):
+        return None
+    ws = data.get("workspaces")
+    if ws is None:
+        return None
+    if isinstance(ws, dict):
+        ws = ws.get("packages", [])
+    if not isinstance(ws, list) or not ws:
+        return None
+    dirs = _match_globs(tree, ws)
+    return _build_workspaces(dirs, tree, manifests)
+
+
+def detect_pnpm_workspaces(
+    tree: set[str], manifests: dict[str, str], warnings: list[str]
+) -> Optional[list[dict]]:
+    content = manifests.get("pnpm-workspace.yaml")
+    if content is None:
+        return None
+    try:
+        import yaml  # local import keeps top-level cheap when YAML is unused
+    except ImportError:
+        warnings.append("pyyaml not available — pnpm-workspace.yaml not parsed")
+        return None
+    try:
+        data = yaml.safe_load(content)
+    except yaml.YAMLError as e:
+        warnings.append(f"pnpm-workspace.yaml parse error: {e}")
+        return None
+    if not isinstance(data, dict):
+        return None
+    pkgs = data.get("packages")
+    if not isinstance(pkgs, list) or not pkgs:
+        return None
+    dirs = _match_globs(tree, pkgs)
+    return _build_workspaces(dirs, tree, manifests)
+
+
+def detect_lerna(
+    tree: set[str], manifests: dict[str, str], warnings: list[str]
+) -> Optional[list[dict]]:
+    content = manifests.get("lerna.json")
+    if content is None:
+        return None
+    try:
+        data = json.loads(content)
+    except json.JSONDecodeError as e:
+        warnings.append(f"lerna.json JSON parse error: {e}")
+        return None
+    if not isinstance(data, dict):
+        return None
+    pkgs = data.get("packages")
+    if pkgs is None:
+        return None
+    if not isinstance(pkgs, list) or not pkgs:
+        return None
+    dirs = _match_globs(tree, pkgs)
+    return _build_workspaces(dirs, tree, manifests)
+
+
+def detect_cargo_workspace(
+    tree: set[str], manifests: dict[str, str], warnings: list[str]
+) -> Optional[list[dict]]:
+    content = manifests.get("Cargo.toml")
+    if content is None:
+        return None
+    try:
+        data = tomllib.loads(content)
+    except tomllib.TOMLDecodeError as e:
+        warnings.append(f"Cargo.toml parse error: {e}")
+        return None
+    workspace = data.get("workspace")
+    if not isinstance(workspace, dict):
+        return None
+    members = workspace.get("members")
+    if not isinstance(members, list) or not members:
+        return None
+    excludes = workspace.get("exclude", [])
+    patterns = list(members) + [f"!{e}" for e in excludes if isinstance(e, str)]
+    dirs = _match_globs(tree, patterns)
+    return _build_workspaces(dirs, tree, manifests)
+
+
+def detect_python_multi_package(
+    tree: set[str], manifests: dict[str, str], warnings: list[str]
+) -> Optional[list[dict]]:
+    candidates: list[str] = []
+    for path in tree:
+        if not path.endswith("/pyproject.toml"):
+            continue
+        parent = path[: -len("/pyproject.toml")]
+        # match `packages/<x>/pyproject.toml`, `apps/<x>/pyproject.toml`, or `libs/<x>/pyproject.toml`
+        if re.match(r"^(packages|apps|libs)/[^/]+$", parent):
+            candidates.append(parent)
+    if len(candidates) < 2:
+        return None
+    return _build_workspaces(sorted(set(candidates)), tree, manifests)
+
+
+def detect_generic_folders(
+    tree: set[str], manifests: dict[str, str], warnings: list[str]
+) -> Optional[list[dict]]:
+    """Last-resort: ≥2 manifested subdirs under any combination of apps/, packages/, libs/, code/.
+
+    Accumulates across all GENERIC_PARENTS — a repo with one manifested child under apps/
+    and one under packages/ counts as a 2-workspace monorepo. Earlier detectors (npm, pnpm,
+    cargo) take priority for repos with a root workspace manifest.
+    """
+    discovered: list[str] = []
+    for parent in GENERIC_PARENTS:
+        children: set[str] = set()
+        for path in tree:
+            if not path.startswith(parent + "/"):
+                continue
+            parts = path.split("/")
+            if len(parts) < 3:
+                continue  # need at least parent/child/file
+            children.add(f"{parent}/{parts[1]}")
+        for child in children:
+            if _find_workspace_manifest(child, tree) is not None:
+                discovered.append(child)
+    if len(discovered) < 2:
+        return None
+    return _build_workspaces(sorted(set(discovered)), tree, manifests)
+
+
+DETECTORS: list[tuple[str, callable]] = [
+    ("npm-workspaces",       detect_npm_workspaces),
+    ("pnpm-workspaces",      detect_pnpm_workspaces),
+    ("lerna",                detect_lerna),
+    ("cargo-workspace",      detect_cargo_workspace),
+    ("python-multi-package", detect_python_multi_package),
+    ("generic-folders",      detect_generic_folders),
+]
+
+
+# --------------------------------------------------------------------------
+# Entry point
+# --------------------------------------------------------------------------
+
+
+def detect(payload: dict) -> dict:
+    """Pure detection — the CLI wraps this with stdin/stdout I/O and exit-code mapping."""
+    tree_raw = payload.get("tree")
+    manifests = payload.get("manifests")
+    warnings: list[str] = []
+    if not isinstance(tree_raw, list):
+        return {"_payload_error": "missing or non-list 'tree' field"}
+    if not isinstance(manifests, dict):
+        return {"_payload_error": "missing or non-dict 'manifests' field"}
+    tree: set[str] = {_normalise_path(p) for p in tree_raw if isinstance(p, str) and p.strip()}
+
+    for kind, detector in DETECTORS:
+        result = detector(tree, manifests, warnings)
+        if result and len(result) >= 1:
+            return {
+                "is_monorepo":   True,
+                "manifest_kind": kind,
+                "workspaces":    result,
+                "warnings":      warnings,
+            }
+
+    return {
+        "is_monorepo":   False,
+        "manifest_kind": None,
+        "workspaces":    [],
+        "warnings":      warnings,
+    }
+
+
+def main(argv: Optional[list[str]] = None) -> int:
+    parser = argparse.ArgumentParser(description="Detect monorepo / workspace layouts from a tree + manifests payload.")
+    parser.add_argument("--json", help="Inline JSON payload (otherwise read from stdin).")
+    args = parser.parse_args(argv)
+
+    raw = args.json
+    if raw is None:
+        raw = sys.stdin.read()
+    if not raw.strip():
+        print(json.dumps({"error": "empty input"}), file=sys.stderr)
+        return 2
+
+    try:
+        payload = json.loads(raw)
+    except json.JSONDecodeError as e:
+        print(json.dumps({"error": f"json decode error: {e}"}), file=sys.stderr)
+        return 2
+
+    result = detect(payload)
+    if "_payload_error" in result:
+        print(json.dumps({"error": result["_payload_error"]}), file=sys.stderr)
+        return 1
+
+    print(json.dumps(result, separators=(",", ":")))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())