nickna / nickna/SharpTS

Epic: No-.NET-required distribution — self-contained managed SKU + Native AOT SKU

Open
#1,324 4 comments 0 reactions 0 assignees View on GitHub
enhancement epic
Dominant language
C#
Stars
154
Forks
4
Avg merge
2h 46m
Merged PRs (30d)
189

Description

## Goal

Offer SharpTS on machines with **no .NET installed** as two deliberately different SKUs:

- **Managed SKU** — self-contained single-file per RID and the default for the full feature set, especially .NET/third-party interop.
- **Native SKU** — Native AOT for the frozen straight-TypeScript surface, with lower startup overhead and explicit diagnostics for unsupported features.

The verified design and measurements live in `docs/plans/native-aot.md`. PE-Packer's completed tracker is nickna/PE-Packer#20; its older AOT markdown is historical context.

## Current status

**All SharpTS source and PE-Packer package-integration work is merged and green on `main`.** SharpTS pins NickNa.PEPacker 1.0.6, and PR #1331 plus its post-merge run passed the exact analyzer ratchet, both managed suites, and the Linux Native AOT compile/bundle smoke. The only remaining release checkpoint is the first SharpTS tag and its six-platform asset validation.

## Completed

- [x] **Track 0 — #1325:** exact AOT/trim/single-file analyzer ratchet (2,585 warnings), six-RID managed self-contained release assets, and release-binary smokes.
- [x] **Phase 1 — #1327:** compile-time NodeRegistry dispatch, reflection-free JSON paths, native fail-fast diagnostics, and `-SharpTSExe` example-harness support.
- [x] **Native compile gate — #1328:** both ILCompiler pipelines run from Native AOT; CA blobs, generic emit fallbacks, required trim/metadata settings, embedded reference index, and PE-Packer bundling are exercised in CI.
- [x] **Managed runtime handoff — #1329:** the native compiler embeds an AnyCPU managed SharpTS runtime, extracts it atomically for compiled soft dependencies, runs `eval()` under CoreCLR, and rejects compiled `child_process.fork` before writing output.
- [x] **Distribution source — #1330:** tagged releases build and execute win-x64/arm64, linux-x64/arm64, and osx-x64/arm64 Native AOT assets on matching-architecture runners. Windows/Linux require SDK-free PE-Packer executable creation; macOS verifies the named built-in-bundler refusal.
- [x] **PE-Packer 1.0.6:** reference policy/index APIs, six embedded Windows/Linux apphosts, and the consumer-controlled SDK-bundler feature switch are released.
- [x] **Published-package integration — #1331:** SharpTS pins 1.0.6 and its permanent native smoke creates and executes a PE-Packer bundle with `DOTNET_ROOT` empty.

## Release checkpoint

- [x] All required SharpTS and PE-Packer source changes are merged.
- [x] NickNa.PEPacker 1.0.6 is published with embedded apphosts and the SDK-bundler feature switch.
- [x] SharpTS consumes 1.0.6; its PR and post-merge `main` CI are green.
- [ ] Tag the first SharpTS release, confirm all six native jobs run, and verify all twelve managed/native archives are attached.

The SharpTS tag is now unblocked. Treat its six native release jobs and twelve attached managed/native archives as the cross-platform acceptance event.

## Decisions settled

- The managed SKU remains the full-feature default; Native AOT is the straight-TypeScript SKU.
- `SharpTS.Sdk` stays managed and RID-neutral. It already runs under `dotnet build` and forwards the project `ReferencePath` through `-r`; substituting the native compiler would lose its interop contract while multiplying package payloads without removing a .NET prerequisite.
- Native distribution is the standalone `sharpts-native--` release asset. A separate opt-in native MSBuild SDK is future work only if measurements justify it.
- Built-in `--target exe` remains Windows/Linux-only until PE-Packer implements Mach-O adjustment and ad-hoc signing.
- Native losses remain explicit: interpreter third-party DLL loading, compile-time third-party refs, `--verify`, `--gen-decl`, compiled `child_process.fork`, and unsupported runtime-generated generic/interoperability shapes route users to the managed SKU.

## Measured facts worth preserving

- Native interpretation moved from roughly 9x slower than JIT to faster than JIT after source-generated dispatch (local dispatch-heavy median about 1,370 ms native vs 1,648 ms JIT).
- Native compile, multi-module output, embedded managed-runtime extraction, and PE-Packer bundle execution pass on win-arm64 locally and linux-x64 in CI.
- PE-Packer's feature switch removed every `SdkBundler` implementation symbol from the win-arm64 ILC map and saved 134,144 bytes (2.91%) in its current smoke image.
- With PE-Packer 1.0.6, local win-arm64 SharpTS created and ran a 355,651-byte target executable with `DOTNET_ROOT` empty; the native SharpTS image contained zero `InvokeSdkBundler` occurrences.

## Non-blocking follow-up after the first release

- Define and test any BCL interop surface we want to promise in the native SKU; the known dynamic-event edge remains outside the straight-TypeScript release contract.
- File/investigate the pre-existing MetadataLoadContext-types-into-`TypeBuilder` limitation upstream if native compile-time third-party references become a goal.
- The optional `Packaging/` dependency reduction and an opt-in native SDK package are separate optimizations, not AOT release blockers.

Contributor guide

Open the contributing guide

Research direction

Start with docs/plans/native-aot.md and the existing six native release jobs on main. Tag the first SharpTS release, confirm all six native jobs run, and verify that the twelve managed/native archives are attached for the six listed RIDs.

Written by the indexing model from the issue text.

Assessment

Tech stack
csharp, typescript
Domain
ci-cd, release
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.