Alpha gate A: single `ownsharp check <path|.sln>` CLI — implementation (design decided, see comments)

[PhysShell]

Agent brief — tier: mid (above-average). ⛔ BLOCKED — do not start until the packaging design decision is recorded in this issue.

Blocker

The design decision — how the Python core ships inside a single tool (embedded runtime vs sidecar download vs interim wrapper until the Rust core lands) — must be made and written into this issue first. It is a one-page decision with long consequences; implementation before it is wasted work.

Goal (once unblocked)

Gate A of docs/notes/alpha-readiness.md: one delightful command — ownsharp check MyApp.sln — from a clean machine to findings in ~3 minutes. Today the extractor is a dotnet tool (ownsharp-extract, P-013) but the core is Python, and the two-step surface lives in scripts/own-check.sh.

Sources of truth

• docs/notes/alpha-readiness.md gate A; docs/proposals/P-013-* (extractor packaging); scripts/own-check.sh / scripts/own-check.ps1 (the behaviour to wrap); action.yml (the Action must keep working on top).

Deliverable (once unblocked)

• One installable command wrapping extract → check → report (github / msbuild / human / sarif formats preserved).
• The 3-minute wow path documented in README's quickstart (coordinate with the front-door issue).
• CI job proving the install-and-run path on a clean runner.

Guardrails

• No behaviour changes to extractor or core — packaging only.
• Windows path must not regress (own-check.ps1 parity).

Done when

install → check → findings reproduces in ~3 minutes on a clean machine, CI-proven; existing Action and scripts keep working.

[PhysShell]

Packaging design decision (recorded — this unblocks the issue)

Decision: one .NET global tool (ownsharp) that embeds BOTH halves — the Roslyn extractor (already PackAsTool, P-013) and the Python core as vendored source — and runs the core on the machine's Python (≥3.11).

Why this shape

The deciding fact: the core is zero-dependency pure Python (pyproject.toml: requires-python >=3.11, no deps). That makes vendoring the ownlang/ source into the NuGet tool package the cheapest option that keeps every load-bearing constraint:

• "One checker" holds literally — the byte-identical Python core renders every verdict; no transpile, no reimplementation, no drift against the differential oracle.
• Extractor/core lockstep becomes a packaging guarantee — one NuGet artifact pins one extractor + one core source tree, so an OWNIR_VERSION mismatch between the two halves cannot happen in the field.
• No per-OS binary matrix — a PyInstaller/PyOxidizer build would mean 3 OS × arch artifacts plus signing/notarization pain, for zero analysis gain.
• The Rust core (P-022) later replaces the sidecar behind the same CLI facade with no UX change — this tool IS the facade the Rust core slots into.

Runtime contract

1. ownsharp check <path|.sln> = extract (in-process) → facts.json → run vendored core via system Python → render (human|github|msbuild|sarif), mirroring scripts/own-check.sh flags (--severity, --fail-on-finding, --emit-facts).
2. Python resolution order: OWN_PYTHON env var → python3 / py -3 on PATH; version-check ≥3.11 up front.
3. No Python found → fail fast with an actionable one-liner (winget/apt/brew command), not an auto-download. Auto-provisioning is explicitly out of v1.
4. Vendored core is unpacked to a per-version cache dir (~/.ownsharp/core/<version>/) on first run; never writes into the analyzed repo.
5. scripts/own-check.sh/.ps1 and action.yml keep working unchanged; the Action may later switch to the tool internally, but that is not part of this issue.

Rejected alternatives (on the record)

• Embed a CPython runtime in the package — heavy, fragile cross-platform, and pointless given a zero-dep core.
• Self-contained PyInstaller core binaries — deferred, optionally revisit only if "works without Python installed" proves to be a real adoption blocker; it is an additive fallback, not the default.
• Wait for the Rust core — the alpha ships now; Rust parity is the replacement path, not the prerequisite.
• Port/transpile the core to C# — a second checker; banned by the ROADMAP design philosophy.

Acceptance (unchanged from the brief)

Clean machine with .NET SDK + Python 3.11: dotnet tool install → ownsharp check → findings in ~3 minutes, CI-proven on ubuntu + windows runners; the no-Python failure message is also pinned by a CI check.

⛔→✅ The blocker is resolved; implementation can start.

---

Generated by Claude Code