specpro-cli 0.1.0__py3-none-any.whl

specpro_cli/assets/templates/test-tasks-template.md

@@ -0,0 +1,174 @@
+---
+description: "Template for high-level test tasks (integration / component E2E / app E2E) generated by /specpro-test-plan"
+---
+
+# High-Level Test Tasks: [FEATURE NAME]
+
+**Input**: spec.md (FR full set + Acceptance Scenarios + NFR performance metrics), tasks.md (FR→task mapping, module paths), plan.md (Risk-Based Quality Assurance classification, Quality Targets), the ACTUAL codebase (grounding scan)
+**Prerequisites**: spec.md (required), plan.md (recommended), tasks.md (recommended)
+**Executor**: `/specpro-test-implement`
+**Scope Boundary**:
+- **Unit tests are OUT of scope for this file** — unit tests are owned by tasks.md (including `core/src` embedded unit tests, registered into the matrix by the grounding scan)
+- **Manual acceptance is OUT of scope for this file** — subjective/exploratory scenarios are routed to `/specpro-manual-test` (manual-test-tasks.md)
+
+**Artifact Language Rule** 🌐: prose content (descriptions, rationales, scenario text) follows the project's Artifact Language setting; structural anchors — section headings below, task ID prefixes (INF/IT/CE/AE), FR/US IDs, the status enum, and table column names — are ALWAYS English, exactly as written in this template. **Entry field labels are anchors too** (`source:`, `Evidence:`, `Fix Direction:`) — never translated: they exist to be searched, and a translated label drops out of every consumer's scan.
+
+**Test-plan Runs** (append one entry per `/specpro-test-plan` run; isomorphic to spec.md Revision History):
+- [test-plan:create YYYY-MM-DD] full mode, [N] FRs, [M] tasks
+<!-- Incremental run examples:
+- [test-plan:incremental YYYY-MM-DD] FR-xxx(Modified) → IT-004 rewritten; FR-yyy(deleted) → row deprecated
+-->
+
+---
+
+## Coverage Matrix (built BEFORE any task generation)
+
+**⚠️ CRITICAL**: one row per FR; every uncovered cell MUST carry a rationale (e.g., "pure UI, app-level" or "covered by tasks.md T-xxx unit tests") — never leave a cell blank.
+
+| FR | Domain | Unit | Integration | Component E2E | App E2E | Task IDs | Status |
+|----|--------|------|-------------|---------------|---------|----------|--------|
+| FR-xxx | handshake | tasks.md T-xxx unit coverage | IT-001 | CE-001 | AE-001 | IT-001, CE-001 | not-started |
+| FR-xxx | decode | core/src XxxDecoderTest | IT-002 | — (byte-level only, integration) | AE-001 | IT-002 | not-started |
+| FR-xxx | UI layout | — (pure UI logic, low risk) | — (pure UI, app-level) | — (no standalone component chain) | AE-003 | AE-003 | not-started |
+| FR-xxx | YAML config | PluginConfigurationTest | — (scripted file IO adds little value) | — | — | — (unit coverage sufficient) | not-applicable |
+| FR-xxx | feature not yet implemented | pending-impl | pending-impl | pending-impl | pending-impl | - | pending-impl |
+
+**Column notes**:
+- **Unit**: register existing tasks.md unit tasks or `core/src` embedded tests (grounding scan output); this file NEVER creates new unit tasks
+- **Integration / Component E2E / App E2E**: task IDs; when not applicable a rationale is MANDATORY
+- **Task IDs**: consolidated IDs of this file's tasks hooked to the FR (updated in sync during execution)
+- **Status** (single execution semantics; writers and triggers per the evolution rules below):
+  * `pending-impl` (no implementation component yet — **generate NO tasks**, never test things that don't exist) — test-plan planning verdict, immutable during execution
+  * `manual` (routed to `/specpro-manual-test`, with the subjective REMNANT named in the rationale) — test-plan planning verdict, immutable during execution. **Prerequisite (FR-065)**: before routing an FR here, automation MUST first be ruled out — evaluate the criterion body against the project's mechanical carriers (text-criterion assertions · extract-and-run of in-doc executable bodies · behavioural replay); every mechanically checkable part MUST get an IT row, and the `manual` row carries ONLY the subjective remnant, named concretely. "No unit execution body" alone MUST NOT justify this routing
+  * `not-applicable` (unit coverage sufficient, no high-level task needed) — test-plan planning verdict, immutable during execution
+  * `not-started` → `in-progress` → `completed` — advanced by `/specpro-test-implement` (derived from task checkboxes); a parenthetical annotation is allowed for refinement (e.g., `not-started (decode sub-item pending)`) — statistics MUST stay compatible
+  * `deprecated` (FR deleted from spec; row kept for traceability, hooked tasks marked `[DELETED]`) — test-plan incremental write
+
+**Status evolution rules** (who changes which value when):
+
+| Status | Writer | Trigger |
+|--------|--------|---------|
+| pending-impl / manual / not-applicable | `/specpro-test-plan` | Planning verdict (grounding scan + layer assignment), immutable during execution |
+| not-started → in-progress → completed | `/specpro-test-implement` | Checkbox-derived: ALL hooked tasks `[x]` → `completed`; SOME → `in-progress`; failures never advance |
+| deprecated | `/specpro-test-plan` (incremental) | FR deleted from spec (SpecStatus=delete) |
+
+**Matrix Change Log** (the processing record for incremental mode; every re-processed FR is logged here — rows absent from the log are unchanged since the last run):
+
+| Date | FR | Change | Trigger | Affected tasks |
+|------|-----|--------|---------|----------------|
+| YYYY-MM-DD | all | create | initial generation | (task ID range) |
+<!-- Incremental examples:
+| YYYY-MM-DD | FR-xxx | update | spec FR-xxx modified (priority adjusted) | IT-004 rewritten in place |
+| YYYY-MM-DD | FR-yyy | delete | FR-yyy removed from spec | row deprecated; IT-011 [DELETED] |
+-->
+<!-- Task removal convention (same as tasks.md): when a spec change invalidates a task, mark `[DELETED]` without physical removal; the next incremental run cleans up -->
+<!-- Incremental generation rule: NO multi-phase Lifecycle markers on rows in this file — execution progress derives from task checkboxes (the Status column is a readable summary); planning generations are carried by "Test-plan Runs + Matrix Change Log" -->
+
+**Layer assignment rules** (detail in the `/specpro-test-plan` command):
+- **Integration**: peer behavior deterministically simulated with byte sequences / scripts
+- **Component E2E**: depends on real peer quirks / timing / performance / concurrency scale
+- **App E2E**: app assembly, UI rendering chain, input-to-display
+- **Subjective/exploratory**: routed to `/specpro-manual-test` (manual) — ONLY after automation is ruled out per FR-065 (mechanical parts → IT rows; the manual row names the subjective remnant)
+
+---
+
+## Peer Diversity Registry [only for protocol / wire-format modules]
+
+**Purpose**: the authoritative, closed set of **measured** peer behaviours. Any test expectation that asserts "peer X behaves as Y" MUST trace to a row here. **Absence means unmeasured — unmeasured peer behaviour MUST NOT be frozen into an expectation.**
+
+| Peer | Version | Measured behaviour | Basis (how it was measured) | Date | Affects |
+|------|---------|--------------------|------------------------------|------|---------|
+| [peer] | [version] | [observed behaviour, including quirks] | [capture / probe / reference implementation] | YYYY-MM-DD | [FR-xxx / task ID] |
+
+<!-- The KIND of difference this registry exists to record: an optional field present in one
+     implementation and absent in another; compile-time options that change wire output;
+     environment-dependent behaviour. Record what was MEASURED for your peers — do not copy
+     these examples as facts. -->
+
+**Ownership**: written ONLY by `/specpro-test-plan` (same boundary as the coverage matrix and the two logs). Differences discovered while executing tests are reported by `/specpro-test-implement` and registered on the next incremental `test-plan` run.
+
+**Audited by**: `analyze` Pass L5 — an expectation that asserts peer behaviour with no row here is a finding.
+
+---
+
+## Test Infrastructure Tasks (INF-xxx, first)
+
+**⚠️ INF tasks MUST complete before ALL test tasks** (e.g., mock servers, test container manifests, test fixtures). INF tasks carry NO FR annotation.
+
+- [ ] INF-001 [infra] Build an in-process mock server (supports 003.003/003.007/003.008 version branches)
+    Location: tests/integration-test/src/jvmTest/fixtures/MockPeerServer.kt
+    Purpose: byte-level scriptable mock peer for IT tasks
+    Validates: replays handshake / security-type / encoding-negotiation byte sequences per script
+
+---
+
+## Integration Test Tasks (IT-xxx, grouped by scenario/domain)
+
+### [handshake]
+
+- [ ] IT-001 [handshake] protocol version-branch handshake (FR-xxx)
+    Location: tests/integration-test/src/jvmTest/kotlin/.../VersionMatrixIT.kt
+    Source: mock server returns 003.003/003.007/003.008; assert the client uses the matching security handshake format
+    Mock: in-process ServerSocket mock server
+    <!-- Optional extensions: Test Cases / Risk Level / Execution Time(<30s) / CI/CD -->
+
+### [encoding-negotiation]
+
+<!-- - [ ] IT-002 [encoding-negotiation] ... (FR-xxx) -->
+
+---
+
+## Component E2E Tasks (CE-xxx)
+
+- [ ] CE-001 [connection-matrix] Real-server auth + full encoding flow (FR-xxx, FR-yyy)
+    Location: tests/e2e-test/src/test/kotlin/.../RealServerConnectionE2ETest.kt
+    Environment: Docker + container manifest (e.g., docker-compose.test.yml)
+    Setup: 1. start the server container 2. @BeforeAll port probing, assumeTrue-skip when unavailable
+    Validates: handshake → auth → encoding negotiation → first-frame decode completes against a REAL peer
+    Teardown: 1. stop and remove containers
+    Performance: first frame <2s (optional; REQUIRED only when a corresponding NFR exists)
+
+---
+
+## Application E2E Tasks (AE-xxx)
+
+- [ ] AE-001 [assembly] App startup → connect → remote screen rendering (FR-xxx, FR-yyy)
+    Location: tests/e2e-test/src/test/kotlin/.../AppAssemblyE2ETest.kt
+    Environment: Desktop app build artifact (grounded build command; launch mechanism + display environment, virtual display for headless) + Docker server
+    Setup: 1. build the app 2. start the server container 3. port-probe guard 4. launch the app
+    Validates: the full input-event-to-screen-display chain (app assembly + UI rendering)
+    Teardown: 1. close the app 2. clean up containers
+    Performance: input-to-display <500ms (optional; REQUIRED only when a corresponding NFR exists)
+
+---
+
+## Progress Statistics
+
+| Layer | Total | Done | Rate |
+|-------|-------|------|------|
+| Infra (INF) | 0 | 0 | 0% |
+| Integration (IT) | 0 | 0 | 0% |
+| Component E2E (CE) | 0 | 0 | 0% |
+| App E2E (AE) | 0 | 0 | 0% |
+| **Total** | 0 | 0 | 0% |
+
+**Matrix coverage**: 0 FRs registered / 0 pending-impl / 0 manual
+
+<!--
+  ============================================================================
+  Execution rules (for /specpro-test-implement):
+  1. Execution order: INF → IT → CE → AE (default when the matrix declares no explicit dependencies)
+  2. Per completed task: check [x] AND sync the Coverage Matrix "Task IDs/Status" columns plus Progress Statistics
+  3. When the E2E environment is unavailable, SKIP via the assumeTrue guard — count as skip, not fail
+  4. A failed task is NEVER checked [x]; its matrix status stays not-started / in-progress
+  5. Cells routed to manual are annotated with /specpro-manual-test coverage
+  6. Only advance not-started / in-progress → completed; NEVER touch pending-impl / manual / not-applicable / deprecated rows (planning verdicts belong to test-plan)
+  7. Tasks marked [DELETED] are skipped during execution
+  8. Execution NEVER writes "Matrix Change Log" or "Test-plan Runs" — both logs are owned by /specpro-test-plan
+
+  Iteration rules (for /specpro-test-plan incremental mode):
+  9. Incremental scope = FRs logged in the Matrix Change Log ∪ FRs with changed SpecStatus in spec.md ∪ new grounding-scan findings;
+     all other matrix rows carry over verbatim (rationales, task IDs, statuses)
+  10. FR deleted → row deprecated, tasks marked [DELETED]; FR modified → row re-adjudicated, tasks rewritten in place (numbering NEVER resets)
+  ============================================================================
+-->

specpro_cli/cli/__init__.py

@@ -0,0 +1,5 @@
+"""Entry layer — argument parsing and flow orchestration.
+
+Holds no agent names, paths, or format knowledge: those live in `integrations/`
+and are reached only through the registry (see specs/plan.md -> Pattern 2).
+"""

specpro_cli/cli/cmd_init.py

@@ -0,0 +1,416 @@
+"""`specpro init` — deploy specpro's assets into a target project.
+
+`specs/contracts/install-cli.md` fixes this module's job and the order it must run in.
+Three rules from that contract drive the shape below:
+
+- **全部校验通过才开始落盘** (§ Pre-write Validation). Every check runs before the first
+  write, because a failure part-way through leaves a half-installed project — the one
+  outcome the ordering exists to prevent.
+- **第 4 项不中止** (same section). A file conflict is *skipped and reported*, never
+  fatal: a user who edited one of twenty files must still receive the other nineteen.
+- **入口层 MUST NOT 硬编码任何 agent 名、路径或格式** (§ 入口层的职责边界). Every name and
+  every path is queried from the registry, so "add an agent = add one subclass" stays
+  true (FR-003). This file is where a hardcoded name would break that.
+
+**Scope of this revision**: the flow skeleton, the pre-write validation block (all four
+items — T027's two checks were part of the skeleton), candidate detection (T026), the
+per-file conflict gate with its `--force` override (T028, delegated to `setup`), and the
+output-contract report (T029). Still open: the uninstall path (T031 — held pending a
+contract-level ruling on its command interface) and the in-repo fallback install path
+(T032, `tools/install/fallback/`).
+"""
+
+from __future__ import annotations
+
+import shutil
+import sys
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+import typer
+
+from specpro_cli.integrations import registry
+
+if TYPE_CHECKING:  # pragma: no cover
+    from specpro_cli.integrations.base import IntegrationBase
+
+# The floor declared in `pyproject.toml` (`requires-python`). Repeated here as a value
+# rather than read from package metadata, because the check must also work in a source
+# checkout where no distribution is installed.
+_MIN_PYTHON = (3, 11)
+
+
+# ---------------------------------------------------------------------------------------
+# Pre-write validation — steps 1–3 of the contract's four
+# ---------------------------------------------------------------------------------------
+
+
+def _check_runtime() -> None:
+    """Step 1 — the CLI's own runtime prerequisite (FR-002, 宪法 2.3).
+
+    ⚠️ **This runs before anything else and exits rather than warns.** 宪法 2.3 states
+    the enforcement point literally: a missing runtime dependency MUST exit before any
+    file is written, with the exact command that installs it. A warning would leave the
+    user inside an install that is about to fail at some later, less legible point.
+
+    The message names a command, not advice — 「请安装 Python 3.11+」 is a description of a
+    state, and the contract asks for the action that reaches it. The interpreter is named
+    per platform because the name genuinely differs.
+    """
+    if sys.version_info[:2] >= _MIN_PYTHON:
+        return
+
+    have = ".".join(str(p) for p in sys.version_info[:3])
+    want = ".".join(str(p) for p in _MIN_PYTHON)
+    if sys.platform.startswith("win"):
+        command = f"py -{want} -m pip install --upgrade specpro-cli"
+        alternative = f"winget install Python.Python.{want}"
+    else:
+        command = f"python{want} -m pip install --upgrade specpro-cli"
+        alternative = "brew install python@3.11" if sys.platform == "darwin" else \
+            "sudo apt install python3.11 python3.11-venv"
+    _abort(
+        f"specpro needs Python {want} or newer; this is {have}.",
+        "No files were written.",
+        f"Install it with:  {command}",
+        f"Or get the interpreter first:  {alternative}",
+    )
+
+
+def _resolve_agent(explicit: str, project_root: Path) -> IntegrationBase:
+    """Step 2 — pick the integration to install for.
+
+    With `--agent` given, the key must be registered (FR-005: an unknown key aborts
+    with the full valid set printed, not merely referred to — a key is the agent's
+    binary name, and a typo is indistinguishable from an unsupported agent without
+    the list).
+
+    Without it, detection runs (T026): exactly one hit installs for that agent;
+    several hits abort and demand an explicit choice, because "guess, then silently
+    install into the wrong agent's directory" is precisely the failure FR-004 exists
+    to prevent; zero hits aborts with the registered set, which is the honest report
+    when nothing on disk names a supported agent.
+
+    ⚠️ **The detection walk is `entry.detect_candidates`, not a second copy.** The
+    entry module already owns that lookup (with its own tests); importing it here —
+    lazily, since `entry` imports this module to register the command — keeps one
+    detection rule. A duplicated walk would drift the first time someone tuned one
+    of them.
+    """
+    if not explicit:
+        # Deferred import: `entry` imports this module at load time (the command
+        # registration), so the import must wait until both modules are loaded.
+        from specpro_cli.cli.entry import detect_candidates
+
+        keys = registry.keys()
+        candidate_keys = detect_candidates(project_root)
+        if len(candidate_keys) == 1:
+            only = registry.get(candidate_keys[0])
+            if only is not None:  # pragma: no cover — detect_candidates reads the same map
+                display = (only.config or {}).get("name") or only.key
+                typer.secho(
+                    f"detect: found {only.key} ({display}) — installing for it "
+                    "(pass --agent to override)",
+                    fg=typer.colors.CYAN,
+                    err=True,
+                )
+                return only
+        if len(candidate_keys) > 1:
+            _abort(
+                "several agents detected in this project — specpro will not pick one.",
+                "Detected: " + ", ".join(candidate_keys),
+                f"All registered keys: {', '.join(keys) if keys else '(none imported yet)'}",
+                "Re-run with:  specpro init --agent <key>",
+            )
+        _abort(
+            "no --agent given, and no supported agent detected in this project.",
+            f"Registered agent keys: {', '.join(keys) if keys else '(none imported yet)'}",
+            "Re-run with:  specpro init --agent <key>",
+        )
+    integration = registry.get(explicit)
+    if integration is None:
+        keys = registry.keys()
+        _abort(
+            f"unknown agent {explicit!r}.",
+            f"Valid keys: {', '.join(keys) if keys else '(none imported yet)'}",
+            # FR-005: the valid set is printed, not merely referred to. An agent key is
+            # the agent's binary name — a typo is indistinguishable from an unsupported
+            # agent without the list.
+        )
+    return integration
+
+
+def _check_writable(integration: IntegrationBase, project_root: Path) -> Path:
+    """Step 3 — the deploy root can be created, or exists and is writable.
+
+    Checked by *attempting* the mkdir rather than by inspecting permissions: permission
+    bits do not decide writability on every filesystem (ACLs, read-only mounts, Windows),
+    so an inspection would report "writable" for paths the following write would reject.
+    The `mkdir` is the only side effect this command performs before the full validation
+    block has passed, and it is idempotent — it creates an empty directory at the
+    integration's own declared root, never a file.
+    """
+    dest = integration.commands_dest(project_root)
+    try:
+        dest.mkdir(parents=True, exist_ok=True)
+    except OSError as exc:
+        _abort(
+            f"cannot create the deploy root: {dest}",
+            f"Reason: {exc}",
+            "No files were written.",
+        )
+    if not dest.is_dir():
+        _abort(f"deploy root is not a directory: {dest}", "No files were written.")
+    return dest
+
+
+# ---------------------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------------------
+
+
+def _is_interactive() -> bool:
+    """Whether prompts may be shown (FR-070/FR-071 TTY guard). Module-level so tests
+    can inject it — CliRunner replaces `sys.stdin` wholesale, so patching the stream's
+    own `isatty` never lands."""
+    return sys.stdin.isatty()
+
+
+def _abort(message: str, *detail_lines: str) -> None:
+    """Report a blocking condition and exit non-zero. Writes nothing — by construction.
+
+    Every caller of this function runs inside the pre-write validation block, so "abort"
+    and "leave the project untouched" are the same act.
+    """
+    typer.secho(f"✗ {message}", fg=typer.colors.RED, err=True)
+    for line in detail_lines:
+        typer.secho(f"  {line}", err=True)
+    raise typer.Exit(code=1)
+
+
+def assets_commands_dir(source: Path | None = None) -> Path:
+    """Where the command templates are read from.
+
+    `--source` wins when given (development and verification against a checkout).
+    Otherwise the snapshot baked into the wheel at build time is used. ⚠️ **The built-in
+    snapshot MUST stay the default**: making `--source` the default would put installation
+    back on a network or a checkout, which is the entire reason the snapshot exists
+    (`install-cli.md` → `## Asset Sourcing` → `### Explicitly Ruled Out`).
+    """
+    if source is not None:
+        root = source.expanduser().resolve()
+        # A `--source` may point either at a repository root (which contains
+        # `commands/`) or directly at a commands directory. Both are accepted; there is
+        # no third form, so no further guessing.
+        return root / "commands" if (root / "commands").is_dir() else root
+
+    from importlib.resources import files
+
+    return Path(str(files("specpro_cli"))) / "assets" / "commands"
+
+
+# FR-066 — the deployment directory for the template/script support groups.
+# T258 lands the NEW name directly (plan.md → CLI UX & Deployment Layout: the
+# three-group expansion and the global rename land in the same round, so the
+# support groups never live under the old name).
+SUPPORT_DIR_NAME = ".specpro"
+
+
+def _repo_root_form(source: Path) -> bool:
+    """A `--source` pointing at a repository root (vs. directly at a commands dir)."""
+    return (source / "commands").is_dir()
+
+
+def _assets_group_dir(group: str, source: Path | None) -> Path | None:
+    """Source of one support group (`templates`, `scripts/bash`).
+
+    Snapshot mode: `specpro_cli/assets/<group>` (always present — the wheel bakes
+    all three groups). `--source` repository-root mode: `<root>/<group>`.
+    A `--source` pointing DIRECTLY at a commands directory provides no support
+    groups — that form promises only commands — so this returns None there and the
+    caller reports the groups as not provided instead of aborting (the two origins
+    are the only two shapes; there is no third form to guess).
+    """
+    if source is None:
+        from importlib.resources import files
+
+        return Path(str(files("specpro_cli"))) / "assets" / group
+    root = source.expanduser().resolve()
+    return root / group if _repo_root_form(root) else None
+
+
+def _deploy_verbatim(src: Path, dest: Path, *, force: bool) -> tuple[list[Path], list[Path]]:
+    """Copy one support group byte-for-byte. Returns `(written, skipped)`.
+
+    Templates and scripts are the byte-identical tier (FR-007) — no format
+    processing here, mirroring the layering rule that keeps format conversion in
+    the integration base class. The per-file conflict gate matches `setup()`'s:
+    an existing file without `--force` is skipped and named, never silently
+    overwritten.
+    """
+    written: list[Path] = []
+    skipped: list[Path] = []
+    for f in sorted(src.rglob("*")):
+        if not f.is_file():
+            continue
+        target = dest / f.relative_to(src)
+        if target.exists() and not force:
+            skipped.append(target)
+            continue
+        target.parent.mkdir(parents=True, exist_ok=True)
+        shutil.copy2(f, target)
+        written.append(target)
+    return written, skipped
+
+
+# ---------------------------------------------------------------------------------------
+# The command
+# ---------------------------------------------------------------------------------------
+
+
+def cmd_init(
+    path: Path = typer.Argument(
+        Path("."),
+        help="Target project root.",
+        show_default=False,
+    ),
+    agent: str = typer.Option(
+        "", "--agent", help="Target agent key (default: detect from the project)."
+    ),
+    force: bool = typer.Option(
+        False, "--force", help="Overwrite files that already exist."
+    ),
+    source: Path | None = typer.Option(
+        None, "--source", help="Read assets from this path instead of the built-in snapshot."
+    ),
+) -> None:
+    """Deploy specpro into a project, for one AI coding agent."""
+    project_root = path.expanduser().resolve()
+
+    # --- interactive gating (TTY only) ---------------------------------------------------
+    # FR-070 / FR-071. A prompt MUST NOT hang a non-TTY run (scripts/CI): there the
+    # flow falls through to the explicit-argument rules below (--agent given, or the
+    # detection/abort logic of FR-004/FR-005).
+    interactive = _is_interactive()
+    if interactive:
+        typer.echo(f"target project: {project_root}")
+        if not typer.confirm("initialize specpro here?", default=True):
+            typer.echo("Aborted — cd to the target project and re-run. Nothing was written.")
+            raise typer.Exit()
+        if not agent:
+            # Registry-driven numbered list; this layer still hardcodes no name.
+            keys = sorted(registry.registered().keys())
+            if keys:
+                typer.echo("select the AI coding agent:")
+                for i, key in enumerate(keys, 1):
+                    typer.echo(f"  {i}. {key}")
+                choice = typer.prompt("number", default=1, type=int)
+                if not 1 <= choice <= len(keys):
+                    _abort(f"selection {choice} is out of range 1..{len(keys)}")
+                agent = keys[choice - 1]
+
+    # --- pre-write validation: all of it, before any of the writing ---------------------
+    _check_runtime()                                           # 1  FR-002
+    integration = _resolve_agent(agent, project_root)          # 2  FR-004 / FR-005
+    dest = _check_writable(integration, project_root)          # 3  FR-005
+
+    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 is created at build time; in a source checkout "
+            "pass --source <path-to-repository-root>.",
+            "No files were written.",
+        )
+
+    # FR-001 — the install entry deploys ALL THREE groups in one invocation
+    # (commands via the integration, templates and support scripts via the
+    # `.specpro/` support directory). Every source is resolved HERE, in the
+    # pre-write block: an abort after the commands group had landed would break
+    # the zero-writes promise in the other direction.
+    support_groups: list[tuple[str, Path, Path | None]] = []
+    for group in ("templates", "scripts/bash"):
+        src = _assets_group_dir(group, source)
+        # ⚠️ `group_dest`, NOT `dest` — `dest` is the integration's deploy root returned
+        # by `_check_writable` above and printed in the report; shadowing it here made
+        # `deployed to:` name the last support group (caught by T258's own test).
+        group_dest = project_root / SUPPORT_DIR_NAME / group
+        if src is not None and not src.is_dir():
+            _abort(
+                f"{group} assets not found at {src}",
+                "The built-in snapshot is created at build time; in a source checkout "
+                "pass --source <path-to-repository-root>.",
+                "No files were written.",
+            )
+        support_groups.append((group, group_dest, src))
+
+    # --- deploy -------------------------------------------------------------------------
+    # ⚠️ **The writing is the integration's, not this layer's.** `install-cli.md` →
+    # 「入口层的职责边界」 puts it in one line: *MUST NOT 包含格式转换逻辑 —— 那是格式基类的
+    # 职责*. An entry layer that looped over templates and wrote files itself would look
+    # correct for the Markdown family and be **wrong for every other one**: it would skip
+    # the skill header, the per-agent field an integration injects through its override
+    # hook, and the TOML/YAML rendering — and it would do so silently, leaving files that
+    # exist and are the wrong shape.
+    #
+    # ⚠️ Note the wording above: this comment may not name an agent. The boundary is
+    # enforced mechanically (`tests/test_cli_entry.py` scans this directory for every
+    # first-batch agent key and deploy root), and it is right to — a name in a comment is
+    # still the entry layer having learned about one agent.
+    #
+    # Step 4 of the validation block (per-file conflict → skip, do not abort) is
+    # delegated to `setup` itself and travels with the format logic it belongs to; the
+    # entry layer only forwards `--force` and reports what comes back.
+    written, skipped = integration.setup(project_root, commands_dir, force=force)
+
+    # --- support groups (byte-identical tier, FR-007: plain copy) ------------------------
+    # src is None ⇔ a commands-only --source; the group is then NOT PROVIDED by
+    # that origin, and the report says so — it is never a silent absence.
+    support_report: list[tuple[str, list[Path], list[Path], str]] = []
+    for group, group_dest, src in support_groups:
+        if src is None:
+            support_report.append((group, [], [], "not provided by this --source (commands-only)"))
+            continue
+        g_written, g_skipped = _deploy_verbatim(src, group_dest, force=force)
+        support_report.append((group, g_written, g_skipped, str(group_dest)))
+
+    # --- report -------------------------------------------------------------------------
+    # Shape fixed by `install-cli.md` → `## Output Contract`: target · agent · written ·
+    # skipped WITH every file named and its reason · how to invoke. 逐条列出 is the hard
+    # requirement there — a bare count leaves the user unable to tell WHICH files he
+    # must handle himself, and "which files did not install" is exactly the thing he
+    # needs to judge.
+    display = (integration.config or {}).get("name") or integration.key
+    template_names = [p.name for p in integration.list_command_templates(commands_dir)]
+
+    typer.echo(f"specpro → {project_root}")
+    typer.echo(f"agent: {integration.key} ({display})")
+    typer.echo(f"deployed to: {dest}")
+    typer.echo(f"written: {len(written)}")
+    if skipped:
+        typer.echo(f"skipped: {len(skipped)} (already exist; use --force to overwrite)")
+        for p in skipped:
+            typer.echo(f"  - {p}")
+    else:
+        typer.echo("skipped: 0")
+    # Output Contract (install-cli.md): skipped files are named, never a bare count —
+    # the same rule the commands group follows above applies to each support group.
+    for group, g_written, g_skipped, note in support_report:
+        if isinstance(note, str) and note.startswith("not provided"):
+            typer.echo(f"support: {group} — {note}")
+            continue
+        typer.echo(
+            f"support: {group} — written {len(g_written)}, skipped {len(g_skipped)}"
+            + (" (already exist; use --force to overwrite)" if g_skipped else "")
+            + f" → {note}"
+        )
+        for p in g_skipped:
+            typer.echo(f"  - {p}")
+    typer.echo("")
+    typer.echo("Next: invoke specpro commands from this agent as")
+    for name in template_names:
+        # `build_command_invocation` takes the COMMAND name (`specpro.analyze`), not the
+        # template file name — passing the raw name emitted `/specpro.analyze.md`, a
+        # suffix no agent parses. `Path.stem` strips the extension for every format.
+        stem = Path(name).stem
+        typer.echo(f"  {integration.build_command_invocation(stem)}   # {name}")