Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 4 additions & 6 deletions .github/workflows/dotnet-ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -47,6 +47,7 @@ jobs:
timeout-minutes: 20
env:
SIDEPULSE_NATIVE_VAULT_TESTS: '1'
SIDEPULSE_INSTALL_SYSTEM_TESTS: '1'
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
with:
Expand Down Expand Up @@ -111,18 +112,15 @@ jobs:
foreach ($architecture in @('x64', 'arm64')) {
$rid = "$prefix-$architecture"
$destination = "artifacts/$rid"
dotnet publish src/SidePulse.Cli -c Release -r $rid --self-contained true -o $destination
dotnet publish src/SidePulse.Cli -c Release -r $rid --self-contained true -p:NuGetLockFilePath=obj/packages.publish.lock.json -o $destination
if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
Copy-Item LICENSE,NOTICE.md $destination
Copy-Item -Recurse third-party $destination
New-Item -ItemType Directory -Force "$destination/third-party/dotnet" | Out-Null
Copy-Item "$env:DOTNET_ROOT/LICENSE.txt","$env:DOTNET_ROOT/ThirdPartyNotices.txt" "$destination/third-party/dotnet"
Copy-Item docs/wiki/Getting-Started.md $destination
$version = ([xml](Get-Content src/SidePulse.Cli/SidePulse.Cli.csproj -Raw)).Project.PropertyGroup.Version
python scripts/package_manifest.py $destination $rid $version
if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
if ($rid -eq $native) {
$binary = if ($IsWindows) { 'spn.exe' } else { 'spn' }
python scripts/install_smoke.py "$destination/$binary"
if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
python scripts/cli_smoke.py "$destination/$binary"
if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
python scripts/animation_smoke.py "$destination/$binary"
Expand Down
1 change: 1 addition & 0 deletions Directory.Build.props
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,7 @@
<ImplicitUsings>enable</ImplicitUsings>
<TreatWarningsAsErrors>true</TreatWarningsAsErrors>
<Deterministic>true</Deterministic>
<DebugType>embedded</DebugType>
<RestorePackagesWithLockFile>true</RestorePackagesWithLockFile>
</PropertyGroup>
</Project>
5 changes: 3 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,9 +2,10 @@

An unofficial .NET companion for SidePulse, with a Spectre.Console terminal interface.

**Status: 0.1.0-beta.1 candidate. Feature parity and hardware validation are still in progress.**
**Status: 0.1.0-beta.2 candidate. Feature parity and hardware validation are still in progress.**

The command is **`spn`**. See [beta notes and alpha migration](docs/releases/0.1.0-beta.1.md).
The command is **`spn`**. See [single-file beta notes](docs/releases/0.1.0-beta.2.md)
and [per-user installation/PATH](docs/wiki/Installation.md).

Start with [Getting started](docs/wiki/Getting-Started.md) for build, USB, phone delivery and Copilot CLI instructions.

Expand Down
38 changes: 38 additions & 0 deletions docs/releases/0.1.0-beta.2.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,38 @@
# SidePulse.NET 0.1.0-beta.2

Single-file portable executables with per-user installation and optional user PATH setup.

- Each runtime archive contains one self-contained executable plus its small
format-2 update manifest. Docs, dependency/runtime licenses and notices are embedded.
A copied executable works alone; native runtime libraries can use a per-user cache.
- `spn install --dry-run`, `spn install`, `spn install --status` and the interactive
Settings → Installation screen provide a permanent per-user location without elevation.
- `--add-to-path` changes only user PATH on Windows. Unix uses a managed user-bin
launcher and, when needed, one explicit backed-up Bash/Zsh/sh profile block.
Command-name conflicts are refused. Repeated installation is idempotent.
- New hook and detached-host setup use the stable installed executable. Existing
hook files still require explicit uninstall/reinstall; manual edits are preserved.
- Verified upgrade, startup probe and rollback support the bundle layout.
Uninstall removes owned binaries/PATH entries while keeping credentials, settings,
user-added files and profile backups. Installed-process removal uses a waiting helper.

## Install or upgrade

Download the matching Windows/Linux/macOS x64 or ARM64 archive and verify
`SHA256SUMS`. Extract and run `.\spn.exe install --dry-run` (PowerShell) or
`./spn install --dry-run` (Unix). Apply with `install`, optionally adding
`--add-to-path`; Unix supports `--shell bash`, `zsh` or `sh`.
The absolute installed executable works immediately; reopen terminals after PATH setup.

Beta 1's updater does not understand format 2. For that one transition, stop the
host, download the new executable, and use its installer or a separate permanent
directory. Existing owned/verified installations can be upgraded with backups;
unowned destinations and edited files are refused. Alpha's command rename still
requires the manual integration transition recorded in beta 1's notes.

Use `spn docs --offline` for full installation, PATH ownership and recovery details.
Hardware/firmware and installed-provider acceptance remain separate from native
CI. Other architectures are cross-built, and packages remain unsigned. Full saved
UI preferences and automatic migration of edited integrations remain open.

This candidate remains an unpublished draft until acceptance is reviewed.
12 changes: 6 additions & 6 deletions docs/wiki/Getting-Started.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,15 +4,15 @@

# Getting started with the beta candidate

The executable is `spn` (`spn.exe` on Windows). Extract the complete platform
archive into a permanent user-owned directory. Run `.\spn.exe` in PowerShell or
`./spn` on Unix unless that directory is on PATH. The beta release notes include
the manual alpha migration; no old-name alias is distributed.
The executable is `spn` (`spn.exe` on Windows). Run `.\spn.exe` in PowerShell or
`./spn` on Unix, then optionally `install --dry-run` and `install --add-to-path`.
Single-file builds contain the runtime, docs and licenses; keep the small manifest
for portable self-updates, or let install create it. See [[Installation]].

USB/SD writes, iPhone pairing/protected links, shared agent host, animation studio,
managed integrations and a persistent interactive session are implemented.
Automatic per-user installation/PATH setup, saved UI preferences, remaining
upstream integrations and physical firmware acceptance remain open.
Per-user installation and optional PATH setup are available. Saved UI preferences,
remaining upstream integrations and physical firmware acceptance remain open.

## Build and run

Expand Down
100 changes: 100 additions & 0 deletions docs/wiki/Installation.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,100 @@
# Installation and portable use

`spn` is a self-contained single executable (`spn.exe` on Windows). Copying that
executable alone is enough for portable use, offline documentation and licenses.
The release archive also contains `sidepulse-install.json`, a small updater
manifest. Native .NET libraries can be extracted into the runtime's per-user
bundle cache; single-file does not mean zero files are ever written.

## Install for this user

```sh
./spn install --dry-run
./spn install
./spn install --status --json
```

Use `.\spn.exe` in PowerShell. Installation is also available from **Settings →
Installation** in the interactive session, with a preview and explicit Install action.
Portable use remains available without running install or changing PATH.

Default binary directories:

| Platform | Location |
|---|---|
| Windows | `%LOCALAPPDATA%\Programs\SidePulse.NET\app` |
| Linux | `~/.local/share/SidePulse.NET/app` |
| macOS | the current user's local application-data directory, under `SidePulse.NET/app` |

`--directory <absolute-path>` selects another dedicated directory. The default
requires no administrator privileges. Existing unowned directories, modified
application files and downgrades are refused. Repeat installation is idempotent.
An upgrade of a verified owned directory uses a backup, startup probe and rollback.
Source-directory files outside the package manifest are never copied.

## Optional user PATH

```powershell
.\spn.exe install --add-to-path --dry-run
.\spn.exe install --add-to-path
```

Windows changes **only the user PATH**, preserving existing entries and registry
value type. It does not copy machine PATH into user PATH. Existing command-name
conflicts are reported before installation. Restart terminals to pick up the
changed environment; the installed absolute path works immediately.

On Unix, a managed `~/.local/bin/spn` symlink points at the permanent executable.
If that directory is already on PATH, no shell profile changes are needed.
Otherwise choose the shell explicitly or let `SHELL` identify it:

```sh
./spn install --add-to-path --shell bash --dry-run
./spn install --add-to-path --shell bash
```

Supported profiles are `.bashrc` for Bash, `.zshrc` for Zsh, and `.profile` for sh/dash.
The preview shows the exact file and export block. An original profile gets a
byte-exact private backup before one marked block is appended. Profile permissions,
unrelated entries and subsequent edits outside that block are retained. Unknown
shells require an explicit choice; no profile is guessed or edited silently.
Open a fresh interactive shell afterward. Login-shell configurations that do not
source these profiles can use the absolute executable or their own PATH setup.

## Agents, host and existing settings

Stop the shared host before installing/upgrading. Configurations, phone links,
protected credentials, profiles and IPC identities keep their existing locations.
After installation, new agent integration and detached-host setup use the stable
installed absolute executable path, even when invoked from a portable copy.

Existing managed hooks are not overwritten automatically. Preview their removal
with the old executable, uninstall them using any original `--config` overrides,
then reinstall using the installed `spn`. Preserve modified files for manual review.
Restart agents and review their normal trust prompts. Deleting the original
download directory does not affect newly registered installed hooks.

## Uninstall and recovery

```sh
spn uninstall --dry-run
spn uninstall
```

Remove managed agent integrations first and stop the host. Uninstall checks
ownership/hashes, removes owned application and PATH/launcher entries, and preserves
settings, credentials, user-added files and profile backups. A modified launcher
or PATH block is refused rather than overwritten. No user data deletion option is
implied by uninstalling the executable.

When invoked from the installed application, a copied helper waits for the
calling process to exit. Confirmed self-removal closes the interactive session.
The command reports `scheduled`, not completed; the reported helper workspace
contains `result.json` after completion and remains available for recovery.
Removing from another portable copy completes directly. Locked executables or
permission errors require closing the relevant process/reviewing the reported
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.
8 changes: 5 additions & 3 deletions docs/wiki/Updating.md
Original file line number Diff line number Diff line change
Expand Up @@ -32,9 +32,11 @@ signatures or protection against a compromised publisher account.
Self-update requires a self-contained distribution containing `sidepulse-install.json`.
Source builds, framework-dependent binaries, older previews without that manifest,
modified application files and symlinked installations require manual installation.
The beta uses `spn` package/executable names. Upgrade from alpha manually using
the release migration instructions; the old updater is not compatible with this
rename. Subsequent beta updates retain the verified directory-package format.
Beta 2 adds single-file manifest format 2, with exactly one owned executable.
It also reads legacy format-1 directory packages. Beta 1's updater cannot read the
new format: download the new executable and use `spn install` to adopt/upgrade the
owned installation, or install into a separate directory. Stop the host first.
Alpha still requires the manual rename transition described in beta 1's notes.
The install directory and its parent must be writable; the updater
never elevates privileges. Package-manager installations should use that manager.

Expand Down
131 changes: 131 additions & 0 deletions scripts/install_smoke.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,131 @@
"""Native single-file installation, PATH ownership and detached uninstall acceptance."""
import json
import os
from pathlib import Path
import re
import shutil
import subprocess
import sys
import tempfile
import time


def main(executable):
source = Path(executable).resolve()
if os.name == 'nt' and os.environ.get('SIDEPULSE_INSTALL_SYSTEM_TESTS') != '1':
raise RuntimeError('Windows user-PATH smoke requires an isolated CI user and SIDEPULSE_INSTALL_SYSTEM_TESTS=1')
with tempfile.TemporaryDirectory(prefix='SidePulse install ü ') as directory:
root = Path(directory).resolve()
download = root / 'Downloads'
download.mkdir()
portable = download / source.name
shutil.copy2(source, portable) # Deliberately no loose runtime, docs or manifest.
target = root / 'Programs' / 'SidePulse ü' / 'app'
config = root / 'configuration'
env = dict(os.environ, SIDEPULSE_NET_HOME=str(config), DOTNET_BUNDLE_EXTRACT_BASE_DIR=str(root / 'runtime-cache'))
original_profile = b'# User settings \xc3\xbc\nexport KEEP=value\n'
if os.name != 'nt':
env.update(HOME=str(root), SHELL='/bin/bash')
profile = root / '.bashrc'
profile.write_bytes(original_profile)
else:
import winreg

def user_path():
with winreg.OpenKey(winreg.HKEY_CURRENT_USER, 'Environment') as key:
try:
return winreg.QueryValueEx(key, 'Path')
except FileNotFoundError:
return None

original_path = user_path()

def run(exe, *args, success=True, extra_env=None):
result = subprocess.run([str(exe), *args], text=True, capture_output=True, env=extra_env or env, timeout=45, cwd=root)
assert (result.returncode == 0) == success, (args, result.returncode, result.stdout, result.stderr)
return result

expected_version = run(portable, '--version').stdout.strip()
docs = json.loads(run(portable, 'docs', '--offline', '--json').stdout)
assert any('Beta.md' in name for name in docs)
licenses = run(portable, 'about', 'licenses', '--full', '--json').stdout
assert '.dotnet.LICENSE.txt' in licenses and '.dotnet.ThirdPartyNotices.txt' in licenses
arguments = ['install', '--directory', str(target), '--add-to-path', '--shell', 'bash', '--json']
preview = json.loads(run(portable, *arguments, '--dry-run').stdout)
assert preview['plan']['Executable'] == str(target / source.name)
assert not target.exists() and not config.exists()
if os.name != 'nt':
assert preview['path']['Profile'] == str(root / '.bashrc')
assert profile.read_bytes() == original_profile
collision = root / 'conflicting command'
collision.mkdir()
(collision / source.name).write_text('unrelated application')
conflicting_env = dict(env, PATH=str(collision) + os.pathsep + env['PATH'])
assert 'Another spn' in run(portable, *arguments, '--dry-run', success=False, extra_env=conflicting_env).stderr
assert not target.exists() and not config.exists()
run(portable, *arguments)
run(portable, *arguments) # Idempotent binary/PATH/profile installation.
installed = target / source.name
record = json.loads((config / 'installation.json').read_text())
assert record['Directory'] == str(target)
assert set(path.name for path in target.iterdir()) == {source.name, 'sidepulse-install.json'}
manifest = json.loads((target / 'sidepulse-install.json').read_text())
assert manifest['Format'] == 2 and len(manifest['Files']) == 1
if os.name != 'nt':
registration = next(item for item in record['PathEntries'] if item['Kind'] == 'profile')
assert Path(registration['Backup']).read_bytes() == original_profile
assert profile.read_text().count('# >>> SidePulse.NET PATH >>>') == 1
profile.write_bytes(profile.read_bytes() + b'# Added after installation\n')
shutil.rmtree(download)
unrelated = root / 'unrelated working directory'
unrelated.mkdir()
fresh_env = dict(env)
if os.name == 'nt':
with winreg.OpenKey(winreg.HKEY_LOCAL_MACHINE, r'SYSTEM\CurrentControlSet\Control\Session Manager\Environment') as key:
machine_path = winreg.QueryValueEx(key, 'Path')[0]
fresh_env['PATH'] = os.path.expandvars(machine_path + ';' + user_path()[0])
invocation = [os.environ.get('COMSPEC', r'C:\Windows\System32\cmd.exe'), '/d', '/c', 'spn', '--version']
else:
invocation = ['/bin/bash', '--noprofile', '--rcfile', str(profile), '-i', '-c', 'spn --version']
fresh = subprocess.run(invocation, stdin=subprocess.DEVNULL, capture_output=True, text=True, env=fresh_env, cwd=unrelated, timeout=45)
assert fresh.returncode == 0 and fresh.stdout.strip() == expected_version, (fresh.returncode, fresh.stdout, fresh.stderr)
run(installed, '--version')
assert json.loads(run(installed, 'install', '--status', '--json').stdout)['mode'] == 'installed'
run(installed, 'state', 'working', '--dry-run', '--json')
plugin = root / 'opencode.js'
run(installed, 'agents', 'install', 'opencode', '--config', str(plugin))
match = re.search(r'const executable =\s*(".*?");', plugin.read_text())
assert json.loads(match.group(1)) == str(installed)
run(installed, 'uninstall', success=False) # Hook paths must be removed explicitly.
run(installed, 'agents', 'uninstall', 'opencode', '--config', str(plugin))
# Unowned files, settings and profiles must survive application removal.
(target / 'personal.txt').write_text('keep')
(config / 'personal-settings.json').write_text('{"keep":true}')
run(installed, 'uninstall', '--dry-run', '--json')
scheduled = json.loads(run(installed, 'uninstall', '--json').stdout)
job = Path(scheduled['workspace'])
deadline = time.monotonic() + 20
while time.monotonic() < deadline and not (job / 'result.json').exists():
time.sleep(0.1)
assert (job / 'result.json').exists(), 'Detached uninstall did not complete'
assert not installed.exists() and not (config / 'installation.json').exists()
assert (target / 'personal.txt').read_text() == 'keep'
assert (config / 'personal-settings.json').exists()
if os.name != 'nt':
assert profile.read_bytes() == original_profile + b'# Added after installation\n'
assert not (root / '.local/bin/spn').exists()
assert Path(registration['Backup']).exists()
else:
assert user_path() == original_path, 'User PATH or its registry type was not restored exactly'
# Give the detached Windows helper time to close its executable before cleanup.
for attempt in range(100):
try:
shutil.rmtree(job)
break
except PermissionError:
time.sleep(0.1)
print('Single-file offline resources, install/PATH preview, conflicts, idempotence, stable hooks and owned uninstall passed.')


if __name__ == '__main__':
main(sys.argv[1])
Loading
Loading