spectask-init 0.1.0__tar.gz

spectask_init-0.1.0/PKG-INFO

@@ -0,0 +1,6 @@
+Metadata-Version: 2.4
+Name: spectask-init
+Version: 0.1.0
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"

spectask_init-0.1.0/README.md

@@ -0,0 +1,84 @@
+# spectask-init
+
+Python3.10+ CLI to bootstrap [Spectask](https://github.com/noant/spectask)-style template files into the **current working directory** (ZIP or Git sources, optional `spec/extend` overlay, IDE paths from `skills-map.json`).
+
+The PyPI project and console command are **`spectask-init`**.
+
+## Use with uvx (recommended)
+
+[`uvx`](https://docs.astral.sh/uv/guides/tools/) runs the tool from PyPI without a permanent install. Install [**uv**](https://docs.astral.sh/uv/getting-started/installation/) first (it includes `uvx`).
+
+```bash
+uvx spectask-init --ide <key>
+```
+
+Examples:
+
+```bash
+uvx spectask-init --ide cursor
+uvx spectask-init --ide cursor --template-branch main
+uvx spectask-init --help
+```
+
+**Requirements:**
+
+- Network access (PyPI).
+- After the package is published, the command resolves **`spectask-init`** from [PyPI](https://pypi.org/project/spectask-init/). Until then, install from this repo (see below).
+- For **Git** template URLs (not ending in `.zip`), `git` must be on your `PATH`.
+
+## Install from source
+
+```bash
+git clone <this-repo-url>
+cd spectask-cli
+pip install .
+spectask-init --ide <key>
+# or: python -m spectask_init --ide <key>
+```
+
+## pip install (global / venv)
+
+```bash
+pip install spectask-init
+spectask-init --ide <key>
+```
+
+## Installing uv (quick reference)
+
+| Platform | Command |
+|----------|---------|
+| **Windows** (PowerShell) | `powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 \| iex"` |
+| **macOS / Linux** | `curl -LsSf https://astral.sh/uv/install.sh \| sh` |
+
+More options: [uv installation](https://docs.astral.sh/uv/getting-started/installation/).
+
+## Docs
+
+- Architecture: [`spec/design/hla.md`](spec/design/hla.md)
+- Spec methodology: [`spec/main.md`](spec/main.md)
+
+## Maintainer: tests and publishing
+
+From the repo root, with [uv](https://docs.astral.sh/uv/) on `PATH`.
+
+**Tests** — install dev dependencies (includes pytest), then run the suite:
+
+```bash
+uv sync --extra dev
+uv run pytest tests
+```
+
+Skip integration tests (no network or `git clone`; unit tests only):
+
+```bash
+uv run pytest tests -m "not integration"
+```
+
+**Publish to PyPI** — set a [PyPI API token](https://pypi.org/manage/account/) and run:
+
+```bash
+export spectask_publish_pypi_token=pypi-...   # or: python scripts/publish.py --token pypi-...
+python scripts/publish.py
+```
+
+Do not commit tokens. See [uv publish](https://docs.astral.sh/uv/guides/publish/).

spectask_init-0.1.0/pyproject.toml

@@ -0,0 +1,18 @@
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "spectask-init"
+version = "0.1.0"
+requires-python = ">=3.10"
+dependencies = []
+
+[project.optional-dependencies]
+dev = ["pytest>=8"]
+
+[project.scripts]
+spectask-init = "spectask_init.cli:main"
+
+[tool.setuptools.packages.find]
+include = ["spectask_init*"]

spectask_init-0.1.0/setup.cfg

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

spectask_init-0.1.0/spectask_init/__init__.py

@@ -0,0 +1 @@
+"""Bootstrap Spectask template files into the current working directory."""

spectask_init-0.1.0/spectask_init/__main__.py

@@ -0,0 +1,4 @@
+from spectask_init.cli import main
+
+if __name__ == "__main__":
+    main()

spectask_init-0.1.0/spectask_init/acquire.py

@@ -0,0 +1,108 @@
+from __future__ import annotations
+
+import subprocess
+import tempfile
+import zipfile
+from contextlib import contextmanager
+from pathlib import Path
+from typing import Generator, Literal
+from urllib.error import HTTPError, URLError
+from urllib.parse import urlparse
+from urllib.request import urlopen
+
+
+def is_zip_url(url: str) -> bool:
+    return urlparse(url).path.lower().endswith(".zip")
+
+
+def resolve_zip_base(extract_dir: Path, layout: Literal["template", "extend"]) -> Path:
+    def has_marker(base: Path) -> bool:
+        if layout == "template":
+            return (base / ".metadata").is_dir()
+        return (base / "spec" / "extend").is_dir()
+
+    base = extract_dir
+    if has_marker(base):
+        return base
+    children = [p for p in base.iterdir() if p.is_dir()]
+    if len(children) == 1:
+        base = children[0]
+        if has_marker(base):
+            return base
+    marker = ".metadata" if layout == "template" else "spec/extend/"
+    raise RuntimeError(
+        f"Cannot resolve {layout} root under {extract_dir}: expected {marker} "
+        "(after unwrapping at most one single top-level folder if present)",
+    )
+
+
+def ensure_git_available() -> None:
+    try:
+        r = subprocess.run(
+            ["git", "--version"],
+            capture_output=True,
+            text=True,
+            timeout=30,
+        )
+    except FileNotFoundError as e:
+        raise RuntimeError("git is not installed or not on PATH; required for non-ZIP URLs.") from e
+    except subprocess.TimeoutExpired as e:
+        raise RuntimeError("git --version timed out; check your git installation.") from e
+    if r.returncode != 0:
+        msg = (r.stderr or r.stdout or "").strip() or f"exit code {r.returncode}"
+        raise RuntimeError(f"git is not available ({msg}); required for non-ZIP URLs.")
+
+
+@contextmanager
+def acquire_source(
+    url: str,
+    *,
+    git_branch: str,
+    layout: Literal["template", "extend"],
+) -> Generator[Path, None, None]:
+    if is_zip_url(url):
+        with tempfile.TemporaryDirectory(prefix="spectask-src-zip-") as td:
+            td_path = Path(td)
+            zip_path = td_path / "archive.zip"
+            try:
+                with urlopen(url, timeout=60) as resp:
+                    zip_path.write_bytes(resp.read())
+            except (HTTPError, URLError, TimeoutError, OSError) as e:
+                raise RuntimeError(f"Failed to download archive {url!r}: {e}") from e
+            extract_dir = td_path / "extract"
+            extract_dir.mkdir()
+            with zipfile.ZipFile(zip_path) as zf:
+                zf.extractall(extract_dir)
+            yield resolve_zip_base(extract_dir, layout)
+        return
+
+    ensure_git_available()
+    with tempfile.TemporaryDirectory(prefix="spectask-src-git-") as td:
+        repo = Path(td) / "repo"
+        try:
+            subprocess.run(
+                [
+                    "git",
+                    "clone",
+                    "--depth",
+                    "1",
+                    "--branch",
+                    git_branch,
+                    "--single-branch",
+                    url,
+                    str(repo),
+                ],
+                check=True,
+                capture_output=True,
+                text=True,
+            )
+        except subprocess.CalledProcessError as e:
+            err = (e.stderr or e.stdout or "").strip()
+            detail = f": {err}" if err else ""
+            raise RuntimeError(f"git clone failed for {url!r}{detail}") from e
+
+        if layout == "template" and not (repo / ".metadata").is_dir():
+            raise RuntimeError(f"Cloned template missing .metadata directory: {repo}")
+        if layout == "extend" and not (repo / "spec" / "extend").is_dir():
+            raise RuntimeError(f"Cloned extend source missing spec/extend: {repo}")
+        yield repo

spectask_init-0.1.0/spectask_init/bootstrap.py

@@ -0,0 +1,151 @@
+from __future__ import annotations
+
+import json
+import shutil
+from pathlib import Path
+from typing import Any
+
+from spectask_init.acquire import acquire_source
+
+
+def _paths_from_entry(entry: dict[str, Any]) -> list[str] | None:
+    """IDE entries use `paths` (spec) or `files` (upstream template)."""
+    if "paths" in entry:
+        v = entry["paths"]
+    elif "files" in entry:
+        v = entry["files"]
+    else:
+        return None
+    if not isinstance(v, list):
+        return None
+    return [p for p in v if isinstance(p, str)]
+
+
+def load_json(path: Path) -> dict[str, Any]:
+    try:
+        raw = path.read_text(encoding="utf-8")
+    except OSError as e:
+        raise RuntimeError(f"Cannot read {path}: {e}") from e
+    try:
+        data = json.loads(raw)
+    except json.JSONDecodeError as e:
+        raise RuntimeError(f"Invalid JSON in {path}: {e}") from e
+    if not isinstance(data, dict):
+        raise RuntimeError(f"Expected JSON object at root in {path}")
+    return data
+
+
+def ide_files_for(skills: dict[str, Any], ide: str) -> list[str]:
+    ides = skills.get("ides")
+    if not isinstance(ides, list):
+        raise RuntimeError("skills-map.json: missing or invalid 'ides' array")
+
+    if ide == "all":
+        seen: set[str] = set()
+        out: list[str] = []
+        for entry in ides:
+            if not isinstance(entry, dict):
+                continue
+            paths = _paths_from_entry(entry)
+            if not paths:
+                continue
+            for p in paths:
+                if p not in seen:
+                    seen.add(p)
+                    out.append(p)
+        return out
+
+    for entry in ides:
+        if not isinstance(entry, dict):
+            continue
+        if entry.get("name") != ide:
+            continue
+        paths = _paths_from_entry(entry)
+        if paths is None:
+            raise RuntimeError(
+                f"skills-map.json: IDE {ide!r} must have a 'paths' or 'files' array of strings",
+            )
+        return paths
+
+    raise RuntimeError(f"Unknown IDE {ide!r} in skills-map.json (not in ides[].name, and not 'all')")
+
+
+def copy_into_cwd(template_root: Path, rel_path: str) -> None:
+    src = (template_root / rel_path).resolve()
+    root = template_root.resolve()
+    try:
+        src.relative_to(root)
+    except ValueError as e:
+        raise RuntimeError(f"Refusing to copy path outside template root: {rel_path!r}") from e
+
+    if not src.exists():
+        raise RuntimeError(f"Template missing path {rel_path!r} (expected under {template_root})")
+
+    dest = (Path.cwd() / rel_path).resolve()
+    cwd = Path.cwd().resolve()
+    try:
+        dest.relative_to(cwd)
+    except ValueError as e:
+        raise RuntimeError(f"Refusing to copy outside current working directory: {rel_path!r}") from e
+
+    if src.is_file():
+        dest.parent.mkdir(parents=True, exist_ok=True)
+        shutil.copy2(src, dest)
+    elif src.is_dir():
+        shutil.copytree(src, dest, dirs_exist_ok=True)
+    else:
+        raise RuntimeError(f"Not a file or directory: {rel_path!r}")
+
+
+def run_template_bootstrap(
+    *,
+    template_url: str,
+    ide: str,
+    skip_example: bool,
+    template_branch: str,
+) -> None:
+    with acquire_source(template_url, git_branch=template_branch, layout="template") as template_root:
+        meta = template_root / ".metadata"
+        required_data = load_json(meta / "required-list.json")
+        required = required_data.get("required")
+        if not isinstance(required, list):
+            raise RuntimeError("required-list.json: missing or invalid 'required' array")
+        for rel in required:
+            if not isinstance(rel, str):
+                raise RuntimeError("required-list.json: 'required' must be a list of strings")
+            copy_into_cwd(template_root, rel)
+
+        if not skip_example:
+            example_data = load_json(meta / "example-list.json")
+            examples = example_data.get("examples")
+            if not isinstance(examples, list):
+                raise RuntimeError("example-list.json: missing or invalid 'examples' array")
+            for rel in examples:
+                if not isinstance(rel, str):
+                    raise RuntimeError("example-list.json: 'examples' must be a list of strings")
+                copy_into_cwd(template_root, rel)
+
+        skills = load_json(meta / "skills-map.json")
+        for rel in ide_files_for(skills, ide):
+            copy_into_cwd(template_root, rel)
+
+
+def copy_extend_overlay(extend_root: Path) -> None:
+    src_dir = extend_root / "spec" / "extend"
+    if not src_dir.is_dir():
+        raise FileNotFoundError(f"No spec/extend in extend source: {src_dir}")
+    dest_root = Path.cwd()
+    for path in src_dir.rglob("*"):
+        if path.is_dir():
+            continue
+        rel = path.relative_to(src_dir)
+        dest = dest_root / "spec" / "extend" / rel
+        dest.parent.mkdir(parents=True, exist_ok=True)
+        shutil.copy2(path, dest)
+
+
+def run_extend(*, extend_url: str | None, extend_branch: str) -> None:
+    if not extend_url:
+        return
+    with acquire_source(extend_url, git_branch=extend_branch, layout="extend") as root:
+        copy_extend_overlay(root)

spectask_init-0.1.0/spectask_init/cli.py

@@ -0,0 +1,84 @@
+from __future__ import annotations
+
+import argparse
+import sys
+import zipfile
+from dataclasses import dataclass
+
+from spectask_init.bootstrap import run_extend, run_template_bootstrap
+
+DEFAULT_TEMPLATE_URL = "https://github.com/noant/spectask.git"
+
+
+@dataclass(frozen=True)
+class CliOptions:
+    template_url: str
+    ide: str
+    template_branch: str
+    extend: str | None
+    extend_branch: str
+    skip_example: bool
+
+
+def build_parser() -> argparse.ArgumentParser:
+    epilog = """
+ZIP vs Git:
+  If the URL path ends with .zip (case-insensitive), the tool downloads and extracts
+  the archive. Otherwise it runs git clone (requires git on PATH), using
+  --template-branch for --template-url and --extend-branch for --extend.
+  The same rule applies to --extend when that option is used.
+
+Default --template-url is the official Spectask GitHub repository (.git); use a .zip URL
+  to avoid git for the template step only.
+""".strip()
+    p = argparse.ArgumentParser(
+        description="Bootstrap Spectask template files into the current directory.",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog=epilog,
+    )
+    p.add_argument(
+        "--template-url",
+        default=DEFAULT_TEMPLATE_URL,
+        metavar="URL",
+        help=f"Template source (ZIP or Git). Default: {DEFAULT_TEMPLATE_URL}",
+    )
+    p.add_argument("--ide", required=True, help="IDE key from skills-map.json, or 'all'.")
+    p.add_argument("--template-branch", default="main", help="Git branch for template URL when not ZIP (default: main).")
+    p.add_argument("--extend", default=None, help="Optional overlay source (ZIP or Git) for spec/extend/.")
+    p.add_argument("--extend-branch", default="main", help="Git branch for --extend when not ZIP (default: main).")
+    p.add_argument("--skip-example", action="store_true", help="Do not copy example-list.json paths.")
+    return p
+
+
+def parse_args(argv: list[str] | None = None) -> CliOptions:
+    p = build_parser()
+    ns = p.parse_args(argv)
+    return CliOptions(
+        template_url=ns.template_url,
+        ide=ns.ide,
+        template_branch=ns.template_branch,
+        extend=ns.extend,
+        extend_branch=ns.extend_branch,
+        skip_example=ns.skip_example,
+    )
+
+
+def main() -> None:
+    opts = parse_args()
+    try:
+        run_template_bootstrap(
+            template_url=opts.template_url,
+            ide=opts.ide,
+            skip_example=opts.skip_example,
+            template_branch=opts.template_branch,
+        )
+    except (OSError, RuntimeError, zipfile.BadZipFile) as e:
+        print(f"spectask-init: {e}", file=sys.stderr)
+        sys.exit(1)
+
+    if opts.extend:
+        try:
+            run_extend(extend_url=opts.extend, extend_branch=opts.extend_branch)
+        except (OSError, RuntimeError, zipfile.BadZipFile) as e:
+            print(f"spectask-init: {e}", file=sys.stderr)
+            sys.exit(1)

spectask_init-0.1.0/spectask_init.egg-info/PKG-INFO

@@ -0,0 +1,6 @@
+Metadata-Version: 2.4
+Name: spectask-init
+Version: 0.1.0
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"

spectask_init-0.1.0/spectask_init.egg-info/SOURCES.txt

@@ -0,0 +1,17 @@
+README.md
+pyproject.toml
+spectask_init/__init__.py
+spectask_init/__main__.py
+spectask_init/acquire.py
+spectask_init/bootstrap.py
+spectask_init/cli.py
+spectask_init.egg-info/PKG-INFO
+spectask_init.egg-info/SOURCES.txt
+spectask_init.egg-info/dependency_links.txt
+spectask_init.egg-info/entry_points.txt
+spectask_init.egg-info/requires.txt
+spectask_init.egg-info/top_level.txt
+tests/test_acquire.py
+tests/test_bootstrap_unit.py
+tests/test_cli_parse.py
+tests/test_integration_cli.py

spectask_init-0.1.0/spectask_init.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

spectask_init-0.1.0/spectask_init.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+spectask-init = spectask_init.cli:main

spectask_init-0.1.0/spectask_init.egg-info/requires.txt

@@ -0,0 +1,3 @@
+
+[dev]
+pytest>=8

spectask_init-0.1.0/spectask_init.egg-info/top_level.txt

@@ -0,0 +1 @@
+spectask_init

spectask_init-0.1.0/tests/test_acquire.py

@@ -0,0 +1,57 @@
+from __future__ import annotations
+
+import pytest
+
+from spectask_init.acquire import is_zip_url, resolve_zip_base
+
+
+@pytest.mark.parametrize(
+    ("url", "expected"),
+    [
+        ("https://github.com/o/r/archive/refs/heads/main.zip", True),
+        ("https://example.com/path.ZIP", True),
+        ("https://github.com/noant/spectask.git", False),
+        ("https://example.com/archive.zip/extra", False),
+    ],
+)
+def test_is_zip_url(url: str, expected: bool) -> None:
+    assert is_zip_url(url) is expected
+
+
+def test_resolve_zip_base_template_at_root(tmp_path) -> None:
+    root = tmp_path / "extract"
+    root.mkdir()
+    (root / ".metadata").mkdir()
+    assert resolve_zip_base(root, "template") == root
+
+
+def test_resolve_zip_base_template_one_wrapper(tmp_path) -> None:
+    extract = tmp_path / "extract"
+    extract.mkdir()
+    inner = extract / "repo-main"
+    inner.mkdir()
+    (inner / ".metadata").mkdir()
+    assert resolve_zip_base(extract, "template") == inner
+
+
+def test_resolve_zip_base_extend_at_root(tmp_path) -> None:
+    root = tmp_path / "extract"
+    root.mkdir()
+    (root / "spec" / "extend").mkdir(parents=True)
+    assert resolve_zip_base(root, "extend") == root
+
+
+def test_resolve_zip_base_extend_one_wrapper(tmp_path) -> None:
+    extract = tmp_path / "extract"
+    extract.mkdir()
+    inner = extract / "repo-main"
+    inner.mkdir()
+    (inner / "spec" / "extend").mkdir(parents=True)
+    assert resolve_zip_base(extract, "extend") == inner
+
+
+def test_resolve_zip_base_template_fails(tmp_path) -> None:
+    root = tmp_path / "extract"
+    root.mkdir()
+    with pytest.raises(RuntimeError, match="Cannot resolve template root"):
+        resolve_zip_base(root, "template")

spectask_init-0.1.0/tests/test_bootstrap_unit.py

@@ -0,0 +1,73 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+import pytest
+
+from spectask_init.bootstrap import copy_into_cwd, ide_files_for, load_json
+
+
+def test_ide_files_for_named() -> None:
+    skills = {
+        "ides": [
+            {"name": "cursor", "paths": ["a.md", "b.md"]},
+            {"name": "other", "files": ["c.md"]},
+        ]
+    }
+    assert ide_files_for(skills, "cursor") == ["a.md", "b.md"]
+    assert ide_files_for(skills, "other") == ["c.md"]
+
+
+def test_ide_files_for_all_dedupes() -> None:
+    skills = {
+        "ides": [
+            {"name": "a", "paths": ["shared.md", "only-a.md"]},
+            {"name": "b", "files": ["shared.md", "only-b.md"]},
+        ]
+    }
+    assert ide_files_for(skills, "all") == ["shared.md", "only-a.md", "only-b.md"]
+
+
+def test_ide_files_for_unknown_ide() -> None:
+    skills = {"ides": [{"name": "cursor", "paths": ["x.md"]}]}
+    with pytest.raises(RuntimeError, match="Unknown IDE"):
+        ide_files_for(skills, "missing")
+
+
+def test_ide_files_for_missing_ides() -> None:
+    with pytest.raises(RuntimeError, match="ides"):
+        ide_files_for({}, "cursor")
+
+
+def test_ide_files_for_named_without_paths() -> None:
+    skills = {"ides": [{"name": "cursor", "oops": []}]}
+    with pytest.raises(RuntimeError, match="must have a 'paths' or 'files'"):
+        ide_files_for(skills, "cursor")
+
+
+def test_load_json_invalid(tmp_path) -> None:
+    p = tmp_path / "bad.json"
+    p.write_text("not json", encoding="utf-8")
+    with pytest.raises(RuntimeError, match="Invalid JSON"):
+        load_json(p)
+
+
+def test_copy_into_cwd_file(tmp_path, monkeypatch) -> None:
+    monkeypatch.chdir(tmp_path)
+    root = tmp_path / "tpl"
+    (root / "dir").mkdir(parents=True)
+    src = root / "dir" / "f.txt"
+    src.write_text("hi", encoding="utf-8")
+    copy_into_cwd(root, "dir/f.txt")
+    assert (tmp_path / "dir" / "f.txt").read_text(encoding="utf-8") == "hi"
+
+
+def test_copy_into_cwd_rejects_escape(tmp_path, monkeypatch) -> None:
+    monkeypatch.chdir(tmp_path)
+    root = tmp_path / "tpl"
+    root.mkdir()
+    other = tmp_path / "outside"
+    other.mkdir()
+    (other / "secret.txt").write_text("x", encoding="utf-8")
+    with pytest.raises(RuntimeError, match="outside template root"):
+        copy_into_cwd(root, "../outside/secret.txt")

spectask_init-0.1.0/tests/test_cli_parse.py

@@ -0,0 +1,60 @@
+from __future__ import annotations
+
+import pytest
+
+from spectask_init.cli import DEFAULT_TEMPLATE_URL, parse_args
+
+
+def test_parse_defaults() -> None:
+    o = parse_args(["--ide", "cursor"])
+    assert o.template_url == DEFAULT_TEMPLATE_URL
+    assert o.ide == "cursor"
+    assert o.template_branch == "main"
+    assert o.extend is None
+    assert o.extend_branch == "main"
+    assert o.skip_example is False
+
+
+def test_parse_custom_template_and_branches() -> None:
+    o = parse_args(
+        [
+            "--template-url",
+            "https://example.com/t.zip",
+            "--ide",
+            "windsurf",
+            "--template-branch",
+            "develop",
+            "--extend-branch",
+            "topic",
+        ]
+    )
+    assert o.template_url == "https://example.com/t.zip"
+    assert o.ide == "windsurf"
+    assert o.template_branch == "develop"
+    assert o.extend is None
+    assert o.extend_branch == "topic"
+
+
+def test_parse_extend_git() -> None:
+    o = parse_args(
+        [
+            "--ide",
+            "cursor",
+            "--extend",
+            "https://github.com/noant/spectask-my-extend.git",
+            "--extend-branch",
+            "main",
+        ]
+    )
+    assert o.extend == "https://github.com/noant/spectask-my-extend.git"
+    assert o.extend_branch == "main"
+
+
+def test_parse_skip_example() -> None:
+    o = parse_args(["--ide", "cursor", "--skip-example"])
+    assert o.skip_example is True
+
+
+def test_parse_ide_required() -> None:
+    with pytest.raises(SystemExit):
+        parse_args([])

spectask_init-0.1.0/tests/test_integration_cli.py

@@ -0,0 +1,183 @@
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+import pytest
+
+from spectask_init.cli import main
+
+TEMPLATE_ZIP = "https://github.com/noant/spectask/archive/refs/heads/main.zip"
+TEMPLATE_GIT = "https://github.com/noant/spectask.git"
+EXTEND_ZIP = "https://github.com/noant/spectask-my-extend/archive/refs/heads/main.zip"
+EXTEND_GIT = "https://github.com/noant/spectask-my-extend.git"
+
+EXAMPLE_ONLY = Path("spec/tasks/0-example-hello/overview.md")
+EXTEND_OVERLAY = Path("spec/extend/0-misc.md")
+CURSOR_SKILL = Path(".cursor/skills/spectask-create/SKILL.md")
+
+
+def _run_main(monkeypatch: pytest.MonkeyPatch, tmp_path: Path, argv: list[str]) -> None:
+    monkeypatch.chdir(tmp_path)
+    monkeypatch.setattr(sys, "argv", ["spectask-init", *argv])
+    main()
+
+
+def _assert_baseline(cwd: Path) -> None:
+    assert (cwd / "spec/main.md").is_file()
+    assert (cwd / "spec/navigation.md").is_file()
+    assert (cwd / "spec/design/hla.md").is_file()
+
+
+@pytest.mark.integration
+def test_zip_template_and_zip_extend(tmp_path, monkeypatch) -> None:
+    _run_main(
+        monkeypatch,
+        tmp_path,
+        [
+            "--template-url",
+            TEMPLATE_ZIP,
+            "--template-branch",
+            "unused-for-zip",
+            "--ide",
+            "cursor",
+            "--extend",
+            EXTEND_ZIP,
+            "--extend-branch",
+            "unused-for-zip",
+        ],
+    )
+    _assert_baseline(tmp_path)
+    assert (tmp_path / EXTEND_OVERLAY).is_file()
+    assert (tmp_path / CURSOR_SKILL).is_file()
+
+
+@pytest.mark.integration
+def test_git_template_and_git_extend(tmp_path, monkeypatch, git_on_path) -> None:
+    _run_main(
+        monkeypatch,
+        tmp_path,
+        [
+            "--template-url",
+            TEMPLATE_GIT,
+            "--template-branch",
+            "main",
+            "--ide",
+            "cursor",
+            "--extend",
+            EXTEND_GIT,
+            "--extend-branch",
+            "main",
+        ],
+    )
+    _assert_baseline(tmp_path)
+    assert (tmp_path / EXTEND_OVERLAY).is_file()
+
+
+@pytest.mark.integration
+def test_zip_template_only(tmp_path, monkeypatch) -> None:
+    _run_main(
+        monkeypatch,
+        tmp_path,
+        ["--template-url", TEMPLATE_ZIP, "--ide", "cursor"],
+    )
+    _assert_baseline(tmp_path)
+    assert not (tmp_path / EXTEND_OVERLAY).is_file()
+
+
+@pytest.mark.integration
+def test_git_template_only(tmp_path, monkeypatch, git_on_path) -> None:
+    _run_main(
+        monkeypatch,
+        tmp_path,
+        ["--template-url", TEMPLATE_GIT, "--template-branch", "main", "--ide", "cursor"],
+    )
+    _assert_baseline(tmp_path)
+    assert not (tmp_path / EXTEND_OVERLAY).is_file()
+
+
+@pytest.mark.integration
+def test_zip_template_and_git_extend(tmp_path, monkeypatch, git_on_path) -> None:
+    _run_main(
+        monkeypatch,
+        tmp_path,
+        [
+            "--template-url",
+            TEMPLATE_ZIP,
+            "--ide",
+            "cursor",
+            "--extend",
+            EXTEND_GIT,
+            "--extend-branch",
+            "main",
+        ],
+    )
+    _assert_baseline(tmp_path)
+    assert (tmp_path / EXTEND_OVERLAY).is_file()
+
+
+@pytest.mark.integration
+def test_git_template_and_zip_extend(tmp_path, monkeypatch, git_on_path) -> None:
+    _run_main(
+        monkeypatch,
+        tmp_path,
+        [
+            "--template-url",
+            TEMPLATE_GIT,
+            "--template-branch",
+            "main",
+            "--ide",
+            "cursor",
+            "--extend",
+            EXTEND_ZIP,
+        ],
+    )
+    _assert_baseline(tmp_path)
+    assert (tmp_path / EXTEND_OVERLAY).is_file()
+
+
+@pytest.mark.integration
+def test_skip_example_off_includes_example_paths(tmp_path, monkeypatch) -> None:
+    _run_main(
+        monkeypatch,
+        tmp_path,
+        ["--template-url", TEMPLATE_ZIP, "--ide", "cursor"],
+    )
+    assert (tmp_path / EXAMPLE_ONLY).is_file()
+
+
+@pytest.mark.integration
+def test_skip_example_on_excludes_example_paths(tmp_path, monkeypatch) -> None:
+    _run_main(
+        monkeypatch,
+        tmp_path,
+        ["--template-url", TEMPLATE_ZIP, "--ide", "cursor", "--skip-example"],
+    )
+    assert not (tmp_path / EXAMPLE_ONLY).exists()
+
+
+@pytest.mark.integration
+def test_ide_all_copies_union(tmp_path, monkeypatch) -> None:
+    _run_main(
+        monkeypatch,
+        tmp_path,
+        ["--template-url", TEMPLATE_ZIP, "--ide", "all"],
+    )
+    assert (tmp_path / CURSOR_SKILL).is_file()
+    assert (tmp_path / "CLAUDE.md").is_file()
+
+
+@pytest.mark.integration
+def test_zip_run_with_custom_tmp_env(tmp_path, monkeypatch) -> None:
+    """ZIP extract uses tempfile; point TMP* at a writable dir (cleaned up after exit)."""
+    sandbox = tmp_path / "sandbox"
+    sandbox.mkdir()
+    monkeypatch.setenv("TMPDIR", str(sandbox))
+    monkeypatch.setenv("TEMP", str(sandbox))
+    monkeypatch.setenv("TMP", str(sandbox))
+    _run_main(
+        monkeypatch,
+        tmp_path,
+        ["--template-url", TEMPLATE_ZIP, "--ide", "cursor"],
+    )
+    _assert_baseline(tmp_path)