Retire the Python runtime and fold the toolkit into one executable

[sameera]

Epic: Retire the Python runtime and fold the toolkit into one executable

⚠️ Utilization risk: assessed L (1–2 weeks). Fills the sprint with no slack for overruns. Watch for scope creep — the stub deferred at #354 was sized M for runtime-retirement alone, and the toolkit fold is what took it to L.

Description

Nexus is published as one npm package that has, until now, carried two runtimes. The TypeScript half is bundled and run by Node; the other half was a Python package, nexus_gh, reached by spawning python3 against a self-locating entry point. Three consecutive port epics have emptied that half: #351 moved the toolkit shell and the delivery-configuration resolver, #353 moved the story filer, and #352 moved the epic filer. Every capability the toolkit declares now runs in process, and the dispatcher's own registry records that no row delegates any more.

What remains is the scaffolding those ports left standing. The release still stages the whole libs/gh-toolkit/ tree into dist/, so every adopter downloads Python modules nothing executes. The package manifest still declares a python: ">=3.10" interpreter floor and the readme still lists it as a requirement, so adopters are told to install a runtime the product no longer uses. The environment guard still probes PATH for python3 and reports a defect when it cannot find one, and nexus version still publishes what it found. A delegation seam — the interpreter constant, the entry-point locator and the child-process call — sits unimported in the source tree. The component-invocation gate still recognises python <script> as an addressing form it must reject, and still classifies nexus-gh as the Python toolkit by name.

That last point is what turns a cleanup into a decision. nexus-gh exists as a second executable name for one reason: epic #247 collapsed every component-invoked TypeScript capability into verbs on the single nexus executable, and exempted this toolkit because it was written in another language and could not fold. That exemption is now void — the toolkit is TypeScript, bundled by the same builder, published from the same manifest. This epic closes it out. The four capabilities become verbs on nexus, the second binary name and its bundle are withdrawn, and every component body that names nexus-gh is rewritten to the one name. Adopters are left with a package that declares one runtime, ships only what it runs, and answers to a single executable.

Success Metrics

• A built release tree contains no file with a .py extension and no gh-toolkit directory, and the published package manifest declares exactly one engine, node.
• The published manifest declares exactly one binary name, nexus; nexus-gh is absent from bin, from the bundle entry points, and from the release tree.
• No file under libs/ or components/ spawns, names, or documents a Python interpreter, and no source module retains a Python entry-point locator or delegation call.
• Every capability reachable as nexus-gh <capability> before this epic is reachable as a nexus dispatch name after it, and the component-invocation gate passes over the rewritten component set with no waiver added.
• The executable answers to exactly one dispatch name that reports release identity, whatever surface that name is listed on.

Personas

Per docs/product/context.md.

Assumptions

• The three port epics (Port the toolkit shell and the shared delivery-config resolver to TypeScript #351, Port the story filer to TypeScript #353, Port the epic filer to TypeScript #352) are complete and merged, so no capability still needs a Python implementation to fall back to. The registry's own note that no row delegates is treated as the evidence for this.
• Lesson documents under docs/delivery/lessons/ are historical records of epics that happened and are never edited to match a later state, so their references to the Python half stay as written.
• The vendored origin snapshot under libs/origin/v1/ is an archived copy of a superseded component set, not part of what this release builds or ships, so its Python scripts are out of scope.
• Withdrawing the nexus-gh binary name is acceptable to break on. Nexus is pre-1.0 and its own component set is the primary caller; adopters holding scripts that call nexus-gh directly are outside the supported surface.

Out of Scope

• Choosing which release-identity surface survives the version collision, and what becomes of the machine-readable capability listing. Both are design decisions for the decision record; Story 5 fixes only the outcome that exactly one survives.
• A deprecation shim that keeps nexus-gh resolving to the executable for a release or two. The assumption above is that the break is taken cleanly; if that is wrong, the shim is its own scope.
• Any change to what the capabilities do. This epic moves and deletes; a folded capability that behaved differently afterwards would be a defect, not a feature.
• Retiring libs/origin/v1/, which carries Python scripts of its own and is a separate question about how long an archived component set is kept.
• Backlog stub Demonstrate that the retained Python filers file issues unchanged #365 ("Demonstrate that the retained Python filers file issues unchanged") describes a demonstration of a half this epic removes. Closing or rewriting it is a backlog-grooming action, not work inside this epic.

Open Questions