specpro-cli 0.1.0__py3-none-any.whl

specpro_cli/integrations/base.py

@@ -0,0 +1,601 @@
+"""`IntegrationBase` + the four format base classes.
+
+Architecture ported from spec-kit (validated on 41 agents); vocabulary narrowed to
+specpro's own templates. See `specs/contracts/agent-registry.md` for the declaration
+contract every subclass must satisfy, and `specs/plan.md` -> "Install CLI — Module
+Structure" for where this file sits.
+
+Why one file holds all five classes: `specs/plan.md`'s module tree defines
+`integrations/base` as "IntegrationBase + the five format base classes". Splitting
+them would be a design change, and this stage executes the design rather than
+revising it.
+
+**What is deliberately NOT ported from spec-kit** (recorded in `specs/research.md`
+-> Addendum): the events/hooks subsystem (`CANONICAL_TO_NATIVE`, `events_config_file`,
+`events_format`) — specpro's contract declares no such fields, and specpro ships no
+hook feature for them to drive. Porting it would add machinery with no consumer.
+"""
+
+from __future__ import annotations
+
+import shutil
+from abc import ABC
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Sequence
+
+__all__ = [
+    "IntegrationBase",
+    "IntegrationOption",
+    "MarkdownIntegration",
+    "SkillsIntegration",
+    "TomlIntegration",
+    "YamlIntegration",
+    "rewrite_project_relative_paths",
+]
+
+
+@dataclass(frozen=True)
+class IntegrationOption:
+    """A CLI option an integration accepts."""
+
+    name: str
+    is_flag: bool = False
+    required: bool = False
+    default: Any = None
+    help: str = ""
+
+
+# --------------------------------------------------------------------------------------
+# Path rewriting
+# --------------------------------------------------------------------------------------
+
+# Literal forms, applied before the regex pass so the regex cannot re-process them.
+_LITERAL_REWRITES: tuple[tuple[str, str], ...] = (
+    ("../../memory/", ".specpro/memory/"),
+    ("../../scripts/", ".specpro/scripts/"),
+    ("../../templates/", ".specpro/templates/"),
+)
+
+# ⚠️ Only the unambiguous `../../` literals are rewritten. See the docstring for why the
+# softer "bare top-level reference" pass that spec-kit also carries is deliberately absent.
+
+
+def rewrite_project_relative_paths(content: str) -> str:
+    """Rewrite repo-relative `../../<dir>/` references to their `.specpro/`-anchored form.
+
+    ⚠️ **This deliberately implements LESS than the reference implementation**, and the
+    reason is measured, not stylistic.
+
+    spec-kit additionally runs a regex pass that rewrites *bare* top-level references —
+    `(^|[\\s`"'(])(?:\\./)?scripts/` and its `memory/` / `templates/` siblings. That
+    pattern has no trailing discriminator, so it cannot tell a path from prose. Measured
+    against specpro's shipped assets it rewrites:
+
+        "temporary scripts/programs created during debugging"
+        -> "temporary .specpro/scripts/programs created during debugging"
+
+    — inside `commands/specpro.implement.md`, silently, in a file the user then reads and
+    executes. No local rule can separate `scripts/programs` (two English words) from
+    `scripts/foo.sh` (a path), so the pass cannot be made safe; it can only be removed.
+
+    Removing it costs nothing here: **no shipped specpro asset contains a bare
+    top-level reference** — specpro's commands were authored against the *install
+    target's* layout and already say `.specpro/...`. The pass's only observable effect on
+    specpro's assets is corruption. The `../../` literals are unambiguous and are kept.
+
+    See `specs/research.md` -> Addendum for the full record (chosen · rejected · why).
+    """
+    for src, dst in _LITERAL_REWRITES:
+        content = content.replace(src, dst)
+
+    # Idempotency repair: a path that already carried the prefix must not gain a second.
+    content = content.replace(".specpro/.specpro/", ".specpro/")
+    content = content.replace(".specpro.specpro/", ".specpro/")
+    return content
+
+
+def _resource_targets(project_root: Path, folder: str, subdir: str) -> Path:
+    """`<project_root>/<folder>/<subdir>`, with the escape check done by the caller."""
+    return project_root / folder / subdir
+
+
+def command_stem(template_name: str) -> str:
+    """The bare command name, with the `specpro.` prefix removed.
+
+    ⚠️ **This differs from spec-kit and the difference is load-bearing.** spec-kit's
+    source templates are named for the command alone (`plan.md`) and the target name is
+    built by *adding* a prefix (`speckit.plan.md`). specpro's source templates **already
+    carry the prefix** (`specpro.specify.md`) — they are the distributed artifacts, not
+    bare inputs. Re-adding the prefix therefore produces `specpro.specpro.specify.md`.
+    Strip first, then rebuild per format.
+    """
+    stem = Path(template_name).stem
+    prefix = "specpro."
+    return stem[len(prefix) :] if stem.startswith(prefix) else stem
+
+
+# --------------------------------------------------------------------------------------
+# Base
+# --------------------------------------------------------------------------------------
+
+
+class IntegrationBase(ABC):
+    """Base for every agent integration.
+
+    There are **no abstract methods**, deliberately (matching spec-kit, which has zero
+    `@abstractmethod` across its integration tree): "required" is enforced at runtime by
+    `commands_dest()` / `setup()` raising `ValueError`, and a half-declared subclass is
+    caught by the registry's registration check rather than by instantiation.
+
+    All state is class-level — no `__init__`, no instance attributes. That is what makes
+    the declaration-only shape possible: a new agent declares four groups of constants
+    and overrides nothing else.
+    """
+
+    # --- required declarations ---------------------------------------------------------
+    key: str = ""
+    config: dict[str, Any] | None = None
+    registrar_config: dict[str, Any] | None = None
+
+    # --- optional declarations ---------------------------------------------------------
+    invoke_separator: str = "."
+    dev_no_symlink: bool = False
+    multi_install_safe: bool = False
+    legacy_flat_command_dir: str | None = None
+    legacy_flat_command_extension: str | None = None
+
+    # --- target paths ------------------------------------------------------------------
+
+    def _require_config(self, *, need_folder: bool = True) -> dict[str, Any]:
+        if self.config is None:
+            raise ValueError(f"{type(self).__name__}: `config` MUST be declared")
+        if need_folder and not self.config.get("folder"):
+            raise ValueError(f"{type(self).__name__}: `config['folder']` MUST be declared")
+        return self.config
+
+    def commands_dest(self, project_root: Path) -> Path:
+        """Where this integration's command files land.
+
+        Reads `config` only — the entry layer MUST NOT hardcode any path, and neither
+        does this method: the deploy root is whatever the subclass declared.
+        """
+        config = self._require_config()
+        subdir = config.get("commands_subdir") or "commands"
+        return _resource_targets(project_root, config["folder"], subdir)
+
+    def command_filename(self, template_name: str) -> str:
+        """Target file name for a source template. Format subclasses override.
+
+        For the Markdown family this is the source name unchanged — specpro's templates
+        are distributed artifacts and already carry the `specpro.` prefix.
+        """
+        return f"specpro.{command_stem(template_name)}.md"
+
+    def planned_paths(self, project_root: Path, commands_dir: Path) -> list[Path]:
+        """Every path `setup()` would write, for THIS source set.
+
+        The uninstall command's removal criterion (install-cli.md → Uninstall
+        Contract) is "only paths derivable from the registry" — this method IS that
+        derivation, so uninstall removes exactly what install would have written and
+        nothing else. The default covers every one-file-per-command format; an agent
+        that writes MORE than one file per command overrides this (its `setup` already
+        knows the second path — restating the list anywhere else would be a second
+        source that drifts).
+        """
+        dest_dir = self.commands_dest(project_root)
+        return [dest_dir / self.command_filename(src.name) for src in self.list_command_templates(commands_dir)]
+
+    def deploy_roots(self, project_root: Path) -> list[Path]:
+        """The directories files land DIRECTLY in (never themselves removed).
+
+        Uninstall may clean up an emptied per-command directory (the skills layout's
+        `specpro-<stem>/`), but never a deploy root — the user's own files may live
+        there. The default is the one root every one-file format has; an agent with a
+        second location overrides this alongside `planned_paths`.
+        """
+        return [self.commands_dest(project_root)]
+
+    # --- invocation --------------------------------------------------------------------
+
+    def build_command_invocation(self, command_name: str, args: str = "") -> str:
+        """Build the agent-native invocation string for a specpro command.
+
+        `specpro.specify` -> `/specpro.specify` (base) or `/specpro-specify` (skills).
+        """
+        stem = command_name
+        if stem.startswith("specpro."):
+            stem = stem[len("specpro.") :]
+        invocation = "/specpro" + self.invoke_separator + stem
+        return f"{invocation} {args}".strip()
+
+    # --- template pipeline --------------------------------------------------------------
+
+    def arg_placeholder(self) -> str:
+        """The token that `$ARGUMENTS` / `{ARGS}` are replaced with. Overridden per format."""
+        if self.registrar_config:
+            return self.registrar_config.get("args") or "$ARGUMENTS"
+        return "$ARGUMENTS"
+
+    @staticmethod
+    def process_template(
+        content: str,
+        agent_name: str,
+        *,
+        arg_placeholder: str = "$ARGUMENTS",
+        invoke_separator: str = ".",
+    ) -> str:
+        """Resolve a command template into its deployable form.
+
+        Order matters and MUST NOT be rearranged: the argument tokens are replaced
+        before the path pass, so an argument value that happens to contain a path-like
+        string is not rewritten as though it were part of the template.
+        """
+        content = content.replace("{ARGS}", arg_placeholder)
+        content = content.replace("$ARGUMENTS", arg_placeholder)
+        content = content.replace("__AGENT__", agent_name)
+        content = rewrite_project_relative_paths(content)
+        return content
+
+    # --- deploy -------------------------------------------------------------------------
+
+    def list_command_templates(self, commands_dir: Path) -> list[Path]:
+        """Every `.md` template under `commands_dir`, sorted by file name."""
+        if not commands_dir.is_dir():
+            raise ValueError(f"{type(self).__name__}: commands dir not found: {commands_dir}")
+        return sorted(p for p in commands_dir.glob("*.md") if p.is_file())
+
+    @staticmethod
+    def write_file(content: str, dest: Path) -> Path:
+        """Write `content` as bytes.
+
+        Written as bytes rather than text so no platform newline translation is applied:
+        the deployed file must be a pure function of the source template, or the
+        reproducibility check (FR-007) compares two different things.
+        """
+        dest.parent.mkdir(parents=True, exist_ok=True)
+        dest.write_bytes(content.replace("\r\n", "\n").encode("utf-8"))
+        return dest
+
+    def setup(
+        self, project_root: Path, commands_dir: Path, *, force: bool = False
+    ) -> tuple[list[Path], list[Path]]:
+        """Deploy this integration's command files. Returns `(written, skipped)`.
+
+        The default implementation copies templates verbatim, with no placeholder
+        processing — a subclass that deploys *derived* artifacts overrides this.
+
+        ⚠️ **The conflict gate lives HERE, per file, not in the entry layer.** The
+        contract's fourth validation item (*install-cli.md* → Pre-write Validation) is
+        "逐个资产文件检查目标是否已存在" — a per-file decision at the moment of
+        writing. Judging it in the entry layer would require the entry layer to
+        enumerate every target path of every format — for the companion-file agent that
+        enumeration is a second copy of what `setup` already knows, and a format that
+        wrote an unplanned file would silently escape the check. The returned `skipped`
+        list is the report's only input for that column (`install-cli.md` → Output
+        Contract requires 每一个 skipped file named with its reason).
+        """
+        dest_dir = self.commands_dest(project_root)
+        dest_dir.mkdir(parents=True, exist_ok=True)
+        written: list[Path] = []
+        skipped: list[Path] = []
+        for src in self.list_command_templates(commands_dir):
+            dest = dest_dir / self.command_filename(src.name)
+            if dest.exists() and not force:
+                skipped.append(dest)
+                continue
+            shutil.copy2(src, dest)
+            written.append(dest)
+        return written, skipped
+
+
+# --------------------------------------------------------------------------------------
+# Format base classes
+# --------------------------------------------------------------------------------------
+
+
+class MarkdownIntegration(IntegrationBase):
+    """`<dir>/<name>.md` — one file per command, placeholder-substituted."""
+
+    def setup(
+        self, project_root: Path, commands_dir: Path, *, force: bool = False
+    ) -> tuple[list[Path], list[Path]]:
+        dest_dir = self.commands_dest(project_root)
+        dest_dir.mkdir(parents=True, exist_ok=True)
+        written: list[Path] = []
+        skipped: list[Path] = []
+        placeholder = self.arg_placeholder()
+        for src in self.list_command_templates(commands_dir):
+            dest = dest_dir / self.command_filename(src.name)
+            if dest.exists() and not force:
+                skipped.append(dest)
+                continue
+            processed = self.process_template(
+                src.read_text(encoding="utf-8"),
+                self.key,
+                arg_placeholder=placeholder,
+                invoke_separator=self.invoke_separator,
+            )
+            written.append(self.write_file(processed, dest))
+        return written, skipped
+
+
+class TomlIntegration(IntegrationBase):
+    """`<dir>/<name>.toml` — the Markdown body repackaged as a TOML `prompt` scalar."""
+
+    def command_filename(self, template_name: str) -> str:
+        return f"specpro.{command_stem(template_name)}.toml"
+
+    def arg_placeholder(self) -> str:
+        # TOML consumers substitute `{{args}}`, not the shell-style token.
+        if self.registrar_config:
+            return self.registrar_config.get("args") or "{{args}}"
+        return "{{args}}"
+
+    @staticmethod
+    def split_frontmatter(content: str) -> tuple[str, str]:
+        """`(frontmatter_body, document_body)`; `("", content)` when there is none.
+
+        Line-anchored rather than `split("---", 2)`: a frontmatter value may itself
+        contain `---`, and splitting on the literal truncates it mid-value.
+        """
+        lines = content.split("\n")
+        if not lines or lines[0].strip() != "---":
+            return "", content
+        for idx in range(1, len(lines)):
+            if lines[idx].strip() == "---":
+                return "\n".join(lines[1:idx]), "\n".join(lines[idx + 1 :])
+        return "", content
+
+    @staticmethod
+    def extract_description(frontmatter: str) -> str:
+        """The `description:` value, or `""`.
+
+        Parsed from the raw frontmatter so block scalars (`|` / `>`) keep their meaning.
+
+        ⚠️ **A missing `yaml` degrades to `""` rather than raising** — this is the
+        fallback installer's dependency contract (T032): an environment without the
+        third-party stack can still install, at the honest cost of a description-less
+        header (the skills frontmatter then carries its `specpro: <stem> workflow`
+        placeholder). Raising here would make the FIRST import failure abort an install
+        that everything else can complete.
+        """
+        if not frontmatter.strip():
+            return ""
+        try:
+            import yaml
+        except ImportError:
+            return ""
+        try:
+            data = yaml.safe_load(frontmatter)
+        except yaml.YAMLError:
+            return ""
+        if isinstance(data, dict) and isinstance(data.get("description"), str):
+            return data["description"]
+        return ""
+
+    @staticmethod
+    def render_toml_string(value: str) -> str:
+        """Render `value` as a TOML string, choosing the cheapest safe form."""
+        if "\n" not in value and "\r" not in value:
+            return '"' + value.replace("\\", "\\\\").replace('"', '\\"') + '"'
+        escaped = value.replace("\\", "\\\\")
+        if '"""' not in escaped:
+            if escaped.endswith('"'):
+                # A value ending in a quote would close the multiline delimiter.
+                return '"""\n' + escaped + '\\\n"""'
+            return '"""\n' + escaped + '"""'
+        if "'''" not in value and not value.endswith("'"):
+            return "'''\n" + value + "'''"
+        return '"' + value.replace("\\", "\\\\").replace('"', '\\"').replace("\n", "\\n") + '"'
+
+    @classmethod
+    def render_toml(cls, description: str, body: str) -> str:
+        """`description` line, blank line, `prompt` block. Empty description omits its line."""
+        parts: list[str] = []
+        if description:
+            parts.append(f"description = {cls.render_toml_string(description)}")
+            parts.append("")
+        parts.append(f"prompt = {cls.render_toml_string(body.rstrip(chr(10)))}")
+        return "\n".join(parts) + "\n"
+
+    def setup(
+        self, project_root: Path, commands_dir: Path, *, force: bool = False
+    ) -> tuple[list[Path], list[Path]]:
+        dest_dir = self.commands_dest(project_root)
+        dest_dir.mkdir(parents=True, exist_ok=True)
+        written: list[Path] = []
+        skipped: list[Path] = []
+        placeholder = self.arg_placeholder()
+        for src in self.list_command_templates(commands_dir):
+            dest = dest_dir / self.command_filename(src.name)
+            if dest.exists() and not force:
+                skipped.append(dest)
+                continue
+            raw = src.read_text(encoding="utf-8")
+            frontmatter, _ = self.split_frontmatter(raw)
+            description = self.extract_description(frontmatter)
+            processed = self.process_template(
+                raw, self.key, arg_placeholder=placeholder, invoke_separator=self.invoke_separator
+            )
+            _, body = self.split_frontmatter(processed)
+            written.append(self.write_file(self.render_toml(description, body), dest))
+        return written, skipped
+
+
+class YamlIntegration(IntegrationBase):
+    """`<dir>/<name>.yaml` — header mapping plus the body as a block scalar."""
+
+    def command_filename(self, template_name: str) -> str:
+        return f"specpro.{command_stem(template_name)}.yaml"
+
+    def arg_placeholder(self) -> str:
+        if self.registrar_config:
+            return self.registrar_config.get("args") or "{{args}}"
+        return "{{args}}"
+
+    @staticmethod
+    def split_frontmatter(content: str) -> tuple[str, str]:
+        return TomlIntegration.split_frontmatter(content)
+
+    @staticmethod
+    def render_yaml(description: str, body: str, source_name: str) -> str:
+        """Header, then the body as a literal block scalar.
+
+        The `|2` indent indicator is written **explicitly**: with a bare `|` YAML infers
+        the indent from the first non-empty line, and a body whose first line is itself
+        indented (a code block, a nested list) parses as an error.
+        """
+        import yaml
+
+        header = {
+            "version": "1.0.0",
+            "description": description,
+            "parameters": [
+                {
+                    "key": "args",
+                    "input_type": "string",
+                    "requirement": "optional",
+                    "default": "",
+                    "description": "User input passed to the command.",
+                }
+            ],
+        }
+        header_text = yaml.safe_dump(header, sort_keys=False, allow_unicode=True).rstrip("\n")
+        indented = "\n".join(("  " + line) if line else "" for line in body.split("\n"))
+        return f"{header_text}\nprompt: |2\n{indented}\n\n# Source: {source_name}\n"
+
+    def setup(
+        self, project_root: Path, commands_dir: Path, *, force: bool = False
+    ) -> tuple[list[Path], list[Path]]:
+        dest_dir = self.commands_dest(project_root)
+        dest_dir.mkdir(parents=True, exist_ok=True)
+        written: list[Path] = []
+        skipped: list[Path] = []
+        placeholder = self.arg_placeholder()
+        for src in self.list_command_templates(commands_dir):
+            dest = dest_dir / self.command_filename(src.name)
+            if dest.exists() and not force:
+                skipped.append(dest)
+                continue
+            raw = src.read_text(encoding="utf-8")
+            frontmatter, _ = self.split_frontmatter(raw)
+            description = TomlIntegration.extract_description(frontmatter)
+            processed = self.process_template(
+                raw, self.key, arg_placeholder=placeholder, invoke_separator=self.invoke_separator
+            )
+            _, body = self.split_frontmatter(processed)
+            written.append(
+                self.write_file(self.render_yaml(description, body, src.name), dest)
+            )
+        return written, skipped
+
+
+class SkillsIntegration(IntegrationBase):
+    """`<dir>/<skill-name>/SKILL.md` — one directory per command.
+
+    Declares `invoke_separator = "-"`: under a skills layout the invocation name is the
+    **directory name**, so `/specpro.specify` becomes `/specpro-specify`.
+    """
+
+    invoke_separator: str = "-"
+
+    def skills_dest(self, project_root: Path) -> Path:
+        config = self._require_config()
+        subdir = config.get("commands_subdir") or "skills"
+        return _resource_targets(project_root, config["folder"], subdir)
+
+    def command_filename(self, template_name: str) -> str:
+        return f"specpro-{command_stem(template_name).replace('.', '-')}/SKILL.md"
+
+    def build_command_invocation(self, command_name: str, args: str = "") -> str:
+        stem = command_name
+        if stem.startswith("specpro."):
+            stem = stem[len("specpro.") :]
+        invocation = "/specpro-" + stem.replace(".", "-")
+        return f"{invocation} {args}".strip()
+
+    def skill_frontmatter_extra(
+        self, stem: str, description: str, source_name: str
+    ) -> list[str]:
+        """Extra frontmatter lines this agent wants on every skill. Default: none.
+
+        This hook exists because the contract names it: `agent-registry.md` →
+        「每个集成模块必须声明」→ **子类方法覆写** = "agent 特有的内容加工（如
+        argument-hints）", and the agent that needs it is `claude`.
+
+        The split matters: the *common* part of the header stays in
+        `build_skill_frontmatter`, and an agent that needs more overrides **this** — so
+        adding an agent never means editing the shared builder. That is the same reason
+        the five format bases exist, one level down.
+        """
+        return []
+
+    @staticmethod
+    def build_skill_frontmatter(
+        stem: str,
+        description: str,
+        source_name: str,
+        extra_lines: Sequence[str] = (),
+    ) -> str:
+        """The five-field skill header, plus whatever the agent adds.
+
+        Every value is double-quoted: an unquoted scalar cannot carry the line breaks,
+        leading `>`/`|`, or control characters that a description may contain.
+
+        `extra_lines` is appended **after** the `metadata` block and **before** the
+        closing `---`: appending after a block scalar keeps the five shared fields
+        contiguous, and the extras are top-level keys, which is where the agent's own
+        field belongs.
+        """
+        import json
+
+        def quote(value: str) -> str:
+            return json.dumps(value, ensure_ascii=False)
+
+        lines = [
+            "---",
+            f"name: {quote('specpro-' + stem)}",
+            f"description: {quote(description or f'specpro: {stem} workflow')}",
+            f"compatibility: {quote('Requires a specpro project structure with .specpro/ directory')}",
+            "metadata:",
+            "  author: specpro",
+            f"  source: {quote(source_name)}",
+            *extra_lines,
+            "---",
+            "",
+        ]
+        return "\n".join(lines)
+
+    def setup(
+        self, project_root: Path, commands_dir: Path, *, force: bool = False
+    ) -> tuple[list[Path], list[Path]]:
+        dest_dir = self.skills_dest(project_root)
+        dest_dir.mkdir(parents=True, exist_ok=True)
+        written: list[Path] = []
+        skipped: list[Path] = []
+        placeholder = self.arg_placeholder()
+        for src in self.list_command_templates(commands_dir):
+            dest = dest_dir / self.command_filename(src.name)
+            if dest.exists() and not force:
+                skipped.append(dest)
+                continue
+            raw = src.read_text(encoding="utf-8")
+            frontmatter, _ = self.split_frontmatter(raw)
+            description = TomlIntegration.extract_description(frontmatter)
+            processed = self.process_template(
+                raw, self.key, arg_placeholder=placeholder, invoke_separator=self.invoke_separator
+            )
+            _, body = self.split_frontmatter(processed)
+            content = self.build_skill_frontmatter(
+                command_stem(src.name),
+                description,
+                src.name,
+                self.skill_frontmatter_extra(command_stem(src.name), description, src.name),
+            ) + body
+            written.append(self.write_file(content, dest))
+        return written, skipped
+
+    @staticmethod
+    def split_frontmatter(content: str) -> tuple[str, str]:
+        return TomlIntegration.split_frontmatter(content)