steppy-dev 0.3.0__py3-none-any.whl

steppy/history.py

@@ -0,0 +1,352 @@
+"""Append-only run history — the substrate for ``steppy flaky``.
+
+A single run's summary tells you what broke today. It cannot tell you that
+``checkout-with-coupon`` has failed in seven of the last twenty runs while
+everything around it is stable. That ranking is what actually directs a fix,
+and it needs one thing the codebase did not have: memory.
+
+Storage is ``.steppy/history.jsonl`` — one JSON object per (run, scenario),
+appended, never rewritten. Deliberately **not** under ``output/``: that tree is
+wiped by cleanup, and history that evaporates on a clean build is worse than no
+history because it looks authoritative. This mirrors the coverage store's
+reasoning for living at ``.steppy/coverage.db``.
+
+JSONL rather than sqlite because the access pattern is "read the tail, group in
+memory" — a few thousand lines is nothing, and a text file survives partial
+writes, concurrent appends and manual inspection in a way a binary store does
+not.
+
+This is a leaf module: stdlib only, no imports from ``cli``, ``coordinator`` or
+``_parallel``. ``steppy.flaky_cli`` and the coordinator both use it, and the
+no-parallel-import guard depends on it staying that way.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import statistics
+import time
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Iterable, Optional
+
+
+HISTORY_DIRNAME = ".steppy"
+HISTORY_FILENAME = "history.jsonl"
+
+# Bumped if the record shape changes incompatibly. Readers skip records whose
+# version they don't understand rather than crashing on an old file.
+RECORD_SCHEMA_VERSION = 1
+
+# Outcomes a record can carry.
+OUTCOME_PASSED = "passed"
+OUTCOME_FLAKY = "flaky"
+OUTCOME_FAILED = "failed"
+
+
+def history_path(project_root: Path) -> Path:
+    return Path(project_root) / HISTORY_DIRNAME / HISTORY_FILENAME
+
+
+# ── Writing ─────────────────────────────────────────────────────────────────
+
+
+def append_run(
+    *,
+    project_root: Path,
+    run_id: str,
+    workers: int,
+    passes: Iterable[Any],
+    verdict: Optional[Any] = None,
+    bus: Optional[Any] = None,
+    started_at: Optional[float] = None,
+) -> Optional[Path]:
+    """Append one record per scenario for a just-finished parallel run.
+
+    ``passes`` are the :class:`~steppy._parallel.retry.PassResult` objects
+    (attempt 1 first). ``verdict`` is the classification when a retry pass ran;
+    without one every scenario is simply passed/failed.
+
+    Returns the path written, or ``None`` on any failure — history is
+    telemetry, and the caller's run has already produced its real outcome. This
+    function never raises.
+    """
+    try:
+        passes = list(passes)
+        records = _build_records(
+            run_id=run_id,
+            workers=workers,
+            passes=passes,
+            verdict=verdict,
+            bus=bus,
+            started_at=started_at,
+        )
+        if not records:
+            return None
+        path = history_path(project_root)
+        path.parent.mkdir(parents=True, exist_ok=True)
+        # One open/append per run keeps the write atomic enough for our
+        # purposes: concurrent runs interleave whole lines, never partial ones.
+        with path.open("a", encoding="utf-8") as f:
+            for record in records:
+                f.write(json.dumps(record, sort_keys=True) + "\n")
+        _ensure_gitignored(path.parent)
+        return path
+    except (OSError, TypeError, ValueError, AttributeError):
+        return None
+
+
+def _build_records(*, run_id, workers, passes, verdict, bus, started_at) -> list[dict]:
+    """One record per scenario, reflecting its FINAL outcome across attempts."""
+    if not passes:
+        return []
+    now = time.time()
+    started = started_at
+    if started is None and bus is not None:
+        started = getattr(bus.snapshot(), "wall_clock_started", None)
+    started = started if started is not None else now
+
+    flaky = set(getattr(verdict, "flaky", ()) or ())
+    failed = set(getattr(verdict, "failed", ()) or ())
+
+    # Last attempt wins for the per-scenario metadata (worker, duration).
+    last_result: dict[str, Any] = {}
+    attempts_used: dict[str, int] = {}
+    for p in passes:
+        for r in p.results:
+            last_result[r.slug] = r
+            attempts_used[r.slug] = p.attempt
+        for slugs in p.orphans.values():
+            for slug in slugs:
+                attempts_used.setdefault(slug, p.attempt)
+                last_result.setdefault(slug, None)
+
+    fingerprints = _fingerprints_by_slug(passes)
+
+    records: list[dict] = []
+    for slug in sorted(last_result):
+        result = last_result[slug]
+        if verdict is not None:
+            if slug in failed:
+                outcome = OUTCOME_FAILED
+            elif slug in flaky:
+                outcome = OUTCOME_FLAKY
+            else:
+                outcome = OUTCOME_PASSED
+        else:
+            outcome = OUTCOME_PASSED if (result is not None and result.exit_code == 0) else OUTCOME_FAILED
+        records.append(
+            {
+                "v": RECORD_SCHEMA_VERSION,
+                "run_id": run_id,
+                "started_at": round(started, 3),
+                "mode": "parallel",
+                "workers": workers,
+                "slug": slug,
+                "outcome": outcome,
+                "attempts": attempts_used.get(slug, 1),
+                "duration_s": round(result.duration_s, 3) if result is not None else None,
+                "worker_id": result.worker_id if result is not None else None,
+                "fingerprint": fingerprints.get(slug),
+            }
+        )
+    return records
+
+
+def _fingerprints_by_slug(passes) -> dict[str, str]:
+    """Failure fingerprint per scenario, from the last attempt that produced a
+    tail. Lets ``steppy flaky`` say "these five always fail the same way"."""
+    try:
+        from ._parallel.fingerprint import fingerprint
+    except ImportError:
+        return {}
+    out: dict[str, str] = {}
+    for p in passes:
+        bus = getattr(p, "bus", None)
+        if bus is None:
+            continue
+        try:
+            tests = bus.snapshot().tests
+        except AttributeError:
+            continue
+        for t in tests:
+            if t.outcome in ("failed", "error", "worker_died") and t.fail_tail and t.scenario_slug:
+                out[t.scenario_slug] = fingerprint(t.fail_tail)
+    return out
+
+
+def _ensure_gitignored(steppy_dir: Path) -> None:
+    """``.steppy/`` is already gitignored in scaffolded projects; add a local
+    guard for projects that predate it so history never lands in a commit."""
+    marker = steppy_dir / ".gitignore"
+    if marker.exists():
+        return
+    try:
+        marker.write_text("# Created by steppy automatically.\n*\n", encoding="utf-8")
+    except OSError:
+        pass
+
+
+# ── Reading ─────────────────────────────────────────────────────────────────
+
+
+def load(project_root: Path, *, last_runs: Optional[int] = None) -> list[dict]:
+    """Read history records, oldest first.
+
+    ``last_runs`` keeps only the N most recent runs (by first appearance), which
+    is what makes "flaky over the last 20 runs" cheap. Malformed or
+    future-versioned lines are skipped, never fatal — a corrupt tail from a
+    killed process must not make the command unusable.
+    """
+    path = history_path(project_root)
+    if not path.is_file():
+        return []
+    records: list[dict] = []
+    try:
+        with path.open("r", encoding="utf-8", errors="replace") as f:
+            for line in f:
+                line = line.strip()
+                if not line:
+                    continue
+                try:
+                    record = json.loads(line)
+                except json.JSONDecodeError:
+                    continue
+                if not isinstance(record, dict) or record.get("v") != RECORD_SCHEMA_VERSION:
+                    continue
+                if record.get("slug"):
+                    records.append(record)
+    except OSError:
+        return []
+
+    if last_runs is not None and last_runs > 0:
+        seen: list[str] = []
+        for record in records:
+            rid = record.get("run_id")
+            if rid not in seen:
+                seen.append(rid)
+        keep = set(seen[-last_runs:])
+        records = [r for r in records if r.get("run_id") in keep]
+    return records
+
+
+@dataclass(frozen=True)
+class FlakeStat:
+    """Aggregated behaviour of one scenario over a window of runs."""
+
+    slug: str
+    runs: int
+    failures: int  # runs that ended failed
+    flakes: int  # runs that needed a retry to pass
+    median_s: Optional[float]
+    p95_s: Optional[float]
+    last_outcome: str
+    fingerprints: list[str]
+
+    @property
+    def flake_rate(self) -> float:
+        """Fraction of runs where this scenario did not pass first try.
+
+        Flakes and outright failures both count: from the reader's point of
+        view "this scenario cost me attention" is the signal, and a scenario
+        that fails outright half the time is not healthier than one that
+        flakes half the time."""
+        return (self.failures + self.flakes) / self.runs if self.runs else 0.0
+
+
+def flake_stats(records: Iterable[dict]) -> list[FlakeStat]:
+    """Aggregate records per scenario, worst first.
+
+    Ordering is by flake rate, then by absolute count, then slug — so a
+    scenario that failed 7/10 outranks one that failed 1/2 despite the lower
+    ratio being computed from more evidence.
+    """
+    by_slug: dict[str, list[dict]] = {}
+    for record in records:
+        by_slug.setdefault(record["slug"], []).append(record)
+
+    stats: list[FlakeStat] = []
+    for slug, rows in by_slug.items():
+        durations = [r["duration_s"] for r in rows if isinstance(r.get("duration_s"), (int, float))]
+        fps = []
+        for r in rows:
+            fp = r.get("fingerprint")
+            if fp and fp not in fps:
+                fps.append(fp)
+        stats.append(
+            FlakeStat(
+                slug=slug,
+                runs=len(rows),
+                failures=sum(1 for r in rows if r.get("outcome") == OUTCOME_FAILED),
+                flakes=sum(1 for r in rows if r.get("outcome") == OUTCOME_FLAKY),
+                median_s=round(statistics.median(durations), 1) if durations else None,
+                p95_s=round(_percentile(durations, 0.95), 1) if durations else None,
+                last_outcome=rows[-1].get("outcome", "unknown"),
+                fingerprints=fps,
+            )
+        )
+    stats.sort(key=lambda s: (-s.flake_rate, -(s.failures + s.flakes), s.slug))
+    return stats
+
+
+def _percentile(values: list[float], q: float) -> float:
+    """Nearest-rank percentile. Avoids a numpy dependency for one number."""
+    if not values:
+        return 0.0
+    ordered = sorted(values)
+    index = max(0, min(len(ordered) - 1, int(round(q * (len(ordered) - 1)))))
+    return ordered[index]
+
+
+def median_durations(project_root: Path, *, last_runs: int = 10) -> dict[str, float]:
+    """Median duration per scenario, for longest-first queue ordering.
+
+    Returns ``{}`` when there is no history — the caller falls back to whatever
+    order it already had.
+    """
+    durations: dict[str, list[float]] = {}
+    for record in load(project_root, last_runs=last_runs):
+        value = record.get("duration_s")
+        if isinstance(value, (int, float)) and value > 0:
+            durations.setdefault(record["slug"], []).append(float(value))
+    return {slug: statistics.median(values) for slug, values in durations.items()}
+
+
+def order_by_duration_desc(slugs: list[str], durations: dict[str, float]) -> list[str]:
+    """Longest-first (LPT) ordering, preserving the caller's order for ties.
+
+    Scenarios with no recorded duration go last: an unknown is most likely a
+    newly added scenario, and guessing it is slow would push a genuinely slow
+    known one behind it. Unknown-last also makes the no-history case a no-op.
+    """
+    if not durations:
+        return list(slugs)
+    known = [s for s in slugs if s in durations]
+    unknown = [s for s in slugs if s not in durations]
+    known.sort(key=lambda s: -durations[s])
+    return known + unknown
+
+
+def prune(project_root: Path, *, keep_runs: int) -> int:
+    """Rewrite the history file keeping only the newest ``keep_runs`` runs.
+
+    Returns the number of records dropped (0 on any error). Uses a temp file +
+    replace so an interrupted prune can't truncate the history."""
+    path = history_path(project_root)
+    if not path.is_file():
+        return 0
+    before = load(project_root)
+    kept = load(project_root, last_runs=keep_runs)
+    if len(kept) == len(before):
+        return 0
+    tmp = path.with_suffix(".jsonl.tmp")
+    try:
+        with tmp.open("w", encoding="utf-8") as f:
+            for record in kept:
+                f.write(json.dumps(record, sort_keys=True) + "\n")
+        os.replace(tmp, path)
+    except OSError:
+        tmp.unlink(missing_ok=True)
+        return 0
+    return len(before) - len(kept)

steppy/init_cli.py

@@ -0,0 +1,330 @@
+"""``steppy init`` — scaffold a new project (FLAWS §7.1).
+
+Zero-to-first-test is otherwise ~7 non-trivial steps, two of which (authoring
+``config.yaml`` and a first scenario) have no scaffolding at all. ``init`` writes
+a commented neutral ``config.yaml`` (with a ``$schema`` header for editor
+autocomplete), a runnable starter scenario, ``credentials.yaml.example``, a
+config JSON Schema, and a ``.steppy/scaffold.json`` manifest, and appends the
+right ``.gitignore`` entries. ``--ci`` also drops in the GitHub Actions workflow,
+and ``--app-dir`` puts the app-side skill in the app's own repository.
+
+Re-running it is safe, which is also how a project set up by hand adopts the
+scaffold: existing files are kept, the starter scenario is left out when
+``scenarios/`` already holds some, and the manifest is merged, not replaced.
+
+A leaf module: imports only from ``_cli_common`` + stdlib (no cycle with
+``cli``). Registered via :func:`register_init` at the bottom of ``cli.py``.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import importlib.resources
+import json
+import os
+from pathlib import Path
+from typing import Optional
+
+import typer
+
+from . import __version__
+from ._cli_common import _cli_errors, _error, console
+from .config_schema import schema_json
+
+# Files init lays down, resolved relative to the target project root. Value is
+# the bundled source path under steppy/templates/ (None ⇒ generated in code).
+_SCHEMA_FILENAME = "steppy-config.schema.json"
+
+# Packaged Claude skills installed into <project>/.claude/skills/<name>/SKILL.md
+# (FLAWS §7.1). Each name matches the skill's frontmatter `name:` and its
+# bundled source dir under steppy/skills/<name>/.
+SKILL_NAMES = ("steppy-scenario-author", "steppy-template", "steppy-ci-report", "steppy-app-tours")
+
+# The skills that also belong in the app's own repository (``--app-dir``). The
+# code they walk an assistant through lives there, and an assistant only sees
+# the skills of the tree it works in.
+APP_SKILL_NAMES = ("steppy-app-tours",)
+
+# Skill folders people copied in by hand before Steppy packaged its skills, and
+# what replaced each. init never wrote them, so no manifest has their hash and
+# nothing can tell a pristine copy from an edited one: they are reported, never
+# removed. Left in place, an assistant loads them beside their replacement.
+LEGACY_SKILLS = {
+    "steppy": "steppy-scenario-author",
+    "steppy-angular-export": "steppy-scenario-author",
+}
+
+# .gitignore lines init ensures are present (idempotent append). The negation
+# un-ignores the committed scaffold manifest that lives under the ignored
+# .steppy/ dir.
+_GITIGNORE_LINES = (
+    ".auth/",
+    "output/",
+    ".steppy/",
+    "credentials.yaml",
+    "!.steppy/scaffold.json",
+)
+
+
+def _bundled(*parts: str) -> Path:
+    """Absolute path to a bundled asset under ``steppy/templates/``."""
+    return Path(importlib.resources.files("steppy") / "templates" / Path(*parts))
+
+
+def _bundled_skill(*parts: str) -> Path:
+    """Absolute path to a bundled asset under ``steppy/skills/``."""
+    return Path(importlib.resources.files("steppy") / "skills" / Path(*parts))
+
+
+def _sha256(text: str) -> str:
+    return hashlib.sha256(text.encode("utf-8")).hexdigest()
+
+
+def _rel(root: Path, path: Path) -> str:
+    """``path`` as the manifest records it: relative to ``root``, ``../`` included.
+
+    An app repository given to ``--app-dir`` usually sits beside the project.
+    On another Windows drive no relative path exists, so the path stays absolute.
+    """
+    try:
+        return Path(os.path.relpath(path, root)).as_posix()
+    except ValueError:
+        return path.as_posix()
+
+
+def _write(target: Path, content: str, written: dict, skipped: list) -> None:
+    """Write ``content`` to ``target`` unless it already exists.
+
+    Records the file (relative to the project root, recorded by the caller) so
+    the scaffold manifest can hash exactly what init produced. Never clobbers a
+    user file — an existing path is reported and skipped.
+    """
+    if target.exists():
+        skipped.append((target, "already exists"))
+        return
+    target.parent.mkdir(parents=True, exist_ok=True)
+    target.write_text(content, encoding="utf-8", newline="\n")
+    written[target] = _sha256(content)
+
+
+def _ensure_gitignore(root: Path, written: dict) -> None:
+    """Append missing ignore lines idempotently (never duplicates a line)."""
+    gitignore = root / ".gitignore"
+    existing = ""
+    if gitignore.exists():
+        existing = gitignore.read_text(encoding="utf-8")
+    present = {line.strip() for line in existing.splitlines()}
+    to_add = [line for line in _GITIGNORE_LINES if line not in present]
+    if not to_add:
+        return
+    block = ""
+    if existing and not existing.endswith("\n"):
+        block += "\n"
+    if existing:
+        block += "\n"
+    block += "# Steppy\n" + "\n".join(to_add) + "\n"
+    with open(gitignore, "a", encoding="utf-8", newline="\n") as f:
+        f.write(block)
+    # The manifest records the resulting file's hash so `update` can tell a
+    # pristine .gitignore from a user-edited one.
+    written[gitignore] = _sha256(gitignore.read_text(encoding="utf-8"))
+
+
+def _write_manifest(root: Path, written: dict) -> None:
+    """Write ``.steppy/scaffold.json`` = {steppy_version, files:{rel: sha256}}.
+
+    Must ship from the first ``init`` — modification detection (§7.7 ``steppy
+    update``) can't be retrofitted onto files whose original hashes were never
+    recorded.
+
+    A re-run merges into the manifest it finds. Replacing it would forget every
+    file an earlier run recorded, and ``update`` would stop managing them. The
+    recorded ``steppy_version`` is kept too: ``update`` shows the changelog since
+    that version, and the older baselines still date from it.
+    """
+    manifest_path = root / ".steppy" / "scaffold.json"
+    manifest = {"steppy_version": __version__, "files": {}}
+    if manifest_path.is_file():
+        manifest = json.loads(manifest_path.read_text(encoding="utf-8"))
+    files = dict(manifest.get("files", {}))
+    files.update({_rel(root, path): digest for path, digest in written.items()})
+    manifest["files"] = dict(sorted(files.items()))
+    manifest_path.parent.mkdir(parents=True, exist_ok=True)
+    manifest_path.write_text(
+        json.dumps(manifest, indent=2, sort_keys=True) + "\n",
+        encoding="utf-8",
+        newline="\n",
+    )
+
+
+def _legacy_skills(root: Path) -> list[tuple[str, str]]:
+    """The :data:`LEGACY_SKILLS` folders present under ``root``, with each one's replacement."""
+    return [
+        (old, new) for old, new in LEGACY_SKILLS.items() if (root / ".claude" / "skills" / old / "SKILL.md").is_file()
+    ]
+
+
+def _report_legacy_skills(root: Path) -> bool:
+    """Print one line per legacy skill folder; returns whether there was any."""
+    found = _legacy_skills(root)
+    for old, new in found:
+        console.print(
+            f"  [yellow]legacy[/yellow] .claude/skills/{old}/ — an old copy, superseded by {new}; "
+            "delete the folder once any local edits are carried over"
+        )
+    return bool(found)
+
+
+def _run_init(
+    directory: Path,
+    ci: bool,
+    no_skills: bool = False,
+    ci_gitlab: bool = False,
+    app_dir: Optional[Path] = None,
+) -> None:
+    root = directory.resolve()
+    app_root = app_dir.resolve() if app_dir is not None else None
+    if app_root is not None and not app_root.is_dir():
+        _error(f"--app-dir: {app_dir} is not a directory")
+        raise typer.Exit(1)
+    root.mkdir(parents=True, exist_ok=True)
+
+    written: dict[Path, str] = {}
+    skipped: list[tuple[Path, str]] = []
+
+    # Core scaffold assets (bundled templates + the generated schema).
+    _write(
+        root / "config.yaml",
+        _bundled("init", "config.yaml").read_text(encoding="utf-8"),
+        written,
+        skipped,
+    )
+    # The starter scenario is for an empty project. In one that already has
+    # scenarios, it would be generated and run against the real app.
+    starter = root / "scenarios" / "example--first-flow.md"
+    if not starter.exists() and any((root / "scenarios").rglob("*.md")):
+        skipped.append((starter, "scenarios/ already has scenarios"))
+    else:
+        _write(
+            starter,
+            _bundled("init", "scenarios", "example--first-flow.md").read_text(encoding="utf-8"),
+            written,
+            skipped,
+        )
+    _write(
+        root / "credentials.yaml.example",
+        _bundled("init", "credentials.yaml.example").read_text(encoding="utf-8"),
+        written,
+        skipped,
+    )
+    _write(root / _SCHEMA_FILENAME, schema_json(), written, skipped)
+
+    if ci:
+        _write(
+            root / ".github" / "workflows" / "steppy.yml",
+            _bundled("ci", "github-actions.yml").read_text(encoding="utf-8"),
+            written,
+            skipped,
+        )
+
+    # A separate flag rather than `--ci <vendor>`: `--ci` is a boolean people
+    # already type, and giving it a value would break every existing invocation.
+    # Writing both files unconditionally would leave a stray .github/ in a GitLab
+    # project, which is noise in a scaffold meant to be read.
+    if ci_gitlab:
+        _write(
+            root / ".gitlab-ci.yml",
+            _bundled("ci", "gitlab-ci.yml").read_text(encoding="utf-8"),
+            written,
+            skipped,
+        )
+
+    # Packaged Claude skills — installed by default so the project's AI
+    # assistant is a Steppy expert on day one (FLAWS §7.1). Routed through
+    # _write so they land in the manifest and never clobber user edits.
+    if not no_skills:
+        for name in SKILL_NAMES:
+            _write(
+                root / ".claude" / "skills" / name / "SKILL.md",
+                _bundled_skill(name, "SKILL.md").read_text(encoding="utf-8"),
+                written,
+                skipped,
+            )
+
+    # The app-side skills, in the app's repository. Recorded in this project's
+    # manifest (as ../<app>/…), so `steppy update` refreshes them with the rest.
+    # When the app is this directory, the loop above already installed them.
+    app_skills: list[Path] = []
+    if app_root is not None and (app_root != root or no_skills):
+        for name in APP_SKILL_NAMES:
+            target = app_root / ".claude" / "skills" / name / "SKILL.md"
+            _write(target, _bundled_skill(name, "SKILL.md").read_text(encoding="utf-8"), written, skipped)
+            if target in written:
+                app_skills.append(target)
+
+    _ensure_gitignore(root, written)
+    _write_manifest(root, written)
+
+    # Report.
+    for path in sorted(written):
+        console.print(f"  [green]create[/green] {_rel(root, path)}")
+    for path, reason in sorted(skipped):
+        console.print(f"  [yellow]skip[/yellow]   {_rel(root, path)} ({reason})")
+    _report_legacy_skills(root)
+
+    if skipped and not written:
+        console.print("\n[yellow]Nothing to do[/yellow] — all scaffold files already exist.")
+        return
+
+    if app_skills:
+        console.print(
+            "\nCommit the skill in the app's repository: it is what an AI assistant working on the app reads."
+        )
+
+    console.print("\n[bold]Next steps:[/bold]")
+    console.print("  1. Edit config.yaml — set your app URLs, roles, and credentials.")
+    console.print("  2. steppy validate   # check your scenarios")
+    console.print("  3. steppy generate   # produce the Playwright tests")
+    console.print("  4. steppy run        # run them")
+
+
+def register_init(app: typer.Typer) -> None:
+    """Register the ``init`` command on the root Typer app."""
+
+    @app.command("init")
+    def init(
+        directory: Path = typer.Argument(
+            Path("."),
+            help="Directory to scaffold (default: current directory).",
+        ),
+        ci: bool = typer.Option(
+            False,
+            "--ci",
+            help="Also write a GitHub Actions workflow (.github/workflows/steppy.yml).",
+        ),
+        ci_gitlab: bool = typer.Option(
+            False,
+            "--ci-gitlab",
+            help="Also write a GitLab CI pipeline (.gitlab-ci.yml).",
+        ),
+        no_skills: bool = typer.Option(
+            False,
+            "--no-skills",
+            help="Do not install the packaged Claude skills into .claude/skills/.",
+        ),
+        app_dir: Optional[Path] = typer.Option(
+            None,
+            "--app-dir",
+            help="Also install the app-side skill (steppy-app-tours: wiring in-app tours into the app's code) "
+            "into this app repository's .claude/skills/. `steppy update` keeps it current.",
+        ),
+    ):
+        """Scaffold a new Steppy project (config, example scenario, schema, gitignore).
+
+        Installs the packaged Claude skills into .claude/skills/ by default so the
+        project's AI assistant knows the Steppy scenario format (use --no-skills to
+        opt out). Safe to re-run in an existing project: it only adds what is
+        missing, and leaves the starter scenario out when scenarios/ has some.
+        """
+        with _cli_errors():
+            _run_init(directory, ci, no_skills, ci_gitlab=ci_gitlab, app_dir=app_dir)