specpro-cli 0.1.0__py3-none-any.whl

specpro_cli/cli/cmd_remove.py

@@ -0,0 +1,122 @@
+"""`specpro remove` — uninstall the specpro files of ONE agent from a project.
+
+The safety of this command lives entirely in one rule, fixed by the contract
+(`install-cli.md` → `## Uninstall Contract`) and not re-argued here:
+
+**Remove only paths derivable from the registry** — for each command template,
+exactly the path `setup()` would write (`planned_paths()` is that derivation).
+Three corollaries are the acceptance scenario's three clauses, and they hold by
+construction, not by checking:
+1. a user's own files are not in the set, so they cannot be deleted;
+2. another agent's installed files belong to a DIFFERENT integration's set;
+3. a specpro file the user RENAMED is no longer derivable, so it is not removed —
+   reported as zero removals, not as a failure.
+
+`--agent` is REQUIRED with no detection: detection reads the existence of the
+layout root, and after an uninstall that directory may still be there (created by
+the user or by other tooling) — using it as the removal target would report a
+successful uninstall of something that was never installed.
+
+The shared helpers (`_check_runtime`, `_abort`) are imported from `cmd_init`
+rather than copied: they are the same validation block's step 1 and the same
+failure shape, and a copy would drift the first time one of them is tuned.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import typer
+
+from specpro_cli.cli.cmd_init import _abort, _check_runtime
+from specpro_cli.integrations import registry
+
+
+def cmd_remove(
+    path: Path = typer.Argument(
+        Path("."),
+        help="Target project root.",
+        show_default=False,
+    ),
+    agent: str = typer.Option(
+        ..., "--agent", help="Agent key to uninstall (required — no detection)."
+    ),
+    source: Path | None = typer.Option(
+        None, "--source", help="Read assets from this path instead of the built-in snapshot."
+    ),
+) -> None:
+    """Remove the specpro files of one agent; never touch anything else."""
+    project_root = path.expanduser().resolve()
+
+    # --- pre-removal validation (contract: mirrors init's block) ------------------------
+    _check_runtime()  # 1  FR-002 — removal runs through the same Python runtime
+
+    integration = registry.get(agent)  # 2  FR-005 — unknown key names the valid set
+    if integration is None:
+        keys = registry.keys()
+        _abort(
+            f"unknown agent {agent!r}.",
+            f"Valid keys: {', '.join(keys) if keys else '(none registered)'}",
+        )
+
+    # 3  a missing layout root is SUCCESS with a statement, not an error — there is
+    #    nothing installed for this agent, and "uninstalled zero files" is the truth.
+    dest_root = integration.commands_dest(project_root).parent  # the layout root
+    if not dest_root.is_dir():
+        typer.echo(f"specpro remove → {project_root}")
+        typer.echo(f"agent: {agent} ({(integration.config or {}).get('name') or agent})")
+        typer.echo(f"nothing installed for {agent!r} under {dest_root}")
+        return
+
+    # --- removal: the registry-derived set, nothing else --------------------------------
+    from specpro_cli.cli.cmd_init import assets_commands_dir
+
+    # Same asset-sourcing rule as install (Uninstall Contract's `--source` row): the
+    # derivable path set needs the template NAME set, and a source checkout has no
+    # built-in snapshot to take it from.
+    commands_dir = assets_commands_dir(source)
+    if not commands_dir.is_dir():
+        _abort(
+            f"command templates not found at {commands_dir}",
+            "The built-in snapshot ships with the wheel; without it the derivable "
+            "path set cannot be computed, and guessing paths is exactly what this "
+            "command must never do.",
+            "In a source checkout, pass the repository (or its commands/ dir):  "
+            "--source <path>",
+        )
+
+    dest_roots = set(integration.deploy_roots(project_root))
+
+    removed: list[Path] = []
+    for target in integration.planned_paths(project_root, commands_dir):
+        if not target.is_file():
+            continue  # never installed (or already removed) — not in the report
+        target.unlink()
+        removed.append(target)
+        # Skills layout: the file sits in its own `specpro-<stem>/` directory. When
+        # this command's removal empties it, take the empty directory too — a
+        # NON-recursive rmdir, so a directory the user has put anything else into is
+        # left (with their files) rather than destroyed. Deploy roots themselves are
+        # never removed (the user's own files may live beside ours there).
+        parent = target.parent
+        if parent not in dest_roots:
+            try:
+                parent.rmdir()
+            except OSError:
+                pass  # not empty — the user's files stay, silently
+
+    # --- report (contract Output Contract: same shape as install's) ---------------------
+    display = (integration.config or {}).get("name") or integration.key
+    typer.echo(f"specpro remove → {project_root}")
+    typer.echo(f"agent: {integration.key} ({display})")
+    typer.echo(f"removed: {len(removed)}")
+    for p in removed:
+        typer.echo(f"  - {p}")
+    if not removed:
+        # The contract names this explicitly: zero removals against an EXISTING root
+        # is a real outcome (everything renamed or already gone), and it must be
+        # said — not folded into a silent success.
+        typer.echo(
+            f"no recognizable specpro files for {integration.key!r} "
+            f"(renamed files are never removed) — nothing was deleted."
+        )

specpro_cli/cli/entry.py

@@ -0,0 +1,181 @@
+"""The `specpro` entry point — the Typer app and the registry-derived lookups.
+
+`specs/contracts/install-cli.md` -> "入口层的职责边界" fixes what may live here:
+parse arguments, validate preconditions, orchestrate, report. Two prohibitions:
+
+- MUST NOT hardcode any agent name, path, or format — **everything is queried from the
+  registry**. That is what makes "add an agent = add one subclass" true (FR-003); a
+  single hardcoded name here would break it, and this file is where it would happen.
+- MUST NOT contain format-conversion logic — that belongs to the format base classes.
+
+`cmd_init` (the main command) is a User Story 1 deliverable and is not registered here
+yet; this skeleton carries `check` and `version` only, which is what T016 specifies.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import typer
+
+from specpro_cli.cli import cmd_init as _cmd_init
+from specpro_cli.cli import cmd_remove as _cmd_remove
+from specpro_cli.integrations import registry
+
+# FR-067 — brand header, printed on the bare invocation and before EVERY subcommand's
+# output. One constant each, defined once; the callback below is the only place the
+# header is emitted from.
+BANNER = r"""
+             ███████╗██████╗ ███████╗ ██████╗██╗███████╗██╗   ██╗
+             ██╔════╝██╔══██╗██╔════╝██╔════╝██║██╔══╝╚██╗ ██╔╝
+             ███████╗██████╔╝█████╗  ██║     ██║█████╗   ╚████╔╝
+             ╚════██║██╔═══╝ ██╔══╝  ██║     ██║██╔══╝    ╚██╔╝
+             ███████║██║     ███████╗╚██████╗██║██║        ██║
+             ╚══════╝╚═╝     ╚══════╝ ╚═════╝╚═╝╚═╝        ╚═╝
+"""
+SLOGAN = "Spec Pro - Better Spec-Driven Development Toolkit for AI Coding Agents"
+
+app = typer.Typer(
+    name="specpro",
+    help="Install specpro's distributed assets into a project, for a supported AI coding agent.",
+    # The header callback must also run on a BARE invocation; without this Click
+    # rejects the missing subcommand before the callback fires ("Missing command").
+    invoke_without_command=True,
+)
+
+
+@app.callback()
+def _header(ctx: typer.Context) -> None:
+    """Print the brand header, then dispatch.
+
+    A bare invocation (no subcommand) gets header + help — the two together are what
+    FR-067 means by "裸调用与每一个子命令的输出". `no_args_is_help` is deliberately NOT
+    used: its help path bypasses the callback, which would make the bare invocation the
+    ONE output without the header.
+    """
+    typer.echo(BANNER)
+    typer.echo(f"  {SLOGAN}")
+    typer.echo("")
+    if ctx.invoked_subcommand is None:
+        typer.echo(ctx.get_help())
+        raise typer.Exit()
+
+# ---------------------------------------------------------------------------------------
+# Registry-derived lookups — the ONLY way this layer learns about agents
+# ---------------------------------------------------------------------------------------
+
+
+def agent_keys() -> list[str]:
+    """Every selectable `--agent` value, from the registry."""
+    return registry.keys()
+
+
+def require_agent_key(key: str) -> None:
+    """Reject an unknown `--agent` value, listing the valid ones.
+
+    The list is not decoration: FR-005 requires the command to exit with the valid keys
+    named, because an agent key is not something a user can guess — it is the agent's
+    binary name, and a typo is indistinguishable from an unsupported agent without it.
+    """
+    known = agent_keys()
+    if key not in known:
+        raise typer.BadParameter(
+            f"unknown agent {key!r}. Valid keys: {', '.join(known) if known else '(none registered)'}"
+        )
+
+
+def detect_candidates(project_root: Path) -> list[str]:
+    """Agent keys whose deploy root already exists under `project_root`.
+
+    Derived from each integration's own `commands_dest()`, so the detection rule lives
+    with the integration that declares the layout — never here. FR-004 requires the
+    caller to ask the user when this returns more than one.
+    """
+    found: list[str] = []
+    for key, integration in sorted(registry.registered().items()):
+        if integration.commands_dest(project_root).parent.exists():
+            found.append(key)
+    return found
+
+
+def _package_version() -> str:
+    from importlib.metadata import PackageNotFoundError, version
+
+    try:
+        return version("specpro-cli")
+    except PackageNotFoundError:  # running from a source tree with no install
+        return "0.0.0+source"
+
+
+# ---------------------------------------------------------------------------------------
+# Commands
+# ---------------------------------------------------------------------------------------
+
+
+# The main command. Registered here rather than in `cmd_init` itself so that this file
+# stays the single place where the CLI's surface is declared — the same reason `check`
+# and `version` live here.
+app.command(name="init")(_cmd_init.cmd_init)
+app.command(name="remove")(_cmd_remove.cmd_remove)
+
+
+@app.command()
+def version() -> None:
+    """Print the installed specpro CLI version and system information (FR-069)."""
+    import platform
+    import sys
+
+    typer.echo(f"specpro-cli {_package_version()}")
+    typer.echo(f"python {sys.version.split()[0]} ({sys.executable})")
+    typer.echo(f"os {platform.system()} {platform.release()} ({platform.machine()})")
+
+
+@app.command()
+def check() -> None:
+    """Self-check: runtime preconditions and which agents are already installed here.
+
+    Read-only by construction — it must remain safe to run in any directory, including
+    one that is not a specpro project.
+    """
+    import shutil
+    import subprocess
+    import sys
+
+    typer.echo(f"specpro-cli {_package_version()}")
+    typer.echo(f"python {sys.version.split()[0]} ({sys.executable})")
+
+    # FR-068 — probe the tools the workflow itself depends on, one row per tool,
+    # present or missing NAMED (a bare count leaves the user unable to act).
+    git = shutil.which("git")
+    if git:
+        ver = subprocess.run(["git", "--version"], capture_output=True, text=True)
+        typer.echo(f"git: present — {ver.stdout.strip() or '(version not reported)'}")
+    else:
+        typer.echo("git: MISSING — install it (https://git-scm.com) — specpro commits per repository")
+
+    keys = agent_keys()
+    if keys:
+        typer.echo(f"registered agents ({len(keys)}): {', '.join(keys)}")
+    else:
+        # Not an error: the registry fills as agent modules are imported, and the
+        # skeleton ships before they exist. Saying so beats printing an empty list.
+        typer.echo("registered agents (0): none — no integration modules are imported yet")
+
+    # Each integration declares its own CLI (`cli_command`); the entry layer only
+    # probes what the registry supplies — never a hardcoded name.
+    for key in keys:
+        integration = registry.registered()[key]
+        cli = getattr(integration, "cli_command", None)
+        if cli is None:
+            typer.echo(f"{key}: IDE-only — no standalone CLI to probe")
+        elif shutil.which(cli):
+            typer.echo(f"{key}: present — {cli} on PATH")
+        else:
+            typer.echo(f"{key}: CLI MISSING — `{cli}` not on PATH (the IDE may still be usable)")
+
+    candidates = detect_candidates(Path.cwd())
+    typer.echo(f"detected in {Path.cwd()}: {', '.join(candidates) if candidates else '(none)'}")
+
+
+if __name__ == "__main__":  # pragma: no cover
+    app()

specpro_cli/integrations/__init__.py

@@ -0,0 +1,36 @@
+"""Integration layer — `IntegrationBase` + the five format base classes + one module per agent.
+
+Each agent module declares its own `key` / `config` / `registrar_config` and registers
+itself on import. Modules MUST NOT import one another (FR-003); the registration block
+below is the only place that knows they exist **as a set**.
+"""
+
+from __future__ import annotations
+
+# ---------------------------------------------------------------------------------------
+# Registration order — explicit, alphabetical, and the only list of its kind (FR-003)
+# ---------------------------------------------------------------------------------------
+#
+# ⚠️ **Why explicit imports rather than directory discovery.** A `pkgutil.iter_modules`
+# walk would make "which agents are supported" a property of the filesystem, and the
+# failure mode of a filesystem property is **a missing file**: a module that fails to
+# import, or is skipped by a bad glob, simply does not appear — and nothing reports it,
+# because at every call site an absent agent and an unsupported agent have the same
+# shape (`registry.get(key)` returns `None` for both). The explicit list converts that
+# into an `ImportError` at package-import time.
+#
+# ⚠️ **Why alphabetical.** The CLI reads the registry through `registry.keys()`, which
+# sorts, so this order does not decide what the user sees. It decides **registration**
+# order — and an unsorted list has no rule for where a new line goes, which is exactly
+# how the duplicate-key check stops being obviously complete. Alphabetical is the one
+# rule a reader can verify at a glance.
+#
+# ⚠️ **Complete as of T025**: all six first-batch agents have a module, each named on
+# its import line with the task that added it. The explicit-imports rule above stands —
+# a seventh agent lands here as a new line (alphabetical), never as directory discovery.
+from specpro_cli.integrations import claude  # noqa: F401  (registers `claude`)
+from specpro_cli.integrations import copilot  # noqa: F401  (registers `copilot`)       # T021
+from specpro_cli.integrations import cursor_agent  # noqa: F401  (registers `cursor-agent`)  # T022
+from specpro_cli.integrations import gemini  # noqa: F401  (registers `gemini`)        # T023
+from specpro_cli.integrations import opencode  # noqa: F401  (registers `opencode`)     # T024
+from specpro_cli.integrations import qodercli  # noqa: F401  (registers `qodercli`)     # T025