reposeed 0.4.0__py3-none-any.whl

reposeed/__init__.py

@@ -0,0 +1,10 @@
+"""RepoSeed project initializer."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("reposeed")
+except PackageNotFoundError:
+    __version__ = "0.4.0"
+
+__all__ = ["__version__"]

reposeed/__main__.py

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

reposeed/cli.py

@@ -0,0 +1,232 @@
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from collections.abc import Sequence
+from pathlib import Path
+
+from reposeed import __version__
+from reposeed.constants import PLATFORM_LABELS, PLATFORMS, STACK_LABELS, STACKS
+from reposeed.detect import detect_project
+from reposeed.doctor import diagnose_project
+from reposeed.errors import CliError
+from reposeed.graphify import graphify_python, run_graphify
+from reposeed.initializer import initialize_project
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    arguments = list(argv if argv is not None else sys.argv[1:])
+    try:
+        if arguments[:1] == ["graphify"]:
+            return run_graphify(arguments[1:])
+        if arguments[:1] == ["_graphify-python"]:
+            return graphify_python()
+
+        parser = _create_parser()
+        namespace = parser.parse_args(arguments)
+        if namespace.command == "init":
+            return _run_init(namespace)
+        if namespace.command == "doctor":
+            return _run_doctor(namespace)
+        parser.print_help()
+        return 0
+    except CliError as error:
+        print(f"Error: {error}", file=sys.stderr)
+        return error.exit_code
+    except KeyboardInterrupt:
+        print("\nError: Initialization cancelled.", file=sys.stderr)
+        return 130
+
+
+def _create_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="reposeed",
+        description="Initialize portable agent instructions and skills for AI coding tools.",
+    )
+    parser.add_argument("--version", action="version", version=__version__)
+    subparsers = parser.add_subparsers(dest="command")
+
+    init = subparsers.add_parser("init", help="initialize agent standards in a project")
+    init.add_argument("directory", nargs="?", default=".", help="project directory")
+    init.add_argument(
+        "-p",
+        "--platforms",
+        help="comma-separated: codex, claude, cursor, antigravity",
+    )
+    init.add_argument(
+        "-s",
+        "--stacks",
+        help="comma-separated: node, python, php, flutter (default: auto-detect)",
+    )
+    init.add_argument("-y", "--yes", action="store_true", help="accept defaults")
+    init.add_argument(
+        "--no-graphify",
+        action="store_false",
+        dest="graphify",
+        default=True,
+        help="skip managed Graphify integration",
+    )
+    graphify_git_hooks = init.add_mutually_exclusive_group()
+    graphify_git_hooks.add_argument(
+        "--graphify-git-hooks",
+        action="store_true",
+        dest="graphify_git_hooks",
+        help="install Graphify Git auto-rebuild hooks (default with Graphify)",
+    )
+    graphify_git_hooks.add_argument(
+        "--no-graphify-git-hooks",
+        action="store_false",
+        dest="graphify_git_hooks",
+        help="skip or remove the default Graphify Git hooks",
+    )
+    init.set_defaults(graphify_git_hooks=None)
+    init.add_argument("--dry-run", action="store_true", help="show changes without writing")
+    init.add_argument("--force", action="store_true", help="replace conflicting generated files")
+    init.add_argument("--json", action="store_true", dest="json_output")
+
+    doctor = subparsers.add_parser("doctor", help="validate an initialized project")
+    doctor.add_argument("directory", nargs="?", default=".", help="project directory")
+    doctor.add_argument("--json", action="store_true", dest="json_output")
+
+    graphify = subparsers.add_parser(
+        "graphify",
+        help="run Graphify from the managed uvx environment",
+    )
+    graphify.add_argument("arguments", nargs=argparse.REMAINDER)
+    return parser
+
+
+def _run_init(namespace: argparse.Namespace) -> int:
+    target = Path(namespace.directory).resolve()
+    detected = detect_project(target)
+    selected_platforms = _parse_list(namespace.platforms)
+    selected_stacks = _parse_list(namespace.stacks) if namespace.stacks is not None else None
+
+    if not namespace.yes and sys.stdin.isatty() and namespace.platforms is None:
+        selected_platforms = _prompt_selection(
+            "Coding agents",
+            list(PLATFORMS),
+            PLATFORM_LABELS,
+            list(PLATFORMS),
+            required=True,
+        )
+        if namespace.stacks is None:
+            selected_stacks = _prompt_selection(
+                "Application stacks",
+                list(STACKS),
+                STACK_LABELS,
+                list(detected["stacks"]),
+                required=False,
+            )
+
+    selected_platforms = selected_platforms or list(PLATFORMS)
+    if selected_stacks is None:
+        selected_stacks = list(detected["stacks"])
+
+    def report(message: str) -> None:
+        if not namespace.json_output:
+            print(f"→ {message}")
+
+    result = initialize_project(
+        target_directory=target,
+        platforms=selected_platforms,
+        stacks=selected_stacks,
+        graphify=namespace.graphify,
+        graphify_git_hooks=namespace.graphify_git_hooks,
+        dry_run=namespace.dry_run,
+        force=namespace.force,
+        report=report,
+    )
+    if namespace.json_output:
+        print(json.dumps(result, indent=2))
+    else:
+        print(_format_init_result(result, namespace.dry_run))
+    return 2 if any(item["status"] == "conflict" for item in result["operations"]) else 0
+
+
+def _run_doctor(namespace: argparse.Namespace) -> int:
+    result = diagnose_project(Path(namespace.directory))
+    if namespace.json_output:
+        print(json.dumps(result, indent=2))
+    elif result["ok"]:
+        print(
+            f"Healthy: {len(result['checks'])} managed files verified in "
+            f"{result['targetDirectory']}"
+        )
+    else:
+        print(f"Found {len(result['issues'])} issue(s) in {result['targetDirectory']}:")
+        for issue in result["issues"]:
+            print(f"- {issue}")
+    return 0 if result["ok"] else 1
+
+
+def _parse_list(value: str | None) -> list[str] | None:
+    if value is None:
+        return None
+    return list(dict.fromkeys(item.strip() for item in value.split(",") if item.strip()))
+
+
+def _prompt_selection(
+    title: str,
+    choices: list[str],
+    labels: dict[str, str],
+    defaults: list[str],
+    *,
+    required: bool,
+) -> list[str]:
+    print(f"\n{title}:")
+    for index, choice in enumerate(choices, start=1):
+        suffix = " (default)" if choice in defaults else ""
+        print(f"  {index}. {labels[choice]}{suffix}")
+    default_text = ",".join(defaults)
+    answer = input(f"Choose comma-separated names or numbers [{default_text}]: ").strip()
+    if not answer:
+        selected = defaults
+    else:
+        selected = []
+        for item in (part.strip() for part in answer.split(",")):
+            selected.append(choices[int(item) - 1] if item.isdigit() else item)
+        selected = list(dict.fromkeys(selected))
+    if required and not selected:
+        raise CliError("Select at least one option.")
+    return selected
+
+
+def _format_init_result(result: dict[str, object], dry_run: bool) -> str:
+    operations = result["operations"]
+    groups: dict[str, list[dict[str, str]]] = {}
+    for operation in operations:  # type: ignore[union-attr]
+        groups.setdefault(operation["status"], []).append(operation)
+    platforms = ", ".join(result["platforms"])  # type: ignore[arg-type]
+    stacks = ", ".join(result["stacks"]) or "universal only"  # type: ignore[arg-type]
+    lines = [
+        f"{'Planned' if dry_run else 'Initialized'} {result['targetDirectory']}",
+        f"Platforms: {platforms}",
+        f"Stacks: {stacks}",
+        "Files: "
+        f"{len(groups.get('created', []))} created, "
+        f"{len(groups.get('updated', []))} updated, "
+        f"{len(groups.get('unchanged', []))} unchanged",
+    ]
+    if groups.get("conflict"):
+        paths = ", ".join(item["path"] for item in groups["conflict"])
+        lines.extend((f"Conflicts preserved: {paths}", "Review those files or rerun with --force."))
+    graphify = result["graphify"]
+    if graphify["enabled"]:  # type: ignore[index]
+        status = "planned" if dry_run else "verified and configured"
+        lines.append(
+            f"Graphify {graphify['version']}: {status} through the uvx environment"  # type: ignore[index]
+        )
+        for item in graphify["platforms"]:  # type: ignore[index]
+            if item.get("platform"):
+                lines.append(f"Graphify ({item['platform']}): {item['status']}")
+        git_hooks = graphify.get("gitHooks", {})  # type: ignore[union-attr]
+        if git_hooks.get("enabled") or git_hooks.get("status") in {
+            "removed",
+            "planned-removal",
+            "skipped-no-git",
+        }:
+            lines.append(f"Graphify Git hooks: {git_hooks['status']}")
+    lines.append("Run `uvx reposeed doctor` to verify the installation.")
+    return "\n".join(lines)

reposeed/constants.py

@@ -0,0 +1,35 @@
+from __future__ import annotations
+
+from importlib.resources import files
+
+FOUNDATION_ROOT = files("reposeed").joinpath("foundation")
+
+PLATFORMS = ("codex", "claude", "cursor", "antigravity")
+STACKS = ("node", "python", "php", "flutter")
+
+PLATFORM_LABELS = {
+    "codex": "Codex",
+    "claude": "Claude Code",
+    "cursor": "Cursor",
+    "antigravity": "Antigravity",
+}
+STACK_LABELS = {
+    "node": "Node.js / TypeScript",
+    "python": "Python",
+    "php": "PHP",
+    "flutter": "Flutter / Dart",
+}
+
+MANAGED_BEGIN = "<!-- reposeed:begin -->"
+MANAGED_END = "<!-- reposeed:end -->"
+MANIFEST_PATH = ".reposeed/manifest.json"
+CONFIG_PATH = ".reposeed/config.json"
+
+GRAPHIFY_PACKAGE = "graphifyy"
+GRAPHIFY_VERSION = "0.9.49"
+GRAPHIFY_PLATFORMS = {
+    "codex": "codex",
+    "claude": "claude",
+    "cursor": "cursor",
+    "antigravity": "antigravity",
+}

reposeed/detect.py

@@ -0,0 +1,89 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+
+def _read_json(path: Path) -> dict[str, Any] | None:
+    try:
+        return json.loads(path.read_text(encoding="utf-8"))
+    except (FileNotFoundError, json.JSONDecodeError):
+        return None
+
+
+def detect_project(target_directory: Path) -> dict[str, list[Any]]:
+    package_json = _read_json(target_directory / "package.json")
+    stacks: list[str] = []
+    if package_json:
+        stacks.append("node")
+    if any(
+        (target_directory / name).exists()
+        for name in ("pyproject.toml", "requirements.txt", "setup.py")
+    ):
+        stacks.append("python")
+    if any((target_directory / name).exists() for name in ("composer.json", "artisan")):
+        stacks.append("php")
+    if (target_directory / "pubspec.yaml").exists():
+        stacks.append("flutter")
+
+    return {
+        "stacks": list(dict.fromkeys(stacks)),
+        "commands": _detect_commands(target_directory, package_json),
+    }
+
+
+def _detect_commands(
+    target_directory: Path, package_json: dict[str, Any] | None
+) -> list[dict[str, str]]:
+    commands: list[dict[str, str]] = []
+    if package_json:
+        runner, install = "npm", "npm install"
+        if (target_directory / "pnpm-lock.yaml").exists():
+            runner, install = "pnpm", "pnpm install"
+        elif (target_directory / "yarn.lock").exists():
+            runner, install = "yarn", "yarn install"
+        elif any((target_directory / name).exists() for name in ("bun.lock", "bun.lockb")):
+            runner, install = "bun", "bun install"
+        commands.append({"label": "Install", "command": install})
+        scripts = package_json.get("scripts", {})
+        for name in ("lint", "typecheck", "test", "build"):
+            if scripts.get(name):
+                separator = " run " if runner == "npm" else " "
+                commands.append({"label": name.title(), "command": f"{runner}{separator}{name}"})
+
+    if (target_directory / "pyproject.toml").exists():
+        if (target_directory / "uv.lock").exists():
+            commands.append({"label": "Install Python", "command": "uv sync"})
+        commands.append({"label": "Test Python", "command": "pytest"})
+    elif (target_directory / "requirements.txt").exists():
+        commands.extend(
+            [
+                {
+                    "label": "Install Python",
+                    "command": "python -m pip install -r requirements.txt",
+                },
+                {"label": "Test Python", "command": "pytest"},
+            ]
+        )
+
+    if (target_directory / "composer.json").exists():
+        commands.extend(
+            [
+                {"label": "Install PHP", "command": "composer install"},
+                {"label": "Test PHP", "command": "composer test"},
+            ]
+        )
+    if (target_directory / "pubspec.yaml").exists():
+        commands.extend(
+            [
+                {"label": "Install Flutter", "command": "flutter pub get"},
+                {"label": "Analyze Flutter", "command": "flutter analyze"},
+                {"label": "Test Flutter", "command": "flutter test"},
+            ]
+        )
+
+    unique: dict[str, dict[str, str]] = {}
+    for command in commands:
+        unique.setdefault(command["command"], command)
+    return list(unique.values())

reposeed/doctor.py

@@ -0,0 +1,122 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from reposeed.constants import CONFIG_PATH, GRAPHIFY_VERSION, MANIFEST_PATH
+from reposeed.graphify import (
+    RunCommand,
+    default_run_command,
+    expected_graphify_files,
+    graphify_git_hooks_healthy,
+    inspect_graphify,
+    inspect_graphify_git_hooks,
+)
+from reposeed.managed_file import content_hash, extract_managed_block, read_json, read_text
+from reposeed.validation import validate_skill
+
+
+def diagnose_project(
+    target_directory: Path, run_command: RunCommand = default_run_command
+) -> dict[str, object]:
+    root = target_directory.resolve()
+    config = read_json(root / CONFIG_PATH)
+    manifest = read_json(root / MANIFEST_PATH)
+    issues: list[str] = []
+    checks: list[str] = []
+
+    if not config:
+        issues.append(f"{CONFIG_PATH} is missing; run `uvx reposeed init`.")
+    if not manifest:
+        issues.append(f"{MANIFEST_PATH} is missing; run `uvx reposeed init`.")
+
+    if manifest:
+        for relative_path, record in manifest.get("files", {}).items():
+            content = read_text(root / relative_path)
+            if content is None:
+                issues.append(f"{relative_path} is missing.")
+                continue
+            tracked = (
+                extract_managed_block(content) if record.get("mode") == "managed-block" else content
+            )
+            if tracked is None or content_hash(tracked) != record.get("sha256"):
+                issues.append(f"{relative_path} has local changes.")
+            else:
+                checks.append(f"{relative_path} matches the manifest.")
+
+    skills_directory = root / ".agents" / "skills"
+    if not skills_directory.is_dir():
+        issues.append(".agents/skills is missing.")
+    else:
+        for entry in sorted(skills_directory.iterdir()):
+            if not entry.is_dir():
+                continue
+            relative_path = f".agents/skills/{entry.name}/SKILL.md"
+            content = read_text(root / relative_path)
+            if content is None:
+                issues.append(f"{relative_path} is missing.")
+            else:
+                issues.extend(validate_skill(content, entry.name, relative_path))
+
+    graphify_config = config.get("graphify") if config else None
+    graphify_enabled = graphify_config is True or (
+        isinstance(graphify_config, dict) and graphify_config.get("enabled") is True
+    )
+    if graphify_enabled:
+        extraction_mode = (
+            graphify_config.get("extractionMode") if isinstance(graphify_config, dict) else None
+        )
+        if extraction_mode != "ast-only":
+            issues.append(
+                "Managed Graphify is not configured for AST-only extraction; rerun "
+                "uvx reposeed init."
+            )
+        else:
+            checks.append("Managed Graphify extraction mode is AST-only.")
+
+        expected_version = (
+            graphify_config.get("version", GRAPHIFY_VERSION)
+            if isinstance(graphify_config, dict)
+            else GRAPHIFY_VERSION
+        )
+        installed = inspect_graphify(root, run_command)
+        if not installed:
+            issues.append("Managed Graphify runtime is unavailable in the uvx environment.")
+        elif installed["version"] != expected_version:
+            issues.append(
+                f"Managed Graphify version is {installed['version']}; expected {expected_version}."
+            )
+        else:
+            checks.append(f"Managed Graphify {installed['version']} is available.")
+
+        graphify_platforms = (
+            graphify_config.get("platforms", config.get("platforms", []))
+            if isinstance(graphify_config, dict)
+            else config.get("platforms", [])
+        )
+        for relative_path in expected_graphify_files(graphify_platforms):
+            if read_text(root / relative_path) is None:
+                issues.append(f"{relative_path} is missing from the Graphify integration.")
+            else:
+                checks.append(f"{relative_path} is configured for Graphify.")
+
+        git_hooks = graphify_config.get("gitHooks", {}) if isinstance(graphify_config, dict) else {}
+        git_hooks_enabled = git_hooks is True or (
+            isinstance(git_hooks, dict) and git_hooks.get("enabled") is True
+        )
+        if git_hooks_enabled:
+            git_hook_status = inspect_graphify_git_hooks(root, run_command)
+            if graphify_git_hooks_healthy(git_hook_status):
+                checks.append("Graphify Git hooks are installed and current.")
+            else:
+                issues.append(
+                    "Graphify Git hooks are missing or out of date; rerun "
+                    "uvx reposeed init --graphify-git-hooks."
+                )
+
+    return {
+        "ok": not issues,
+        "targetDirectory": str(root),
+        "config": config,
+        "checks": checks,
+        "issues": issues,
+    }

reposeed/errors.py

@@ -0,0 +1,4 @@
+class CliError(Exception):
+    def __init__(self, message: str, *, exit_code: int = 1) -> None:
+        super().__init__(message)
+        self.exit_code = exit_code

reposeed/foundation/AGENTS.md

@@ -0,0 +1,108 @@
+# Shared agent conventions
+
+Use these conventions as the repository-wide baseline. Read
+`AGENTS.local.md` before non-trivial work for this project's real commands and
+exceptions. Guidance closer to the code takes precedence when it is more
+specific.
+
+## Before changing code
+
+- Surface material assumptions. Inspect the repository first; ask only when a
+  choice cannot be discovered and different answers would materially change
+  the result. State low-risk, reversible assumptions while proceeding.
+- Define a checkable completion criterion before implementation. Include the
+  behavior to preserve, the behavior to add, and the verification that will
+  prove both.
+- Build the smallest coherent change that meets that criterion. Avoid
+  speculative abstractions and unrelated cleanup.
+- Match the surrounding architecture and style. Record a nearby issue instead
+  of silently expanding the task to fix it.
+- Use the `clarify-before-building` skill for ambiguous or non-trivial work.
+- Use `writing-plans` when asked for an execution-ready implementation plan;
+  planning-only requests do not authorize code changes.
+
+## Project knowledge
+
+- Read `CONTEXT.md` before making a domain-model decision when it exists.
+- Read relevant records in `docs/adr/` before changing an established
+  architectural seam. Add an ADR when a durable, consequential decision is
+  made and the repository uses that convention.
+- Treat configuration, package scripts, tests, and existing code as the source
+  of truth. Keep `AGENTS.local.md` focused on conventions that cannot be
+  discovered cheaply from those files.
+
+## Context efficiency
+
+- Start with the smallest reliable source: targeted search, configuration, and
+  relevant code or test slices. Expand only when the evidence is insufficient.
+- Reuse existing indexes, summaries, and cached results. Reference large
+  artifacts by path instead of pasting or rereading them in full.
+- Keep plans, progress updates, and handoffs concise and decision-focused.
+- Use token-heavy semantic analysis or parallel agents only when their expected
+  value justifies the duplicated context; do not use them as routine discovery.
+
+## Implementation baseline
+
+- Use `diagnosing-bugs` for bugs, failures, regressions, or unexpected
+  behavior. Confirm root cause before proposing a fix, and keep diagnosis
+  read-only unless a fix was requested.
+- Use `tdd` when the user explicitly requests test-first development or a
+  red-green-refactor workflow.
+- Add or update tests for behavior changes. A bug fix needs a regression test
+  that fails without the fix. If a test is impractical, explain the concrete
+  reason and provide proportionate verification.
+- Validate untrusted input at system boundaries. Keep authorization checks on
+  the resource being accessed, set timeouts on external calls, and avoid
+  leaking internal errors to users.
+- Keep secrets out of source, fixtures, logs, prompts, and commit history. Use
+  the project's established secret and configuration mechanism.
+- Prefer existing dependencies and standard-library capabilities. Check
+  maintenance, licensing, security, bundle/runtime cost, and project fit before
+  adding a production dependency.
+- Preserve public interfaces unless the requested change explicitly includes a
+  migration. Document intentional breaking changes.
+- Write comments for constraints and non-obvious reasoning, not a narration of
+  the code.
+
+## Verification and delivery
+
+- Run the narrowest relevant checks while iterating, then the project's full
+  lint, type-check, and test commands before handing off when practical.
+- Report exactly what was verified and any remaining risk. Never describe a
+  check as passing if it was not run.
+- Use `verification-before-completion` before claiming changed work is fixed,
+  passing, complete, or ready to ship.
+- Use `code-review` for review-only requests and report actionable findings
+  before summaries. Do not modify reviewed code unless asked.
+- Use `security-checklist` for auth, authorization, payments, user data, file
+  uploads, or external services.
+- Use `maintain-changelog` before every commit so the dated changelog entry is
+  included in the same commit as the change.
+- Use `commit-messages` when composing commits and `pr-description` when
+  preparing pull requests.
+- Use `compounding-knowledge` after work that uncovered a reusable convention,
+  debugging technique, or repository-specific trap.
+
+## Collaboration and source control
+
+- Preserve user-authored and unrelated working-tree changes. Resolve overlap
+  explicitly instead of overwriting it.
+- Keep commits and pull requests focused on one reviewable outcome. Follow the
+  repository's branch and review policy; never push or merge unless the user or
+  workflow authorizes it.
+- Check for active parallel work before editing shared files when the project
+  provides an active-work registry or coordination mechanism.
+
+## Optional knowledge graph
+
+When `graphify-out/graph.json` exists, use `graphify query "<question>"` for
+architectural discovery before broad repository scans, and set a small
+`--budget` appropriate to the question. Prefer `query`, `path`, or `explain`
+over loading the full report or raw graph. Preserve any Graphify-managed
+sections when updating instruction files. See
+`.reposeed/guides/GRAPHIFY.md` for setup and operating details.
+After the final code edit in a task, refresh an existing graph with
+`uvx reposeed graphify update .` before handoff. This AST-only refresh is
+the complete managed update path. Managed Graphify is AST-only: do not run
+semantic extraction, media transcription, deep mode, semantic deduplication,
+or LLM community labeling through RepoSeed.

reposeed/foundation/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog
+
+This file records meaningful changes to the project for humans and agents.
+
+## [Unreleased]