From 8ab88e5411c7d4c94bf1ce287b4a926f0ceebf40 Mon Sep 17 00:00:00 2001 From: Gordon Breuer Date: Mon, 26 Oct 2026 11:47:21 +0000 Subject: [PATCH 1/2] Reduce startup overhead and benchmark native single-file launches --- .github/workflows/startup-benchmark.yml | 67 ++++++++ .../2026-10-26-linux-baseline.json | 121 ++++++++++++++ .../2026-10-26-linux-compressed.json | 121 ++++++++++++++ .../2026-10-26-linux-optimized.json | 155 ++++++++++++++++++ docs/performance/2026-10-26-startup.md | 97 +++++++++++ docs/wiki/Installation.md | 15 ++ scripts/benchmark_startup.py | 149 +++++++++++++++++ scripts/cli_smoke.py | 4 + scripts/terminal_smoke.py | 24 +++ src/SidePulse.Cli/CliApplication.cs | 116 +++++++++++++ src/SidePulse.Cli/HostManagement.cs | 5 +- src/SidePulse.Cli/Program.cs | 110 +------------ src/SidePulse.Cli/ShellSession.cs | 4 +- 13 files changed, 879 insertions(+), 109 deletions(-) create mode 100644 .github/workflows/startup-benchmark.yml create mode 100644 docs/performance/2026-10-26-linux-baseline.json create mode 100644 docs/performance/2026-10-26-linux-compressed.json create mode 100644 docs/performance/2026-10-26-linux-optimized.json create mode 100644 docs/performance/2026-10-26-startup.md create mode 100644 scripts/benchmark_startup.py create mode 100644 src/SidePulse.Cli/CliApplication.cs diff --git a/.github/workflows/startup-benchmark.yml b/.github/workflows/startup-benchmark.yml new file mode 100644 index 0000000..6c24055 --- /dev/null +++ b/.github/workflows/startup-benchmark.yml @@ -0,0 +1,67 @@ +name: Startup benchmark +on: + pull_request: + paths: + - 'src/**' + - 'Directory.*' + - 'scripts/benchmark_startup.py' + - '.github/workflows/startup-benchmark.yml' + workflow_dispatch: + inputs: + baseline_ref: + description: Baseline commit or tag to publish with the same SDK + required: true + default: 26f64b9f864348e51684bf68f49095f151a3ba27 +permissions: + contents: read +concurrency: + group: startup-${{ github.ref }} + cancel-in-progress: true +jobs: + measure: + strategy: + fail-fast: false + matrix: + os: [windows-latest, ubuntu-latest, macos-latest] + runs-on: ${{ matrix.os }} + timeout-minutes: 15 + steps: + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7 + with: + path: candidate + persist-credentials: false + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7 + with: + path: baseline + ref: ${{ inputs.baseline_ref || github.event.pull_request.base.sha }} + persist-credentials: false + - uses: actions/setup-dotnet@a98b56852c35b8e3190ac28c8c2271da59106c68 # v6 + with: + dotnet-version: 10.0.x + - name: Publish and compare isolated native bundles + shell: pwsh + run: | + $prefix = if ($IsWindows) { 'win' } elseif ($IsMacOS) { 'osx' } else { 'linux' } + $rid = "$prefix-$([System.Runtime.InteropServices.RuntimeInformation]::ProcessArchitecture.ToString().ToLowerInvariant())" + $binary = if ($IsWindows) { 'spn.exe' } else { 'spn' } + dotnet --info > sdk-info.txt + foreach ($source in @('baseline', 'candidate')) { + dotnet publish "$source/src/SidePulse.Cli" -c Release -r $rid --self-contained true -p:NuGetLockFilePath=obj/packages.publish.lock.json -o "$source/published" + if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE } + } + $before = git -C baseline rev-parse HEAD + $after = git -C candidate rev-parse HEAD + python candidate/scripts/benchmark_startup.py "baseline/published/$binary" --samples 9 --label $before --output baseline.json + if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE } + python candidate/scripts/benchmark_startup.py "candidate/published/$binary" --samples 9 --label $after --output candidate.json --compare baseline.json + if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE } + - name: Upload measurements and build environment + if: always() + uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2 + with: + name: startup-${{ runner.os }} + path: | + baseline.json + candidate.json + sdk-info.txt + retention-days: 30 diff --git a/docs/performance/2026-10-26-linux-baseline.json b/docs/performance/2026-10-26-linux-baseline.json new file mode 100644 index 0000000..9c08ae7 --- /dev/null +++ b/docs/performance/2026-10-26-linux-baseline.json @@ -0,0 +1,121 @@ +{ + "schema_version": 1, + "label": "26f64b9-baseline", + "platform": "Linux-6.18.55-x86_64-with-glibc2.41", + "architecture": "x86_64", + "processor": "", + "logical_cpus": 3, + "python": "3.12.14", + "executable_sha256": "9d3ea52f7fc8d22e2dff491cb1747514643db799da489b04b70fe956c58a48c7", + "executable_bytes": 76610475, + "executable_gzip_bytes": 33159265, + "extracted_bytes": 0, + "extracted_files": [], + "samples_per_mode": 9, + "results": { + "version": { + "empty_bundle_cache": { + "samples_ms": [ + 148.98, + 127.45, + 142.65, + 138.52, + 136.94, + 124.39, + 136.71, + 127.36, + 136.07 + ], + "median_ms": 136.71, + "min_ms": 124.39, + "max_ms": 148.98 + }, + "cached_bundle": { + "samples_ms": [ + 127.5, + 130.29, + 125.13, + 134.55, + 137.77, + 145.04, + 140.88, + 133.7, + 125.39 + ], + "median_ms": 133.7, + "min_ms": 125.13, + "max_ms": 145.04 + } + }, + "state_preview": { + "empty_bundle_cache": { + "samples_ms": [ + 162.0, + 155.58, + 163.04, + 172.06, + 172.45, + 163.97, + 185.22, + 170.78, + 175.74 + ], + "median_ms": 170.78, + "min_ms": 155.58, + "max_ms": 185.22 + }, + "cached_bundle": { + "samples_ms": [ + 171.82, + 173.08, + 168.58, + 163.84, + 175.19, + 172.55, + 179.07, + 184.86, + 170.26 + ], + "median_ms": 172.55, + "min_ms": 163.84, + "max_ms": 184.86 + } + }, + "home": { + "empty_bundle_cache": { + "samples_ms": [ + 514.89, + 457.32, + 455.02, + 450.45, + 467.5, + 455.27, + 465.33, + 450.49, + 449.22 + ], + "median_ms": 455.27, + "min_ms": 449.22, + "max_ms": 514.89 + }, + "cached_bundle": { + "samples_ms": [ + 450.8, + 449.66, + 469.67, + 455.02, + 453.06, + 464.61, + 538.6, + 512.48, + 524.06 + ], + "median_ms": 464.61, + "min_ms": 449.66, + "max_ms": 538.6 + } + } + }, + "home_measurement": "Unix PTY at 100x30, first complete Home input guide", + "limits": "Empty bundle cache is not cold OS page cache. Alternating cold/warm runs; no hardware or bridge delivery. Times include process startup, not just managed Main. gzip bytes are executable-only, not the complete release archive." +} diff --git a/docs/performance/2026-10-26-linux-compressed.json b/docs/performance/2026-10-26-linux-compressed.json new file mode 100644 index 0000000..8b83314 --- /dev/null +++ b/docs/performance/2026-10-26-linux-compressed.json @@ -0,0 +1,121 @@ +{ + "schema_version": 1, + "label": "26f64b9-compressed", + "platform": "Linux-6.18.55-x86_64-with-glibc2.41", + "architecture": "x86_64", + "processor": "", + "logical_cpus": 3, + "python": "3.12.14", + "executable_sha256": "095ca7500b081bbd2686d2aef8ca7d7b751d951edb925b7a5aec83881538ffe8", + "executable_bytes": 40573373, + "executable_gzip_bytes": 33397573, + "extracted_bytes": 0, + "extracted_files": [], + "samples_per_mode": 9, + "results": { + "version": { + "empty_bundle_cache": { + "samples_ms": [ + 225.33, + 213.58, + 196.03, + 205.14, + 194.69, + 211.46, + 209.51, + 210.05, + 194.09 + ], + "median_ms": 209.51, + "min_ms": 194.09, + "max_ms": 225.33 + }, + "cached_bundle": { + "samples_ms": [ + 204.52, + 193.42, + 207.66, + 211.3, + 202.99, + 197.75, + 193.89, + 204.02, + 206.18 + ], + "median_ms": 204.02, + "min_ms": 193.42, + "max_ms": 211.3 + } + }, + "state_preview": { + "empty_bundle_cache": { + "samples_ms": [ + 232.05, + 238.23, + 244.81, + 468.24, + 290.1, + 247.22, + 233.8, + 239.64, + 413.73 + ], + "median_ms": 244.81, + "min_ms": 232.05, + "max_ms": 468.24 + }, + "cached_bundle": { + "samples_ms": [ + 250.4, + 242.64, + 467.02, + 310.57, + 287.94, + 242.27, + 240.89, + 348.84, + 266.28 + ], + "median_ms": 266.28, + "min_ms": 240.89, + "max_ms": 467.02 + } + }, + "home": { + "empty_bundle_cache": { + "samples_ms": [ + 542.57, + 509.71, + 534.39, + 508.87, + 533.97, + 527.29, + 519.1, + 511.95, + 560.07 + ], + "median_ms": 527.29, + "min_ms": 508.87, + "max_ms": 560.07 + }, + "cached_bundle": { + "samples_ms": [ + 589.7, + 527.65, + 524.56, + 528.51, + 555.26, + 527.4, + 515.02, + 522.36, + 524.96 + ], + "median_ms": 527.4, + "min_ms": 515.02, + "max_ms": 589.7 + } + } + }, + "home_measurement": "Unix PTY at 100x30, first complete Home input guide", + "limits": "Empty bundle cache is not cold OS page cache. Alternating cold/warm runs; no hardware or bridge delivery. Times include process startup, not just managed Main. gzip bytes are executable-only, not the complete release archive." +} diff --git a/docs/performance/2026-10-26-linux-optimized.json b/docs/performance/2026-10-26-linux-optimized.json new file mode 100644 index 0000000..da52f76 --- /dev/null +++ b/docs/performance/2026-10-26-linux-optimized.json @@ -0,0 +1,155 @@ +{ + "schema_version": 1, + "label": "optimized", + "platform": "Linux-6.18.55-x86_64-with-glibc2.41", + "architecture": "x86_64", + "processor": "", + "logical_cpus": 3, + "python": "3.12.14", + "executable_sha256": "7d5149d9ca403cbb6ac4b4d9a429e93b1d63f6987065f03a76e17f4dd89cef47", + "executable_bytes": 76610987, + "executable_gzip_bytes": 33159461, + "extracted_bytes": 0, + "extracted_files": [], + "samples_per_mode": 9, + "results": { + "version": { + "empty_bundle_cache": { + "samples_ms": [ + 28.35, + 30.68, + 34.65, + 29.19, + 29.57, + 26.99, + 29.76, + 29.22, + 29.0 + ], + "median_ms": 29.22, + "min_ms": 26.99, + "max_ms": 34.65 + }, + "cached_bundle": { + "samples_ms": [ + 30.6, + 27.57, + 32.06, + 28.26, + 31.12, + 28.75, + 29.75, + 29.15, + 27.92 + ], + "median_ms": 29.15, + "min_ms": 27.57, + "max_ms": 32.06 + } + }, + "state_preview": { + "empty_bundle_cache": { + "samples_ms": [ + 171.36, + 176.45, + 176.24, + 188.97, + 182.97, + 175.11, + 183.06, + 176.61, + 184.67 + ], + "median_ms": 176.61, + "min_ms": 171.36, + "max_ms": 188.97 + }, + "cached_bundle": { + "samples_ms": [ + 169.04, + 158.64, + 159.28, + 174.94, + 187.98, + 166.24, + 187.52, + 172.75, + 163.25 + ], + "median_ms": 169.04, + "min_ms": 158.64, + "max_ms": 187.98 + } + }, + "home": { + "empty_bundle_cache": { + "samples_ms": [ + 177.85, + 197.93, + 196.68, + 189.95, + 230.9, + 193.38, + 185.61, + 180.83, + 199.79 + ], + "median_ms": 193.38, + "min_ms": 177.85, + "max_ms": 230.9 + }, + "cached_bundle": { + "samples_ms": [ + 186.88, + 189.26, + 187.07, + 181.59, + 389.52, + 215.76, + 187.99, + 199.62, + 178.68 + ], + "median_ms": 187.99, + "min_ms": 178.68, + "max_ms": 389.52 + } + } + }, + "home_measurement": "Unix PTY at 100x30, first complete Home input guide", + "limits": "Empty bundle cache is not cold OS page cache. Alternating cold/warm runs; no hardware or bridge delivery. Times include process startup, not just managed Main. gzip bytes are executable-only, not the complete release archive.", + "comparison": { + "version/empty_bundle_cache": { + "before_ms": 136.71, + "after_ms": 29.22, + "change_percent": -78.6 + }, + "version/cached_bundle": { + "before_ms": 133.7, + "after_ms": 29.15, + "change_percent": -78.2 + }, + "state_preview/empty_bundle_cache": { + "before_ms": 170.78, + "after_ms": 176.61, + "change_percent": 3.4 + }, + "state_preview/cached_bundle": { + "before_ms": 172.55, + "after_ms": 169.04, + "change_percent": -2.0 + }, + "home/empty_bundle_cache": { + "before_ms": 455.27, + "after_ms": 193.38, + "change_percent": -57.5 + }, + "home/cached_bundle": { + "before_ms": 464.61, + "after_ms": 187.99, + "change_percent": -59.5 + } + }, + "regression_budget": "median <= baseline * 1.5 + 100ms; executable <= baseline * 1.1", + "regressions": [] +} diff --git a/docs/performance/2026-10-26-startup.md b/docs/performance/2026-10-26-startup.md new file mode 100644 index 0000000..e4aaacd --- /dev/null +++ b/docs/performance/2026-10-26-startup.md @@ -0,0 +1,97 @@ +# Startup and size baseline — 2026-10-26 + +Issue: [#25](https://github.com/Anheledir/SidePulse.NET/issues/25). +AOT/trimming follow-up: [#26](https://github.com/Anheledir/SidePulse.NET/issues/26). + +## Method + +Release, self-contained single-file linux-x64, .NET SDK 10.0.100/runtime 10.0.0, +Linux 6.18.55/glibc 2.41, Intel Xeon Platinum 8573C, three logical CPUs exposed. +Baseline source: `26f64b9f864348e51684bf68f49095f151a3ba27`. The optimized +working-tree build is identified by its executable SHA-256 in the raw report. +Nine paired launches per command/cache mode; report medians, with all samples +retained below. Each pair starts with a new isolated bundle extraction directory +and then reuses it. This is **not cold OS page-cache or cold-boot measurement**. +Measurements include process launch through command exit; Home ends at its first +complete input guide in a real Unix PTY at 100x30, before selecting explicit Quit. +The application config location is isolated and must remain absent. No device, +phone token, bridge request or credential vault is required. + +## Local Linux results + +| Build / measurement | Empty bundle cache | Reused bundle cache | +|---|---:|---:| +| Baseline `--version` | 136.71 ms | 133.70 ms | +| Optimized `--version` | 29.22 ms | 29.15 ms | +| Compressed baseline `--version` | 209.51 ms | 204.02 ms | +| Baseline state preview | 170.78 ms | 172.55 ms | +| Optimized state preview | 176.61 ms | 169.04 ms | +| Compressed baseline state preview | 244.81 ms | 266.28 ms | +| Baseline Home | 455.27 ms | 464.61 ms | +| Optimized Home | 193.38 ms | 187.99 ms | +| Compressed baseline Home | 527.29 ms | 527.40 ms | + +Warm Home improves about 60%; the bare version probe improves about 78%. +State-preview differences are small enough to treat as shared-machine noise. + +| Build | Executable bytes | Executable gzip bytes (level 6) | Observed extraction bytes | +|---|---:|---:|---:| +| Baseline | 76,610,475 | 33,159,265 | 0 | +| Optimized | 76,610,987 | 33,159,461 | 0 | +| Compressed baseline | 40,573,373 | 33,397,573 | 0 | + +Gzip sizes refer to the executable only, not complete release archives/manifests. +The compressed experiment uses `EnableCompressionInSingleFile=true` against the +baseline. It cuts the managed bundle's on-disk executable size by about 47%, but +adds roughly 60–95 ms startup cost here and slightly increases gzip download size. +**Keep bundle compression disabled.** It works against the observed startup goal. +No trimming/AOT or framework-dependent requirement is introduced by this change. + +## Cost attribution and changes + +- Home formerly waited up to 300 ms for a missing host. It now probes for an + immediately available connection, with a bounded response deadline. Normal host + start/status/stop retain their existing wait/cancellation behavior. A busy or + missing endpoint is labeled **not connected**, rather than declaring it stopped. + PTY smoke verifies both missing-host navigation and an actual running dry-run host. +- Bare `--version`/`-v` now use a small bootstrap without terminal setup or the + full command registry. Version calls with other flags retain normal parsing; + quiet/noninteractive output equivalence is tested. The ~29 ms result is a + runtime-plus-minimal-managed-work proxy, **not an isolated JIT profiler result**. +- In this Linux .NET 10 bundle, both an isolated extraction-directory inventory + and host tracing observed no extracted native files for these commands. Empty + versus reused extraction caches have no convincing startup premium here. + Do not attribute these Linux timings to disk extraction or generalize them to + Windows/macOS. The publisher still allows extraction when the runtime needs it. +- The CLI and Core assemblies are about 563 KB and 220 KB respectively in this + build; Spectre.Console is about 848 KB, Spectre.Console.Cli 432 KB and QRCoder + 204 KB. The self-contained runtime/framework dominates the 76.6 MB executable. + Embedded docs/licenses remain available. AOT/trimming compatibility and actual + runtime/JIT/resource profiling remain the next investigation under #26. + +## Reproduction and regression budget + +```bash +dotnet publish src/SidePulse.Cli -c Release -r linux-x64 --self-contained true -p:NuGetLockFilePath=obj/packages.publish.lock.json -o /tmp/spn-publish +python3 scripts/benchmark_startup.py /tmp/spn-publish/spn --samples 9 --label candidate --output /tmp/startup.json +``` + +Publish a baseline into a separate directory with the same SDK, measure it first, +then pass `--compare /tmp/baseline.json` for the candidate. Keep individual samples +and executable hashes. Do not run benchmark pairs alongside heavy build/test work. +The initial shared-runner guard allows a median up to `baseline * 1.5 + 100 ms` +and executable growth up to 10%. This intentionally catches severe regressions, +not small scheduling noise; it is not a promise about every user's machine. + +The **Startup benchmark** workflow builds baseline/candidate with one SDK on +native Windows/Linux/macOS, uploads raw reports and SDK information, and applies +that budget. Its manual baseline defaults to the pre-optimization commit above. +Windows command timings and cache inventories are automated; **Windows Home needs +an actual console/ConPTY measurement** and is not represented by redirected help. +Native architecture/OS numbers must remain distinct from cross-built packages. + +Raw local reports: + +- [Baseline](2026-10-26-linux-baseline.json) +- [Optimized](2026-10-26-linux-optimized.json) +- [Compressed experiment](2026-10-26-linux-compressed.json) diff --git a/docs/wiki/Installation.md b/docs/wiki/Installation.md index 87945f6..23b59c7 100644 --- a/docs/wiki/Installation.md +++ b/docs/wiki/Installation.md @@ -98,3 +98,18 @@ state; no process is forcibly killed. Settings remain available for reinstall. Installation registration and PATH ownership are stored in `installation.json` beside application settings, separate from protected phone credentials. `install --status` and `doctor` show installation context without exposing credentials. + +## Startup and executable size + +Self-contained bundles include the .NET runtime. A large executable does not imply +that the whole application is unpacked on each launch. Native extraction depends +on runtime/platform; local Linux .NET 10 startup measurements observed no extracted +files for version, state preview and Home. Empty extraction-cache and warm-cache +measurements must be distinguished from cold OS startup. + +Home probes the host without waiting for an absent endpoint, and bare version +checks use a lightweight bootstrap. Bundle compression remains disabled: the +measured smaller executable incurred additional startup CPU cost and did not +reduce the gzip download. See the repository's +[startup report](https://github.com/Anheledir/SidePulse.NET/blob/main/docs/performance/2026-10-26-startup.md) for numbers, limits and +reproduction; Native AOT/trimming remains a separate investigation. diff --git a/scripts/benchmark_startup.py b/scripts/benchmark_startup.py new file mode 100644 index 0000000..bdd9d2c --- /dev/null +++ b/scripts/benchmark_startup.py @@ -0,0 +1,149 @@ +"""Measure isolated single-file launches; cold means empty bundle cache, not cold OS cache.""" +import argparse +import gzip +import hashlib +import json +import os +from pathlib import Path +import platform +import statistics +import subprocess +import tempfile +import time + + +def launch(executable, arguments, environment, home=False): + start = time.perf_counter() + if not home: + result = subprocess.run([str(executable), *arguments], env=environment, + capture_output=True, timeout=15) + if result.returncode: + raise RuntimeError(f'Benchmark command failed: {arguments}; exit {result.returncode}') + return (time.perf_counter() - start) * 1000 + import fcntl + import pty + import select + import struct + import termios + master, slave = pty.openpty() + fcntl.ioctl(slave, termios.TIOCSWINSZ, struct.pack('HHHH', 30, 100, 0, 0)) + child = subprocess.Popen([str(executable)], stdin=slave, stdout=slave, stderr=slave, env=environment) + os.close(slave) + output = b'' + try: + deadline = time.monotonic() + 15 + while time.monotonic() < deadline: + if select.select([master], [], [], 0.05)[0]: + try: + output += os.read(master, 65536) + except OSError: + break + if b'Esc back' in output and b'Last action:' in output: + elapsed = (time.perf_counter() - start) * 1000 + # A new PTY is not necessarily the controlling terminal; use the + # explicit menu action rather than relying on its signal handling. + os.write(master, b'\x1b[A\r') + while child.poll() is None and time.monotonic() < deadline: + if select.select([master], [], [], 0.05)[0]: + try: + os.read(master, 65536) + except OSError: + break + if child.wait(timeout=2) != 0: + raise RuntimeError('Home failed to exit cleanly') + return elapsed + if child.poll() is not None: + break + raise RuntimeError('Home readiness marker not observed') + finally: + if child.poll() is None: + child.kill() + child.wait(timeout=5) + os.close(master) + + +def summary(values): + ordered = sorted(values) + return {'samples_ms': [round(v, 2) for v in values], + 'median_ms': round(statistics.median(values), 2), + 'min_ms': round(ordered[0], 2), 'max_ms': round(ordered[-1], 2)} + + +def benchmark(executable, samples=7, label=None): + executable = Path(executable).resolve() + with tempfile.TemporaryDirectory(prefix='spn startup ') as temporary: + root = Path(temporary) + environment = dict(os.environ, SIDEPULSE_NET_HOME=str(root / 'config'), + TERM='xterm-256color', COLORTERM='truecolor') + environment.pop('NO_COLOR', None) + modes = [('version', ['--version']), ('state_preview', ['state', 'working', '--dry-run', '--json'])] + if os.name != 'nt': + modes.append(('home', [])) + results = {} + cache_files = [] + for name, arguments in modes: + cold, warm = [], [] + for index in range(samples): + cache = root / f'{name}-{index}' + environment['DOTNET_BUNDLE_EXTRACT_BASE_DIR'] = str(cache) + cold.append(launch(executable, arguments, environment, home=name == 'home')) + warm.append(launch(executable, arguments, environment, home=name == 'home')) + if not cache_files: + cache_files = [{'name': p.name, 'bytes': p.stat().st_size} + for p in sorted(cache.rglob('*')) if p.is_file()] + results[name] = {'empty_bundle_cache': summary(cold), 'cached_bundle': summary(warm)} + if (root / 'config').exists(): + raise RuntimeError('Read-only benchmark unexpectedly created application configuration') + # gzip is measured outside launch timings, at the release tar compression level. + data = executable.read_bytes() + return {'schema_version': 1, 'label': label, 'platform': platform.platform(), + 'architecture': platform.machine(), 'processor': platform.processor(), + 'logical_cpus': os.cpu_count(), 'python': platform.python_version(), + 'executable_sha256': hashlib.sha256(data).hexdigest(), 'executable_bytes': len(data), + 'executable_gzip_bytes': len(gzip.compress(data, compresslevel=6, mtime=0)), + 'extracted_bytes': sum(f['bytes'] for f in cache_files), 'extracted_files': cache_files, + 'samples_per_mode': samples, 'results': results, + 'home_measurement': 'Not measured: Windows requires a real console/ConPTY measurement' if os.name == 'nt' else 'Unix PTY at 100x30, first complete Home input guide', + 'limits': 'Empty bundle cache is not cold OS page cache. Alternating cold/warm runs; no hardware or bridge delivery. Times include process startup, not just managed Main. gzip bytes are executable-only, not the complete release archive.'} + + +def main(): + parser = argparse.ArgumentParser(description=__doc__) + parser.add_argument('executable') + parser.add_argument('--samples', type=int, default=7) + parser.add_argument('--label') + parser.add_argument('--compare', type=Path, help='Compare against a prior report from the same machine') + parser.add_argument('--output', type=Path, required=True) + args = parser.parse_args() + if not 1 <= args.samples <= 100: + parser.error('--samples must be 1..100') + result = benchmark(args.executable, args.samples, args.label) + if args.compare: + baseline = json.loads(args.compare.read_text(encoding='utf-8')) + comparison = {} + regressions = [] + for mode, measurements in result['results'].items(): + for cache, values in measurements.items(): + previous = baseline['results'][mode][cache]['median_ms'] + current = values['median_ms'] + comparison[f'{mode}/{cache}'] = {'before_ms': previous, 'after_ms': current, + 'change_percent': round((current / previous - 1) * 100, 1)} + # Shared CI runners are noisy. Catch severe regressions, not small jitter. + if current > previous * 1.5 + 100: + regressions.append(f'{mode}/{cache}') + if result['executable_bytes'] > baseline['executable_bytes'] * 1.1: + regressions.append('executable growth >10%') + result['comparison'] = comparison + result['regression_budget'] = 'median <= baseline * 1.5 + 100ms; executable <= baseline * 1.1' + result['regressions'] = regressions + args.output.parent.mkdir(parents=True, exist_ok=True) + args.output.write_text(json.dumps(result, indent=2) + '\n', encoding='utf-8') + print(f"{args.label or 'spn'}: {result['executable_bytes']} executable bytes; {result['extracted_bytes']} extracted bytes") + for name, measurements in result['results'].items(): + print(name, {cache: values['median_ms'] for cache, values in measurements.items()}) + if result.get('regressions'): + raise SystemExit('Startup regression budget exceeded: ' + ', '.join(result['regressions'])) + + +if __name__ == '__main__': + main() diff --git a/scripts/cli_smoke.py b/scripts/cli_smoke.py index 34b85eb..cada94b 100644 --- a/scripts/cli_smoke.py +++ b/scripts/cli_smoke.py @@ -18,6 +18,10 @@ def run(*args, input=None): assert result.returncode == 0, (args, result.stdout, result.stderr) return result + version = run('--version').stdout + assert version and version == run('-v').stdout + assert run('--version', '--quiet').stdout == '' + assert version == run('--version', '--no-interactive').stdout preview = json.loads(run('state', 'working', '--dry-run', '--json').stdout) assert preview['program'] == 'off\n#00e5ff 1.6s pulse\nrepeat' malformed = run('hook', 'preToolUse', input='invalid') diff --git a/scripts/terminal_smoke.py b/scripts/terminal_smoke.py index 2894ee8..85d072b 100644 --- a/scripts/terminal_smoke.py +++ b/scripts/terminal_smoke.py @@ -72,6 +72,7 @@ def finish(self): menu = Terminal([]) try: + menu.until('Host: not connected') menu.until('Quit') menu.send(b'\x1b') # Esc at Home never exits. menu.until('Quit') @@ -154,6 +155,29 @@ def finish(self): if restarted.process.poll() is None: restarted.process.kill() + host = subprocess.Popen([executable, 'host', 'run', '--dry-run', '--plain'], + stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL, env=env) + connected = None + try: + for _ in range(20): + status = subprocess.run([executable, 'host', 'status', '--json'], capture_output=True, + text=True, env=env, timeout=5) + if status.returncode == 0 and json.loads(status.stdout)['Running']: + break + assert host.poll() is None, 'Dry-run host exited before readiness' + else: + raise AssertionError('Dry-run host did not become ready') + connected = Terminal([]) + connected.until('Host: running') + connected.until('Quit') + connected.send(b'\x1b[A\r') + connected.finish() + finally: + if connected is not None and connected.process.poll() is None: + connected.process.kill() + host.terminate() + host.wait(timeout=5) + file = root / 'custom.LED' editor = Terminal(['animations', 'edit', '--file', str(file), '--model', 'dot']) try: diff --git a/src/SidePulse.Cli/CliApplication.cs b/src/SidePulse.Cli/CliApplication.cs new file mode 100644 index 0000000..a76816e --- /dev/null +++ b/src/SidePulse.Cli/CliApplication.cs @@ -0,0 +1,116 @@ +using Spectre.Console; +using Spectre.Console.Cli; +using SidePulse.Core; + +namespace SidePulse.Cli; + +internal static class CliApplication +{ + public static int Run(string[] args) + { + args = TerminalMode.Configure(args); + var session = ShellSession.ShouldStart(args); + if (!session) + { + try { args = Interactive.Resolve(args) ?? []; } + catch (Exception ex) { return TerminalMode.Error(ex); } + if (args.Length == 0) return 0; + } + static string[] Normalize(string[] command) + { + if (command.Length == 1 && command[0] == "update") return ["update", "check"]; + if (command.Length >= 1 && command[0] == "host" && (command.Length == 1 || command[1].StartsWith('-') && command[1] is not "--help" and not "-h")) + return new[] { "host", "run" }.Concat(command.Skip(1)).ToArray(); + return command; + } + args = Normalize(args); + using var logOutput = HostLogs.Redirect(args); + var app = new CommandApp(); + app.Configure(config => + { + config.ConfigureConsole(AnsiConsole.Console); + config.SetApplicationName(ApplicationIdentity.Command); + config.SetApplicationVersion(ProjectInfo.Version); + config.AddCommand("settings").WithDescription("Show, set or reset persistent non-secret defaults."); + config.AddCommand("install").WithDescription("Install for this user; optionally configure user PATH."); + config.AddCommand("uninstall").WithDescription("Remove the managed installation while retaining settings and phone links."); + config.AddCommand("internal-uninstall").IsHidden(); + config.AddBranch("animations", animations => + { + animations.SetDescription("Create, validate, preview and send Dot / Pro LED patterns."); + animations.AddCommand("list"); + animations.AddCommand("preview"); + animations.AddCommand("validate"); + animations.AddCommand("apply"); + animations.AddCommand("edit"); + animations.AddCommand("import"); + animations.AddCommand("export"); + }); + config.AddBranch("profiles", profiles => + { + profiles.AddCommand("set"); + profiles.AddCommand("show"); + }); + config.AddBranch("about", about => + { + about.AddCommand("info"); + about.AddCommand("website"); + about.AddCommand("github"); + about.AddCommand("upstream"); + about.AddCommand("credits"); + about.AddCommand("licenses"); + }); + config.AddCommand("docs"); + config.AddBranch("update", update => + { + update.SetDescription("Check GitHub releases and install verified self-contained updates."); + update.AddCommand("check"); + update.AddCommand("install"); + update.AddCommand("status"); + }); + config.AddCommand("internal-update").IsHidden(); + config.AddBranch("link", links => + { + links.SetDescription("Pair and manage protected iPhone links."); + links.AddCommand("pair").WithDescription("Pair an iPhone by QR code."); + links.AddCommand("list").WithDescription("List saved phones without exposing tokens."); + links.AddCommand("import").WithDescription("Save an existing token from an environment variable."); + links.AddCommand("default").WithDescription("Choose the default saved phone."); + links.AddCommand("rename").WithDescription("Rename a phone alias."); + links.AddCommand("remove").WithDescription("Remove a local phone link."); + }); + config.AddCommand("doctor").WithDescription("Check local setup without sending to devices or the network."); + config.AddCommand("devices").WithDescription("List mounted SidePulse devices."); + config.AddCommand("state").WithDescription("Display an agent state on USB or iPhone."); + config.AddCommand("write").WithDescription("Send a raw LED program with firmware envelope checks."); + config.AddCommand("dashboard").WithDescription("Show devices and built-in status profiles."); + config.AddBranch("host", host => + { + host.SetDescription("Manage the shared agent host."); + host.AddCommand("run").WithDescription("Run in the foreground."); + host.AddCommand("start").WithDescription("Start a detached host with bounded local logs."); + host.AddCommand("reset").WithDescription("Clear stale sessions without inventing completion."); + host.AddCommand("status").WithDescription("Query the running host and agent sessions."); + host.AddCommand("stop").WithDescription("Request graceful shutdown over current-user IPC."); + host.AddCommand("logs").WithDescription("Show recent background host log lines."); + }); + config.AddBranch("agents", agents => + { + agents.SetDescription("Set up Copilot, Codex, Claude Code, Kiro and OpenCode lifecycle integrations."); + agents.AddCommand("list"); + agents.AddCommand("install"); + agents.AddCommand("status"); + agents.AddCommand("uninstall"); + }); + config.AddCommand("hook").IsHidden(); + config.AddCommand("hook-config").WithDescription("Generate opt-in Copilot CLI hook configuration."); + config.SetExceptionHandler((exception, _) => + { + // Credential-bearing HTTP exception details are never displayed. + return TerminalMode.Error(exception); + }); + }); + try { return session ? new ShellSession((command, token) => app.Run(Normalize(command), token)).Run(args) : app.Run(args); } + catch (Exception ex) { return TerminalMode.Error(ex); } + } +} diff --git a/src/SidePulse.Cli/HostManagement.cs b/src/SidePulse.Cli/HostManagement.cs index d65c1a9..e40e26a 100644 --- a/src/SidePulse.Cli/HostManagement.cs +++ b/src/SidePulse.Cli/HostManagement.cs @@ -12,12 +12,13 @@ namespace SidePulse.Cli; public sealed record HostSnapshot(bool Running, int? ProcessId, AgentState State, IReadOnlyList Sessions, int ProtocolVersion = 1); public static class HostControl { - public static async Task Request(string command, CancellationToken cancellationToken, TimeSpan? timeout = null) + public static async Task Request(string command, CancellationToken cancellationToken, TimeSpan? timeout = null, bool waitForConnection = true) { using var deadline = CancellationTokenSource.CreateLinkedTokenSource(cancellationToken); deadline.CancelAfter(timeout ?? TimeSpan.FromSeconds(2)); using var pipe = new NamedPipeClientStream(".", LocalPipe.Name, PipeDirection.InOut, PipeOptions.Asynchronous | PipeOptions.CurrentUserOnly); - try { await pipe.ConnectAsync(deadline.Token); } + try { await pipe.ConnectAsync(waitForConnection ? Timeout.Infinite : 0, deadline.Token); } + catch (TimeoutException) when (!waitForConnection) { return new(false, null, AgentState.Unknown, []); } catch (OperationCanceledException) when (!cancellationToken.IsCancellationRequested) { return new(false, null, AgentState.Unknown, []); } await pipe.WriteAsync(Encoding.UTF8.GetBytes(JsonSerializer.Serialize(new { Command = command, ProtocolVersion = 1 }) + "\n"), deadline.Token); await pipe.FlushAsync(deadline.Token); diff --git a/src/SidePulse.Cli/Program.cs b/src/SidePulse.Cli/Program.cs index 41a5622..375020c 100644 --- a/src/SidePulse.Cli/Program.cs +++ b/src/SidePulse.Cli/Program.cs @@ -1,109 +1,9 @@ -using Spectre.Console; -using Spectre.Console.Cli; using SidePulse.Cli; -using SidePulse.Core; -args = TerminalMode.Configure(args); -var session = ShellSession.ShouldStart(args); -if (!session) +// Keep the runtime/startup probe independent of terminal and command registration. +if (args is ["--version"] or ["-v"]) { - try { args = Interactive.Resolve(args) ?? []; } - catch (Exception ex) { return TerminalMode.Error(ex); } - if (args.Length == 0) return 0; + Console.WriteLine(ProjectInfo.Version); + return 0; } -static string[] Normalize(string[] command) -{ - if (command.Length == 1 && command[0] == "update") return ["update", "check"]; - if (command.Length >= 1 && command[0] == "host" && (command.Length == 1 || command[1].StartsWith('-') && command[1] is not "--help" and not "-h")) - return new[] { "host", "run" }.Concat(command.Skip(1)).ToArray(); - return command; -} -args = Normalize(args); -using var logOutput = HostLogs.Redirect(args); -var app = new CommandApp(); -app.Configure(config => -{ - config.ConfigureConsole(AnsiConsole.Console); - config.SetApplicationName(ApplicationIdentity.Command); - config.SetApplicationVersion(ProjectInfo.Version); - config.AddCommand("settings").WithDescription("Show, set or reset persistent non-secret defaults."); - config.AddCommand("install").WithDescription("Install for this user; optionally configure user PATH."); - config.AddCommand("uninstall").WithDescription("Remove the managed installation while retaining settings and phone links."); - config.AddCommand("internal-uninstall").IsHidden(); - config.AddBranch("animations", animations => - { - animations.SetDescription("Create, validate, preview and send Dot / Pro LED patterns."); - animations.AddCommand("list"); - animations.AddCommand("preview"); - animations.AddCommand("validate"); - animations.AddCommand("apply"); - animations.AddCommand("edit"); - animations.AddCommand("import"); - animations.AddCommand("export"); - }); - config.AddBranch("profiles", profiles => - { - profiles.AddCommand("set"); - profiles.AddCommand("show"); - }); - config.AddBranch("about", about => - { - about.AddCommand("info"); - about.AddCommand("website"); - about.AddCommand("github"); - about.AddCommand("upstream"); - about.AddCommand("credits"); - about.AddCommand("licenses"); - }); - config.AddCommand("docs"); - config.AddBranch("update", update => - { - update.SetDescription("Check GitHub releases and install verified self-contained updates."); - update.AddCommand("check"); - update.AddCommand("install"); - update.AddCommand("status"); - }); - config.AddCommand("internal-update").IsHidden(); - config.AddBranch("link", links => - { - links.SetDescription("Pair and manage protected iPhone links."); - links.AddCommand("pair").WithDescription("Pair an iPhone by QR code."); - links.AddCommand("list").WithDescription("List saved phones without exposing tokens."); - links.AddCommand("import").WithDescription("Save an existing token from an environment variable."); - links.AddCommand("default").WithDescription("Choose the default saved phone."); - links.AddCommand("rename").WithDescription("Rename a phone alias."); - links.AddCommand("remove").WithDescription("Remove a local phone link."); - }); - config.AddCommand("doctor").WithDescription("Check local setup without sending to devices or the network."); - config.AddCommand("devices").WithDescription("List mounted SidePulse devices."); - config.AddCommand("state").WithDescription("Display an agent state on USB or iPhone."); - config.AddCommand("write").WithDescription("Send a raw LED program with firmware envelope checks."); - config.AddCommand("dashboard").WithDescription("Show devices and built-in status profiles."); - config.AddBranch("host", host => - { - host.SetDescription("Manage the shared agent host."); - host.AddCommand("run").WithDescription("Run in the foreground."); - host.AddCommand("start").WithDescription("Start a detached host with bounded local logs."); - host.AddCommand("reset").WithDescription("Clear stale sessions without inventing completion."); - host.AddCommand("status").WithDescription("Query the running host and agent sessions."); - host.AddCommand("stop").WithDescription("Request graceful shutdown over current-user IPC."); - host.AddCommand("logs").WithDescription("Show recent background host log lines."); - }); - config.AddBranch("agents", agents => - { - agents.SetDescription("Set up Copilot, Codex, Claude Code, Kiro and OpenCode lifecycle integrations."); - agents.AddCommand("list"); - agents.AddCommand("install"); - agents.AddCommand("status"); - agents.AddCommand("uninstall"); - }); - config.AddCommand("hook").IsHidden(); - config.AddCommand("hook-config").WithDescription("Generate opt-in Copilot CLI hook configuration."); - config.SetExceptionHandler((exception, _) => - { - // Credential-bearing HTTP exception details are never displayed. - return TerminalMode.Error(exception); - }); -}); -try { return session ? new ShellSession((command, token) => app.Run(Normalize(command), token)).Run(args) : app.Run(args); } -catch (Exception ex) { return TerminalMode.Error(ex); } +return CliApplication.Run(args); diff --git a/src/SidePulse.Cli/ShellSession.cs b/src/SidePulse.Cli/ShellSession.cs index 51f1588..6dac247 100644 --- a/src/SidePulse.Cli/ShellSession.cs +++ b/src/SidePulse.Cli/ShellSession.cs @@ -152,8 +152,8 @@ private string HomeContext() string host; try { - var snapshot = HostControl.Request("status", CancellationToken.None, TimeSpan.FromMilliseconds(300)).GetAwaiter().GetResult(); - host = snapshot.Running ? $"running · {snapshot.State} · {snapshot.Sessions.Count} sessions" : "stopped"; + var snapshot = HostControl.Request("status", CancellationToken.None, TimeSpan.FromMilliseconds(300), waitForConnection: false).GetAwaiter().GetResult(); + host = snapshot.Running ? $"running · {snapshot.State} · {snapshot.Sessions.Count} sessions" : "not connected"; } catch (Exception ex) when (ex is IOException or OperationCanceledException or UnauthorizedAccessException) { host = "not responding · see Agents & host"; } return $"Output: {settings.OutputDescription}\nBrightness: {settings.Brightness}% · Profile: {settings.Profile ?? "built-in"} · Shell: {TerminalMode.Shell}\nHost: {host}\nLast action: {recent ?? "none this session"}"; From 1e9a3e663faff0ba0003f10b7ef1c0767b53f128 Mon Sep 17 00:00:00 2001 From: Gordon Breuer Date: Mon, 26 Oct 2026 11:50:31 +0000 Subject: [PATCH 2/2] Keep installation startup probes on full CLI initialization --- docs/performance/2026-10-26-startup.md | 4 +++- src/SidePulse.Cli/Updates.cs | 2 ++ 2 files changed, 5 insertions(+), 1 deletion(-) diff --git a/docs/performance/2026-10-26-startup.md b/docs/performance/2026-10-26-startup.md index e4aaacd..effb5c7 100644 --- a/docs/performance/2026-10-26-startup.md +++ b/docs/performance/2026-10-26-startup.md @@ -56,7 +56,9 @@ No trimming/AOT or framework-dependent requirement is introduced by this change. PTY smoke verifies both missing-host navigation and an actual running dry-run host. - Bare `--version`/`-v` now use a small bootstrap without terminal setup or the full command registry. Version calls with other flags retain normal parsing; - quiet/noninteractive output equivalence is tested. The ~29 ms result is a + quiet/noninteractive output equivalence is tested. Install/update startup probes + deliberately use `--version --no-interactive` to exercise full CLI initialization, + so the lightweight probe does not weaken replacement/rollback checks. The ~29 ms result is a runtime-plus-minimal-managed-work proxy, **not an isolated JIT profiler result**. - In this Linux .NET 10 bundle, both an isolated extraction-directory inventory and host tracing observed no extracted native files for these commands. Empty diff --git a/src/SidePulse.Cli/Updates.cs b/src/SidePulse.Cli/Updates.cs index cc4b7e1..710f78c 100644 --- a/src/SidePulse.Cli/Updates.cs +++ b/src/SidePulse.Cli/Updates.cs @@ -35,6 +35,8 @@ public static async Task Probe(string target, string version, CancellationToken using var deadline = CancellationTokenSource.CreateLinkedTokenSource(cancellationToken); deadline.CancelAfter(TimeSpan.FromSeconds(15)); var start = new ProcessStartInfo(executable) { UseShellExecute = false, RedirectStandardOutput = true, RedirectStandardError = true, RedirectStandardInput = true, CreateNoWindow = true, WorkingDirectory = target }; start.ArgumentList.Add("--version"); + // Exercise terminal/parser/command registration, not only the fast version bootstrap. + start.ArgumentList.Add("--no-interactive"); using var process = Process.Start(start) ?? throw new IOException("Could not verify the new executable."); process.StandardInput.Close(); var output = process.StandardOutput.ReadToEndAsync(deadline.Token); var errors = process.StandardError.ReadToEndAsync(deadline.Token);