deploysquad-recon-core 0.1.1__tar.gz

deploysquad_recon_core-0.1.1/PKG-INFO

@@ -0,0 +1,11 @@
+Metadata-Version: 2.4
+Name: deploysquad-recon-core
+Version: 0.1.1
+Summary: Engine for reading, writing, and validating Obsidian vault project graphs
+Requires-Python: >=3.11
+Requires-Dist: pydantic>=2.0
+Requires-Dist: python-frontmatter>=1.0
+Requires-Dist: mcp[cli]>=1.0
+Requires-Dist: google-generativeai<2,>=0.8
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"

deploysquad_recon_core-0.1.1/pyproject.toml

@@ -0,0 +1,33 @@
+[build-system]
+requires = ["setuptools>=68.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "deploysquad-recon-core"
+version = "0.1.1"
+description = "Engine for reading, writing, and validating Obsidian vault project graphs"
+requires-python = ">=3.11"
+dependencies = [
+    "pydantic>=2.0",
+    "python-frontmatter>=1.0",
+    "mcp[cli]>=1.0",
+    "google-generativeai>=0.8,<2",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+]
+
+[project.scripts]
+recon-server = "deploysquad_recon_core.mcp_server:main"
+deploysquad-recon-core = "deploysquad_recon_core.__main__:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+deploysquad_recon_core = ["skill/*.md", "skill/openclaw/recon/SKILL.md", "skill/openclaw/recon-add-feature/SKILL.md"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

deploysquad_recon_core-0.1.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

deploysquad_recon_core-0.1.1/src/deploysquad_recon_core/__init__.py

@@ -0,0 +1,203 @@
+"""recon-core: Engine for reading, writing, and validating Obsidian vault project graphs.
+
+Public API:
+    create_node(node_type, data, project_dir, body_sections=None) -> Path
+    get_node(file_path) -> dict
+    list_nodes(project_dir, node_type=None, status=None) -> list[dict]
+    update_node(file_path, updates, body_sections=None) -> Path
+    resolve_links(project_dir) -> dict
+    build_index(project_dir) -> dict
+    generate_context(feature_name, project_dir) -> str
+    embed_nodes(project_dir, api_key=None) -> dict
+    find_similar(node_path, project_dir, top_k=5, threshold=0.75) -> list[tuple[Path, float]]
+"""
+from __future__ import annotations
+
+from pathlib import Path
+
+from .errors import ValidationError, NodeNotFoundError, BrokenLinkError, DuplicateNodeError
+from .models import NODE_TYPE_MAP, get_model_for_type
+from .vault.reader import read_node
+from .vault.writer import write_node
+from .vault.paths import node_filepath, parse_filename, type_to_subfolder, find_project_name, project_tag
+from .links import resolve_all_links
+from .index import build_index as _build_index, write_index, read_index
+from .context import generate_context as _generate_context
+from .embeddings import embed_nodes, find_similar
+
+
+def create_node(
+    node_type: str,
+    data: dict,
+    project_dir: str | Path,
+    body_sections: dict[str, str] | None = None,
+) -> Path:
+    """Create and write a new node to the vault.
+
+    Args:
+        node_type: One of the 10 node types (e.g. "feature", "user-story")
+        data: Dict of frontmatter fields (type and schema_version auto-filled)
+        project_dir: Root directory of the project vault
+        body_sections: Optional dict of {heading: content} for the body
+
+    Returns:
+        Path to the created file
+
+    Raises:
+        ValidationError: Data fails schema validation
+        DuplicateNodeError: Node already exists
+        KeyError: Unknown node type
+    """
+    project_dir = Path(project_dir)
+    model_cls = get_model_for_type(node_type)
+
+    # Auto-fill type and schema_version
+    full_data = {"type": node_type, "schema_version": 1, **data}
+
+    # Auto-add project tag
+    if node_type == "project":
+        proj_name = data.get("name", "")
+    else:
+        proj_name = find_project_name(project_dir)
+
+    if proj_name:
+        tag = project_tag(proj_name)
+        existing_tags = full_data.get("tags", [])
+        if tag not in existing_tags:
+            full_data["tags"] = existing_tags + [tag]
+
+    try:
+        model = model_cls(**full_data)
+    except Exception as e:
+        raise ValidationError(f"Validation failed for {node_type}: {e}") from e
+
+    return write_node(model, project_dir, body_sections=body_sections)
+
+
+def get_node(file_path: str | Path) -> dict:
+    """Read and validate a node file.
+
+    Returns dict with keys: frontmatter, body, body_sections, model, file_path
+    """
+    return read_node(Path(file_path))
+
+
+def list_nodes(
+    project_dir: str | Path,
+    node_type: str | None = None,
+    status: str | None = None,
+) -> list[dict]:
+    """List nodes in the project, optionally filtered by type and/or status.
+
+    Returns list of dicts, each with: type, name, status, file_path
+    """
+    project_dir = Path(project_dir)
+    results = []
+
+    for md_file in sorted(project_dir.rglob("*.md")):
+        if ".graph" in md_file.parts:
+            continue
+        parsed = parse_filename(md_file.name)
+        if parsed is None:
+            continue
+
+        file_type, name = parsed
+
+        if node_type and file_type != node_type:
+            continue
+
+        node_data = read_node(md_file)
+        node_status = node_data["model"].status
+        if hasattr(node_status, "value"):
+            node_status = node_status.value
+
+        if status and node_status != status:
+            continue
+
+        results.append({
+            "type": file_type,
+            "name": name,
+            "status": node_status,
+            "file_path": md_file,
+        })
+
+    return results
+
+
+def update_node(
+    file_path: str | Path,
+    updates: dict,
+    body_sections: dict[str, str] | None = None,
+) -> Path:
+    """Update an existing node's frontmatter fields.
+
+    Reads the current node, merges updates, validates, and rewrites.
+
+    Args:
+        file_path: Path to the existing node file
+        updates: Dict of fields to update (merged with existing frontmatter)
+        body_sections: If provided, replaces the body sections entirely
+
+    Returns:
+        Path to the updated file
+    """
+    file_path = Path(file_path)
+    current = read_node(file_path)
+
+    # Merge updates into existing frontmatter
+    merged = {**current["frontmatter"], **updates}
+
+    # Ensure project tag is preserved/added
+    proj_name = find_project_name(
+        file_path.parent.parent if type_to_subfolder(merged["type"]) else file_path.parent
+    )
+    if not proj_name and merged["type"] == "project":
+        proj_name = merged.get("name", "")
+    if proj_name:
+        tag = project_tag(proj_name)
+        existing_tags = merged.get("tags", [])
+        if tag not in existing_tags:
+            merged["tags"] = existing_tags + [tag]
+
+    model_cls = get_model_for_type(merged["type"])
+    try:
+        model = model_cls(**merged)
+    except Exception as e:
+        raise ValidationError(f"Validation failed: {e}") from e
+
+    # Use existing body sections if not replacing
+    if body_sections is None:
+        body_sections = current["body_sections"]
+
+    # Derive project_dir from file_path based on node type.
+    # Project nodes live at project_dir/Project - Name.md (subfolder is empty),
+    # other nodes live at project_dir/subfolder/Type - Name.md.
+    subfolder = type_to_subfolder(merged["type"])
+    if subfolder:
+        project_dir = file_path.parent.parent
+    else:
+        project_dir = file_path.parent
+
+    return write_node(model, project_dir, body_sections=body_sections, overwrite=True)
+
+
+def resolve_links(project_dir: str | Path) -> dict:
+    """Check all wikilinks in the vault.
+
+    Returns:
+        {"valid": [LinkResult, ...], "broken": [LinkResult, ...]}
+    """
+    return resolve_all_links(Path(project_dir))
+
+
+def build_index(project_dir: str | Path) -> dict:
+    """Build the graph index from vault files.
+
+    Returns the index dict. Does NOT write it to disk -- call write_index() for that.
+    """
+    return _build_index(Path(project_dir))
+
+
+def generate_context(feature_name: str, project_dir: str | Path) -> str:
+    """Generate a CONTEXT.md string for a Feature node."""
+    return _generate_context(feature_name, Path(project_dir))

deploysquad_recon_core-0.1.1/src/deploysquad_recon_core/__main__.py

@@ -0,0 +1,50 @@
+"""Entry point for `uvx deploysquad-recon-core [subcommand]`.
+
+No args → start MCP server (Claude Code)
+install  → interactive installer
+*        → CLI subcommand for OpenClaw shell integration
+"""
+import sys
+
+
+def main() -> None:
+    if len(sys.argv) < 2:
+        # No subcommand — start MCP server
+        from .mcp_server import main as mcp_main
+        mcp_main()
+        return
+
+    command = sys.argv[1]
+
+    if command == "install":
+        from .cli import install
+        install()
+        return
+
+    # All other subcommands go through cli_tools
+    from .cli_tools import build_parser
+    handlers = {
+        "list_nodes":       "cmd_list_nodes",
+        "get_node":         "cmd_get_node",
+        "create_node":      "cmd_create_node",
+        "update_node":      "cmd_update_node",
+        "resolve_links":    "cmd_resolve_links",
+        "build_index":      "cmd_build_index",
+        "generate_context": "cmd_generate_context",
+        "embed_nodes":      "cmd_embed_nodes",
+        "find_similar":     "cmd_find_similar",
+    }
+
+    if command not in handlers:
+        print(f"Unknown command: {command}", file=sys.stderr)
+        print(f"Available: install, {', '.join(handlers)}", file=sys.stderr)
+        sys.exit(1)
+
+    from . import cli_tools
+    parser = build_parser()
+    args = parser.parse_args()
+    getattr(cli_tools, handlers[command])(args)
+
+
+if __name__ == "__main__":
+    main()

deploysquad_recon_core-0.1.1/src/deploysquad_recon_core/cli.py

@@ -0,0 +1,107 @@
+"""Install command for recon — writes MCP config and copies skill files."""
+from __future__ import annotations
+
+import importlib.resources as resources
+import json
+import shutil
+from pathlib import Path
+
+
+def _claude_settings_path() -> Path:
+    return Path.home() / ".claude" / "settings.json"
+
+
+def _commands_dir() -> Path:
+    return Path.home() / ".claude" / "commands"
+
+
+def _read_settings(path: Path) -> dict:
+    if path.exists():
+        try:
+            return json.loads(path.read_text())
+        except json.JSONDecodeError as e:
+            raise SystemExit(
+                f"Error: {path} contains invalid JSON and could not be read.\n"
+                f"Please fix or remove it before running install.\nDetail: {e}"
+            )
+    return {}
+
+
+def _write_settings(path: Path, data: dict) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(data, indent=2))
+
+
+def _openclaw_skills_dir() -> Path | None:
+    """Return OpenClaw skills directory if OpenClaw is installed, else None."""
+    openclaw_dir = Path.home() / ".openclaw" / "workspace" / "skills"
+    return openclaw_dir if openclaw_dir.parent.parent.exists() else None
+
+
+def _install_openclaw_skills() -> bool:
+    """Copy OpenClaw skill dirs to ~/.openclaw/workspace/skills/. Returns True if installed."""
+    skills_dir = _openclaw_skills_dir()
+    if skills_dir is None:
+        return False
+
+    skills_dir.mkdir(parents=True, exist_ok=True)
+    import deploysquad_recon_core
+
+    skill_src = resources.files(deploysquad_recon_core) / "skill" / "openclaw"
+    for skill_name in ["recon", "recon-add-feature"]:
+        dest = skills_dir / skill_name
+        dest.mkdir(exist_ok=True)
+        src_file = skill_src / skill_name / "SKILL.md"
+        with resources.as_file(src_file) as src:
+            shutil.copy2(src, dest / "SKILL.md")
+        print(f"✓ OpenClaw: {skill_name} skill copied to {dest}")
+    return True
+
+
+def install() -> None:
+    """Interactive installer: prompts for vault path, writes MCP config, copies skills."""
+    # Prompt for vault path — re-prompt until path exists
+    default = str(Path.home() / "obsidian-vault")
+    while True:
+        raw = input(f"Where is your Obsidian vault? [{default}] ").strip()
+        vault_path = raw if raw else default
+        if Path(vault_path).exists():
+            break
+        print(f"  ✗ Path not found: {vault_path}. Please enter a valid directory.")
+
+    # Write MCP server config
+    settings_path = _claude_settings_path()
+    settings = _read_settings(settings_path)
+    settings.setdefault("mcpServers", {})
+    settings["mcpServers"]["recon"] = {
+        "command": "uvx",
+        "args": ["deploysquad-recon-core"],
+        "env": {"VAULT_PATH": vault_path},
+    }
+    _write_settings(settings_path, settings)
+    print(f"✓ MCP server config written to {settings_path}")
+
+    # Copy skill files
+    commands_dir = _commands_dir()
+    commands_dir.mkdir(parents=True, exist_ok=True)
+
+    import deploysquad_recon_core
+    skill_dir = resources.files(deploysquad_recon_core) / "skill"
+    for skill_file in ["recon.md", "recon.add-feature.md"]:
+        dest = commands_dir / skill_file
+        skill_source = skill_dir / skill_file
+        with resources.as_file(skill_source) as src:
+            shutil.copy2(src, dest)
+        print(f"✓ Copied {skill_file} to {dest}")
+
+    # OpenClaw (if installed)
+    if _install_openclaw_skills():
+        print()
+        print("OpenClaw detected — skills also installed.")
+        print("In OpenClaw, say: 'map out my project with recon'")
+    else:
+        print()
+        print("(OpenClaw not detected — skipping. Install from openclaw.ai if needed.)")
+
+    print()
+    print("Done! Restart Claude Code and run /recon to get started.")

deploysquad_recon_core-0.1.1/src/deploysquad_recon_core/cli_tools.py

@@ -0,0 +1,190 @@
+"""CLI subcommands for OpenClaw shell integration.
+
+Each function is one subcommand. All output JSON to stdout.
+Exit code 0 = success, 1 = error (error JSON on stdout).
+"""
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+
+
+def _ok(data: dict | list) -> None:
+    print(json.dumps(data, default=str))
+
+
+def _err(message: str) -> None:
+    print(json.dumps({"error": message}))
+    sys.exit(1)
+
+
+def cmd_list_nodes(args) -> None:
+    from deploysquad_recon_core import list_nodes
+    try:
+        nodes = list_nodes(
+            args.project_dir,
+            node_type=args.type,
+            status=args.status,
+        )
+        _ok([{
+            "type": n["type"],
+            "name": n["name"],
+            "status": n["status"],
+            "file_path": str(n["file_path"]),
+        } for n in nodes])
+    except Exception as e:
+        _err(str(e))
+
+
+def cmd_get_node(args) -> None:
+    from deploysquad_recon_core import get_node
+    try:
+        result = get_node(args.file)
+        _ok({
+            "frontmatter": result["frontmatter"],
+            "body": result["body"],
+            "file_path": str(args.file),
+        })
+    except Exception as e:
+        _err(str(e))
+
+
+def cmd_create_node(args) -> None:
+    from deploysquad_recon_core import create_node
+    try:
+        data = json.loads(args.data)
+        body_sections = json.loads(args.body_sections) if args.body_sections else None
+        path = create_node(args.type, data, args.project_dir, body_sections)
+        _ok({"file_path": str(path), "status": "created"})
+    except Exception as e:
+        _err(str(e))
+
+
+def cmd_update_node(args) -> None:
+    from deploysquad_recon_core import update_node
+    try:
+        updates = json.loads(args.data)
+        body_sections = json.loads(args.body_sections) if args.body_sections else None
+        path = update_node(args.file, updates, body_sections)
+        _ok({"file_path": str(path), "status": "updated"})
+    except Exception as e:
+        _err(str(e))
+
+
+def cmd_resolve_links(args) -> None:
+    from deploysquad_recon_core import resolve_links
+    try:
+        result = resolve_links(args.project_dir)
+        _ok({
+            "valid_count": len(result["valid"]),
+            "broken_count": len(result["broken"]),
+            "broken": [str(b) for b in result["broken"]],
+        })
+    except Exception as e:
+        _err(str(e))
+
+
+def cmd_build_index(args) -> None:
+    from deploysquad_recon_core import build_index
+    from deploysquad_recon_core.index import write_index
+    try:
+        index = build_index(args.project_dir)
+        write_index(index, Path(args.project_dir))
+        _ok({"node_count": len(index.get("nodes", {})), "status": "built"})
+    except Exception as e:
+        _err(str(e))
+
+
+def cmd_generate_context(args) -> None:
+    from deploysquad_recon_core import generate_context
+    try:
+        content = generate_context(args.feature, args.project_dir)
+        _ok({"content": content, "feature": args.feature})
+    except Exception as e:
+        _err(str(e))
+
+
+def cmd_embed_nodes(args) -> None:
+    from deploysquad_recon_core import embed_nodes
+    try:
+        result = embed_nodes(args.project_dir, api_key=args.api_key)
+        _ok(result if isinstance(result, dict) else {"status": "embedded"})
+    except Exception as e:
+        _err(str(e))
+
+
+def cmd_find_similar(args) -> None:
+    from deploysquad_recon_core import find_similar
+    try:
+        results = find_similar(
+            Path(args.node),
+            args.project_dir,
+            top_k=args.top_k,
+            threshold=args.threshold,
+        )
+        _ok([{"path": str(p), "score": score} for p, score in results])
+    except Exception as e:
+        _err(str(e))
+
+
+def build_parser():
+    import argparse
+    parser = argparse.ArgumentParser(
+        prog="deploysquad_recon_core",
+        description="recon-core CLI — graph authoring tools",
+    )
+    sub = parser.add_subparsers(dest="command")
+
+    # install
+    sub.add_parser("install", help="Install recon into Claude Code / OpenClaw")
+
+    # list_nodes
+    p = sub.add_parser("list_nodes", help="List nodes in a project")
+    p.add_argument("--project-dir", required=True)
+    p.add_argument("--type", default=None)
+    p.add_argument("--status", default=None)
+
+    # get_node
+    p = sub.add_parser("get_node", help="Read a node file")
+    p.add_argument("--file", required=True, type=Path)
+
+    # create_node
+    p = sub.add_parser("create_node", help="Create a new node")
+    p.add_argument("--type", required=True)
+    p.add_argument("--project-dir", required=True)
+    p.add_argument("--data", required=True, help="JSON dict of frontmatter fields")
+    p.add_argument("--body-sections", default=None, help='JSON dict e.g. \'{"## Description": "..."}\'')
+
+    # update_node
+    p = sub.add_parser("update_node", help="Update an existing node")
+    p.add_argument("--file", required=True, type=Path)
+    p.add_argument("--data", required=True, help="JSON dict of fields to update")
+    p.add_argument("--body-sections", default=None)
+
+    # resolve_links
+    p = sub.add_parser("resolve_links", help="Check all wikilinks")
+    p.add_argument("--project-dir", required=True)
+
+    # build_index
+    p = sub.add_parser("build_index", help="Rebuild .graph/index.json")
+    p.add_argument("--project-dir", required=True)
+
+    # generate_context
+    p = sub.add_parser("generate_context", help="Generate CONTEXT.md for a feature")
+    p.add_argument("--feature", required=True, help="Feature name (not filename)")
+    p.add_argument("--project-dir", required=True)
+
+    # embed_nodes
+    p = sub.add_parser("embed_nodes", help="Embed all nodes for semantic search")
+    p.add_argument("--project-dir", required=True)
+    p.add_argument("--api-key", default=None)
+
+    # find_similar
+    p = sub.add_parser("find_similar", help="Find semantically similar nodes")
+    p.add_argument("--node", required=True, help="Vault-relative path to node file")
+    p.add_argument("--project-dir", required=True)
+    p.add_argument("--top-k", type=int, default=5)
+    p.add_argument("--threshold", type=float, default=0.75)
+
+    return parser