specced 0.1.0__py3-none-any.whl

specced/__init__.py

@@ -0,0 +1,11 @@
+"""specced — install a reusable, interview-driven agentic coding setup into any repo.
+
+The Python package is the *deterministic* half of specced: it scaffolds the
+proof-loop engine, project-scoped agents, managed guide blocks, and the
+Layer-2 structure (constitution, rules, code-review, mcp, Makefile vocabulary).
+
+The *intelligent* half — the interview that fills in project-specific content —
+lives in the Claude Code plugin under ``plugin/`` and drives this CLI.
+"""
+
+__version__ = "0.1.0"

specced/_paths.py

@@ -0,0 +1,11 @@
+"""Resource-path resolution shared by scaffold and detect (avoids an import cycle)."""
+
+from __future__ import annotations
+
+from importlib.resources import files
+from pathlib import Path
+
+
+def templates_dir() -> Path:
+    """Path to the bundled templates directory (works for editable + wheel)."""
+    return Path(str(files("specced"))) / "templates"

specced/cli.py

@@ -0,0 +1,178 @@
+"""specced command-line interface.
+
+Thin wrapper over :mod:`specced.scaffold`. Every command prints a JSON result to
+stdout so the interview agent (or a human) can read exactly what happened.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+from typing import Any
+
+from . import scaffold
+
+
+def _repo_root(args: argparse.Namespace) -> Path:
+    start = Path(args.repo_root).resolve() if args.repo_root else Path.cwd()
+    return scaffold.discover_repo_root(start)
+
+
+def _emit(payload: dict[str, Any]) -> None:
+    print(json.dumps(payload, indent=2))
+
+
+def cmd_init(args: argparse.Namespace) -> int:
+    _emit(
+        scaffold.init_repo(
+            _repo_root(args),
+            minimal=args.minimal,
+            force=args.force,
+            format_cmd=args.format_cmd,
+            preset=args.preset,
+        )
+    )
+    return 0
+
+
+def cmd_detect(args: argparse.Namespace) -> int:
+    _emit(scaffold.detect_repo(_repo_root(args)))
+    return 0
+
+
+def cmd_presets(args: argparse.Namespace) -> int:
+    _emit({"presets": scaffold.list_presets()})
+    return 0
+
+
+def cmd_add_mcp(args: argparse.Namespace) -> int:
+    result = scaffold.compose_mcp(_repo_root(args), args.names, force=args.force)
+    _emit(result)
+    return 1 if result["unknown"] else 0
+
+
+def cmd_add_skill(args: argparse.Namespace) -> int:
+    result = scaffold.add_skill(_repo_root(args), args.name, force=args.force)
+    _emit(result)
+    return 0 if result.get("ok") else 1
+
+
+def cmd_list_skills(args: argparse.Namespace) -> int:
+    _emit({"library_skills": scaffold.list_library_skills()})
+    return 0
+
+
+def cmd_sync(args: argparse.Namespace) -> int:
+    _emit(scaffold.sync(_repo_root(args)))
+    return 0
+
+
+def cmd_doctor(args: argparse.Namespace) -> int:
+    result = scaffold.doctor(_repo_root(args))
+    _emit(result)
+    return 0 if result["ok"] else 1
+
+
+def cmd_status(args: argparse.Namespace) -> int:
+    _emit(scaffold.status(_repo_root(args)))
+    return 0
+
+
+def cmd_version(args: argparse.Namespace) -> int:
+    _emit({"specced": scaffold.SPECCED_VERSION, "engine": scaffold.engine_version()})
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="specced",
+        description="Install and manage the specced agentic coding setup in a repo.",
+    )
+
+    common = argparse.ArgumentParser(add_help=False)
+    common.add_argument(
+        "--repo-root",
+        default=None,
+        help="Path inside the target repo. Defaults to the current directory.",
+    )
+
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    p_init = sub.add_parser(
+        "init", parents=[common], help="Install the setup into the repo (idempotent)."
+    )
+    p_init.add_argument(
+        "--preset",
+        default=None,
+        help="Stack preset name, or 'auto' to detect (see: specced presets).",
+    )
+    p_init.add_argument(
+        "--minimal",
+        action="store_true",
+        help="Install only the engine, agents, managed blocks, and config "
+        "(skip Layer-2 content files so the interview can author them).",
+    )
+    p_init.add_argument("--force", action="store_true", help="Overwrite existing files.")
+    p_init.add_argument(
+        "--format-cmd",
+        default=None,
+        help="Format+lint command for the Stop hook (default: 'make fmt lint').",
+    )
+    p_init.set_defaults(func=cmd_init)
+
+    p_detect = sub.add_parser(
+        "detect", parents=[common], help="Inspect the repo and report stack signals (JSON)."
+    )
+    p_detect.set_defaults(func=cmd_detect)
+
+    p_presets = sub.add_parser("presets", help="List available stack presets.")
+    p_presets.set_defaults(func=cmd_presets)
+
+    p_mcp = sub.add_parser(
+        "add-mcp", parents=[common], help="Add MCP servers to .mcp.json from the catalog."
+    )
+    p_mcp.add_argument(
+        "names", nargs="+", help="Server names (see 'mcp_catalog' in: specced status)."
+    )
+    p_mcp.add_argument("--force", action="store_true", help="Overwrite an existing server entry.")
+    p_mcp.set_defaults(func=cmd_add_mcp)
+
+    p_add = sub.add_parser(
+        "add-skill", parents=[common], help="Install a domain skill from the library."
+    )
+    p_add.add_argument("name", help="Library skill name (see: specced list-skills).")
+    p_add.add_argument("--force", action="store_true", help="Replace if already present.")
+    p_add.set_defaults(func=cmd_add_skill)
+
+    p_list = sub.add_parser("list-skills", help="List available library skills.")
+    p_list.set_defaults(func=cmd_list_skills)
+
+    p_sync = sub.add_parser(
+        "sync",
+        parents=[common],
+        help="Refresh engine + agents + managed blocks to this specced version.",
+    )
+    p_sync.set_defaults(func=cmd_sync)
+
+    p_doctor = sub.add_parser("doctor", parents=[common], help="Verify the setup is consistent.")
+    p_doctor.set_defaults(func=cmd_doctor)
+
+    p_status = sub.add_parser(
+        "status", parents=[common], help="Show installed components and config."
+    )
+    p_status.set_defaults(func=cmd_status)
+
+    p_version = sub.add_parser("version", help="Print specced and engine versions.")
+    p_version.set_defaults(func=cmd_version)
+
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    return int(args.func(args))
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

specced/detect.py

@@ -0,0 +1,299 @@
+"""Stack detection for the bootstrap interview.
+
+Pure, dependency-free inspection of a repo: languages, package managers, tracks,
+candidate verification commands, data/infra signals, and existing conventions.
+The interview reads this so it can *confirm* detections instead of asking blind,
+and ``specced init --preset auto`` uses it to pick a preset.
+
+Kept stdlib-only (text + JSON scans, no tomllib) to honor requires-python >= 3.10.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from pathlib import Path
+from typing import Any
+
+from ._paths import templates_dir
+
+TRACK_DIRS = (
+    "backend",
+    "frontend",
+    "ml",
+    "infra",
+    "services",
+    "api",
+    "web",
+    "app",
+    "apps",
+    "packages",
+    "server",
+    "client",
+    "mobile",
+)
+
+DB_IMAGES = (
+    "postgres",
+    "mysql",
+    "mariadb",
+    "redis",
+    "qdrant",
+    "mongo",
+    "elasticsearch",
+    "clickhouse",
+)
+
+
+def _read(path: Path) -> str:
+    try:
+        return path.read_text(encoding="utf-8")
+    except OSError:
+        return ""
+
+
+def _load_json(path: Path) -> dict[str, Any]:
+    try:
+        return json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return {}
+
+
+def _manifest_dirs(root: Path) -> list[Path]:
+    """Root plus immediate track subdirs — enough to see a backend/+frontend/ monorepo."""
+    dirs = [root]
+    for name in TRACK_DIRS:
+        d = root / name
+        if d.is_dir():
+            dirs.append(d)
+    return dirs
+
+
+def detect(repo_root: Path) -> dict[str, Any]:
+    root = repo_root
+    languages: set[str] = set()
+    frameworks: set[str] = set()
+    tools: set[str] = set()
+    node_scripts: dict[str, str] = {}
+
+    for d in _manifest_dirs(root):
+        pyproject = _read(d / "pyproject.toml")
+        if pyproject or (d / "requirements.txt").exists() or (d / "setup.py").exists():
+            languages.add("python")
+            for dep in ("fastapi", "django", "flask", "sqlalchemy", "alembic", "pydantic"):
+                if re.search(rf"\b{dep}\b", pyproject, re.IGNORECASE):
+                    frameworks.add(dep)
+            for tool in ("ruff", "black", "mypy", "pytest", "tox", "nox"):
+                if re.search(rf"\b{tool}\b", pyproject, re.IGNORECASE):
+                    tools.add(tool)
+
+        pkg = _load_json(d / "package.json")
+        if pkg:
+            languages.add("node")
+            node_scripts.update(pkg.get("scripts", {}) or {})
+            alldeps = {**(pkg.get("dependencies") or {}), **(pkg.get("devDependencies") or {})}
+            for dep in (
+                "next",
+                "react",
+                "vue",
+                "svelte",
+                "@sveltejs/kit",
+                "vite",
+                "express",
+                "@nestjs/core",
+                "vitest",
+                "jest",
+                "eslint",
+                "prettier",
+                "typescript",
+            ):
+                if dep in alldeps:
+                    frameworks.add(dep.split("/")[0].lstrip("@"))
+
+        if (d / "go.mod").exists():
+            languages.add("go")
+        if (d / "Cargo.toml").exists():
+            languages.add("rust")
+        jvm = _read(d / "pom.xml") + _read(d / "build.gradle") + _read(d / "build.gradle.kts")
+        if jvm:
+            languages.add("java")
+            if re.search(r"spring", jvm, re.IGNORECASE):
+                frameworks.add("spring")
+        gemfile = _read(d / "Gemfile")
+        if gemfile:
+            languages.add("ruby")
+            if re.search(r"\brails\b", gemfile, re.IGNORECASE):
+                frameworks.add("rails")
+
+    if (root / ".golangci.yml").exists() or (root / ".golangci.yaml").exists():
+        tools.add("golangci-lint")
+
+    tracks = [name for name in TRACK_DIRS if (root / name).is_dir()]
+
+    # data / infra
+    infra: dict[str, Any] = {
+        "databases": [],
+        "supabase": False,
+        "migrations": None,
+        "docker_compose": False,
+    }
+    for compose in ("docker-compose.yml", "docker-compose.yaml", "compose.yml"):
+        text = _read(root / compose)
+        if text:
+            infra["docker_compose"] = True
+            for img in DB_IMAGES:
+                if re.search(rf"image:\s*[\"']?{img}", text, re.IGNORECASE):
+                    if img not in infra["databases"]:
+                        infra["databases"].append(img)
+    if (root / "supabase").is_dir():
+        infra["supabase"] = True
+        if "postgres" not in infra["databases"]:
+            infra["databases"].append("postgres")
+    for mig in ("alembic", "migrations", "prisma", "db/migrate"):
+        if (root / mig).exists() or any((root / t / "alembic").exists() for t in tracks):
+            infra["migrations"] = mig
+            break
+
+    existing = {
+        "constitution": (root / "CONSTITUTION.md").exists(),
+        "claude_dir": (root / ".claude").is_dir(),
+        "docs": (root / "docs").is_dir(),
+        "ci": (root / ".github" / "workflows").is_dir(),
+        "git": (root / ".git").exists(),
+        "specced": (root / ".specced" / "config.json").exists(),
+    }
+
+    detection = {
+        "repo_root": str(root),
+        "languages": sorted(languages),
+        "frameworks": sorted(frameworks),
+        "tools": sorted(tools),
+        "node_scripts": node_scripts,
+        "tracks": tracks,
+        "infra": infra,
+        "existing": existing,
+        "monorepo": len([t for t in tracks if t in ("backend", "frontend", "ml")]) >= 2,
+    }
+    detection["suggested_preset"] = suggest_preset(detection)
+    detection["suggested_mcp"] = suggest_mcp(detection)
+    detection["suggested_verification"] = suggest_verification(detection)
+    detection["summary"] = summary(detection)
+    return detection
+
+
+def _load_presets() -> list[dict[str, Any]]:
+    out: list[dict[str, Any]] = []
+    for path in sorted((templates_dir() / "presets").glob("*.json")):
+        try:
+            out.append(json.loads(path.read_text(encoding="utf-8")))
+        except json.JSONDecodeError:
+            continue
+    return out
+
+
+def suggest_preset(d: dict[str, Any]) -> str | None:
+    """Pick the highest-priority preset whose declared markers match the repo.
+
+    Detection is DATA-DRIVEN: each preset file (templates/presets/*.json) carries a
+    `detect` block, e.g. ``{"any_frameworks": ["next"], "priority": 52}``. The preset's
+    top-level ``language`` must be present in the repo; if ``any_frameworks`` is given,
+    at least one must match. A preset with no ``any_frameworks`` is the generic fallback
+    for its language. Adding an auto-detected preset is therefore one JSON file, no code.
+    """
+    langs = set(d["languages"])
+    fw = set(d["frameworks"])
+    best: str | None = None
+    best_priority = -1
+    for preset in _load_presets():
+        det = preset.get("detect")
+        if det is None:
+            continue
+        language = det.get("language") or preset.get("language")
+        if not language or language not in langs:
+            continue
+        any_frameworks = det.get("any_frameworks") or []
+        if any_frameworks and not (fw & set(any_frameworks)):
+            continue
+        priority = det.get("priority", 0)
+        if priority > best_priority:
+            best_priority = priority
+            best = preset.get("name")
+    return best
+
+
+def suggest_mcp(d: dict[str, Any]) -> list[str]:
+    servers = ["context7"]
+    if d["existing"]["ci"] or d["existing"]["git"]:
+        servers.append("github")
+    infra = d["infra"]
+    if infra["supabase"]:
+        servers.append("supabase")
+    elif "postgres" in infra["databases"]:
+        servers.append("postgres")
+    if "qdrant" in infra["databases"]:
+        servers.append("qdrant")
+    # de-dup, preserve order
+    seen: set[str] = set()
+    return [s for s in servers if not (s in seen or seen.add(s))]
+
+
+def suggest_verification(d: dict[str, Any]) -> dict[str, str | None]:
+    langs = d["languages"]
+    tools = set(d["tools"])
+    scripts = d["node_scripts"]
+    out: dict[str, str | None] = {"fmt": None, "lint": None, "test": None, "build": None}
+    if "python" in langs:
+        out["fmt"] = "ruff format ." if "ruff" in tools else "black ."
+        out["lint"] = "ruff check ." + (" && mypy ." if "mypy" in tools else "")
+        out["test"] = "pytest -q"
+        out["build"] = "python -m build"
+    if "go" in langs:
+        out["fmt"] = "gofmt -w ."
+        out["lint"] = "golangci-lint run" if "golangci-lint" in tools else "go vet ./..."
+        out["test"] = "go test ./..."
+        out["build"] = "go build ./..."
+    if "rust" in langs:
+        out["fmt"] = "cargo fmt"
+        out["lint"] = "cargo clippy --all-targets -- -D warnings"
+        out["test"] = "cargo test"
+        out["build"] = "cargo build --release"
+    if "java" in langs:
+        out["fmt"] = "./mvnw spotless:apply"
+        out["lint"] = "./mvnw -q verify -DskipTests"
+        out["test"] = "./mvnw test"
+        out["build"] = "./mvnw -q package -DskipTests"
+    if "ruby" in langs:
+        out["fmt"] = "bundle exec rubocop -A"
+        out["lint"] = "bundle exec rubocop"
+        out["test"] = "bundle exec rspec"
+        out["build"] = "bundle exec rails zeitwerk:check"
+    if "node" in langs:
+        if "lint" in scripts:
+            out["lint"] = "npm run lint"
+        if "build" in scripts:
+            out["build"] = "npm run build"
+        if "test" in scripts:
+            out["test"] = "npm test"
+        if "format" in scripts:
+            out["fmt"] = "npm run format"
+    return out
+
+
+def summary(d: dict[str, Any]) -> list[str]:
+    lines = []
+    lines.append(f"languages: {', '.join(d['languages']) or 'unknown'}")
+    if d["frameworks"]:
+        lines.append(f"frameworks: {', '.join(d['frameworks'])}")
+    if d["tracks"]:
+        lines.append(
+            f"tracks: {', '.join(d['tracks'])}" + ("  (monorepo)" if d["monorepo"] else "")
+        )
+    if d["infra"]["databases"]:
+        lines.append(
+            f"data: {', '.join(d['infra']['databases'])}"
+            + ("  +supabase" if d["infra"]["supabase"] else "")
+        )
+    if d["suggested_preset"]:
+        lines.append(f"suggested preset: {d['suggested_preset']}")
+    lines.append(f"suggested mcp: {', '.join(d['suggested_mcp'])}")
+    return lines