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
52 changes: 52 additions & 0 deletions .github/workflows/json-compatibility.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,52 @@
name: JSON compatibility
on:
pull_request:
paths:
- 'src/**'
- 'scripts/json_compatibility.py'
- '.github/workflows/json-compatibility.yml'
workflow_dispatch:
inputs:
baseline_ref:
description: Baseline commit or tag to publish with the same SDK
required: true
default: 763ab97ae34175f3ef69331f42bb3740581b0d4f
permissions:
contents: read
concurrency:
group: json-compatibility-${{ github.ref }}
cancel-in-progress: true
jobs:
compare:
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: Compare public JSON contracts with the baseline
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 }
}
python candidate/scripts/json_compatibility.py "baseline/published/$binary" "candidate/published/$binary"
if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
62 changes: 62 additions & 0 deletions docs/decisions/0004-generated-json-contracts.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,62 @@
# Generated JSON contracts

Date: 2026-10-26. Delivery: #60; CLI dependency follow-up: #61.

## Decision

Use explicit records and System.Text.Json generated metadata for application files,
transport envelopes, IPC and CLI JSON. The executable disables reflection-based
JSON serialization by default. Unknown contracts fail explicitly; they do not fall
back to runtime reflection. Core services remain independent of terminal output
and receive their existing caller-owned HTTP clients/credential protectors.

`CoreJsonContext` registers persisted core records and the phone bridge envelope.
`CliJsonContext` registers public output and helper-plan records. The separate
`IpcJsonContext` keeps the host's numeric wire enums. Runtime option converters use
the generic enum converter, not the dynamic converter factory.

## Compatibility

- Keep existing property names/order, casing, null fields, enum representations
and constructor defaults. Lowercase CLI reply properties are deliberate wire
names; existing public model properties retain their PascalCase names.
- Preferences, profiles, encrypted link plaintext and ownership records retain
their current schema. Link/ownership record implementation types are internal;
encryption/protection and credential identities are unchanged.
- Package/install/update records retain case-insensitive reads, indentation and
format-1/format-2 handling. Startup/helper/rollback checks remain active.
- Host messages retain numeric enums and ProtocolVersion 1. CLI output retains
named enums. Old unversioned event defaults and numeric host responses still read.
- The bridge retains `aps.content-available`, `leds` and `data.sidepulse_event_id`;
no alert field or push token is added to JSON output. Token-bearing PhoneLink
objects are not registered as public CLI output contracts.
- Serializer contexts receive copies of caller options: a context encapsulates
its options, so sharing an options instance between Core and CLI contexts would
break uninstall/helper serialization. Copies also preserve caller mutability
without retaining a stale cached snapshot.

## Evidence and remaining work

JsonContractTests compares generated output bytes with the prior anonymous/file
shapes and fixed legacy fixtures; it covers defaults, enum differences, protected
link payload shape, caller-owned options and unknown/secret output rejection.
The normal CLI and lifecycle smoke run with reflection JSON disabled.

```bash
python3 scripts/json_compatibility.py /path/to/baseline/spn /path/to/candidate/spn
```

This compares 22 public JSON/error responses. Only executable-directory
and derived receipt-key differences are normalized. Preview commands must leave
configuration unchanged; other probes must add no filesystem effects beyond the
baseline. The existing native-vault phone list can create an empty store lock. Run against a stopped host; a live externally changing session
is not deterministic compatibility evidence. JSON compatibility CI publishes both
revisions with the same SDK on native Windows/Linux/macOS and runs this comparison.

Application JSON IL2026 diagnostics are removed, including the generic
`JsonArray.Add<JsonObject>` overload (use the concrete JsonNode overload instead).
Local strict partial-trim/ReadyToRun now reaches the third-party
Spectre.Console.Cli IL2104 warning; AOT reports that dependency's IL3050 rather than
our JSON APIs. #61 owns the remaining CLI metadata/dynamic-code compatibility.
Publishing experiments no longer re-enable reflection JSON for smaller variants.
Default release trimming/AOT flags stay unchanged until their full acceptance.
6 changes: 3 additions & 3 deletions scripts/deployment_experiments.py
Original file line number Diff line number Diff line change
Expand Up @@ -18,9 +18,9 @@
MODES = {
'full': [],
'raw-trim': ['PublishTrimmed=true'],
'partial-strict': ['PublishTrimmed=true', 'TrimMode=partial', 'JsonSerializerIsReflectionEnabledByDefault=true'],
'partial': ['PublishTrimmed=true', 'TrimMode=partial', 'JsonSerializerIsReflectionEnabledByDefault=true'],
'partial-r2r': ['PublishTrimmed=true', 'TrimMode=partial', 'JsonSerializerIsReflectionEnabledByDefault=true', 'PublishReadyToRun=true'],
'partial-strict': ['PublishTrimmed=true', 'TrimMode=partial'],
'partial': ['PublishTrimmed=true', 'TrimMode=partial'],
'partial-r2r': ['PublishTrimmed=true', 'TrimMode=partial', 'PublishReadyToRun=true'],
'aot': ['PublishAot=true', 'PublishSingleFile=false', 'DebugType=None', 'StripSymbols=true'],
}

Expand Down
88 changes: 88 additions & 0 deletions scripts/json_compatibility.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,88 @@
"""Compare public JSON responses and their filesystem effects with a published baseline executable."""
import argparse
import hashlib
import json
import os
from pathlib import Path
import subprocess
import tempfile

COMMANDS = [
['state', 'working', '--dry-run', '--json'],
['state', 'waiting', '--brightness', '42', '--dry-run', '--json'],
['settings', 'show', '--json'], ['install', '--status', '--json'],
['uninstall', '--dry-run', '--json'], ['update', 'status', '--json'],
['host', 'status', '--json'], ['devices', '--json'], ['dashboard', '--json'],
['doctor', '--json'], ['link', 'list', '--json'], ['agents', 'list', '--json'],
['animations', 'list', '--json'],
['animations', 'validate', 'solid-green', '--model', 'dot', '--json'],
['animations', 'preview', 'solid-green', '--model', 'dot', '--at', '100', '--json'],
['animations', 'export', 'solid-green', '--model', 'dot', '--json'],
['docs', '--offline', '--json'], ['about', 'info', '--json'],
['about', 'github', '--json'], ['about', 'credits', '--json'],
['about', 'licenses', '--full', '--json'],
['state', 'not-a-state', '--json'],
]


def normalize(value, executable):
if isinstance(value, dict):
return {key: normalize(item, executable) for key, item in value.items()}
if isinstance(value, list):
return [normalize(item, executable) for item in value]
if isinstance(value, str):
target = str(executable.parent).rstrip('/\\')
if os.name == 'nt':
target = target.upper()
key = hashlib.sha256(target.encode('utf-8')).hexdigest().upper()[:24]
return value.replace(str(executable.parent), '<published-directory>').replace(key, '<installation-key>')
return value


def snapshot(root):
if not root.exists():
return {}
entries = {'.': ('directory', root.stat().st_mode & 0o777)}
for path in sorted(root.rglob('*')):
name = str(path.relative_to(root))
entries[name] = ('directory', path.stat().st_mode & 0o777) if path.is_dir() else ('file', hashlib.sha256(path.read_bytes()).hexdigest(), path.stat().st_mode & 0o777)
return entries


def main():
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument('baseline', type=Path)
parser.add_argument('candidate', type=Path)
args = parser.parse_args()
baseline, candidate = args.baseline.resolve(), args.candidate.resolve()
with tempfile.TemporaryDirectory(prefix='spn JSON compatibility ') as temporary:
config = Path(temporary) / 'config'
environment = dict(os.environ, SIDEPULSE_NET_HOME=str(config))
for command in COMMANDS:
results = []
before = snapshot(config)
baseline_files = None
for executable in (baseline, candidate):
response = subprocess.run([str(executable), *command], env=environment,
capture_output=True, text=True, timeout=15)
channel = response.stdout if response.returncode == 0 else response.stderr
try:
value = normalize(json.loads(channel), executable)
except ValueError as error:
raise AssertionError(f'Invalid JSON for {command}, exit {response.returncode}') from error
results.append((response.returncode, value))
files = snapshot(config)
if executable == baseline:
baseline_files = files
else:
assert files == baseline_files, f'Candidate changed configuration beyond baseline: {command}'
if '--dry-run' in command:
assert files == before, f'Preview created or changed configuration: {command}'
assert results[0] == results[1], (command, results)
# Existing link-list behavior can create an empty store lock on native-vault
# platforms. Compare those effects rather than asserting a false baseline.
print(f'{len(COMMANDS)} public JSON command/error responses match baseline.')


if __name__ == '__main__':
main()
10 changes: 5 additions & 5 deletions src/SidePulse.Cli/About.cs
Original file line number Diff line number Diff line change
Expand Up @@ -29,7 +29,7 @@ public static IReadOnlyList<DependencyCredit> Dependencies
get
{
using var stream = Assembly.GetManifestResourceStream("SidePulse.Cli.Dependencies.json") ?? throw new IOException("Dependency credits are missing.");
return JsonSerializer.Deserialize<DependencyCredit[]>(stream, new JsonSerializerOptions { PropertyNameCaseInsensitive = true })!;
return JsonSerializer.Deserialize(stream, CliJson.Info<DependencyCredit[]>(new JsonSerializerOptions { PropertyNameCaseInsensitive = true }))!;
}
}
public static IReadOnlyList<string> LicenseResources => Assembly.GetManifestResourceNames().Where(n => n.Contains(".Licenses.", StringComparison.Ordinal)).Order(StringComparer.Ordinal).ToArray();
Expand All @@ -46,15 +46,15 @@ public static int Link(string url, AboutSettings settings)
try { Process.Start(new ProcessStartInfo(url) { UseShellExecute = true }); }
catch (Exception ex) when (ex is System.ComponentModel.Win32Exception or InvalidOperationException) { throw new IOException("Could not open the browser. Open this URL manually: " + url); }
}
if (settings.Json) Output.Print(new { url, opened = settings.Open }); else Console.WriteLine(url);
if (settings.Json) Output.Print(new LinkReply(url, settings.Open)); else Console.WriteLine(url);
return 0;
}
}
public sealed class AboutCommand : Command<AboutSettings>
{
public override int Execute(CommandContext context, AboutSettings settings, CancellationToken cancellationToken)
{
if (settings.Json) Output.Print(new { name = "SidePulse.NET", version = ProjectInfo.Version, license = "MIT", unofficial = true, website = ProjectInfo.Website, github = ProjectInfo.Github, upstream = ProjectInfo.Upstream });
if (settings.Json) Output.Print(new AboutReply("SidePulse.NET", ProjectInfo.Version, "MIT", true, ProjectInfo.Website, ProjectInfo.Github, ProjectInfo.Upstream));
else Console.WriteLine($"SidePulse.NET {ProjectInfo.Version}\nUnofficial .NET companion · MIT\nOriginal SidePulse by Peter Kuhar / InteliWEAR\n{ProjectInfo.Github}");
return 0;
}
Expand Down Expand Up @@ -85,7 +85,7 @@ public sealed class CreditsCommand : Command<AboutSettings>
{
public override int Execute(CommandContext context, AboutSettings settings, CancellationToken cancellationToken)
{
if (settings.Json) Output.Print(new { project = "Gordon Breuer / Anheledir", upstream = "Peter Kuhar / InteliWEAR", dependencies = ProjectInfo.Dependencies });
if (settings.Json) Output.Print(new CreditsReply("Gordon Breuer / Anheledir", "Peter Kuhar / InteliWEAR", ProjectInfo.Dependencies));
else
{
Console.WriteLine("SidePulse.NET: Gordon Breuer / Anheledir\nSidePulse hardware, protocol and original animations: Peter Kuhar / InteliWEAR\n" + ProjectInfo.Upstream);
Expand All @@ -102,7 +102,7 @@ public override int Execute(CommandContext context, AboutSettings settings, Canc
var resources = ProjectInfo.LicenseResources;
var runtimeDirectory = Path.Combine(AppContext.BaseDirectory, "third-party", "dotnet");
var runtime = Directory.Exists(runtimeDirectory) ? Directory.GetFiles(runtimeDirectory).Order(StringComparer.Ordinal).ToArray() : [];
if (settings.Json) Output.Print(new { project = "MIT", dependencies = ProjectInfo.Dependencies, notices = resources.Select(r => new { name = r, text = settings.Full ? ProjectInfo.LicenseText(r) : null }), runtimeNotices = runtime.Select(r => new { name = Path.GetFileName(r), text = settings.Full ? File.ReadAllText(r) : null }) });
if (settings.Json) Output.Print(new LicensesReply("MIT", ProjectInfo.Dependencies, resources.Select(r => new LicenseNotice(r, settings.Full ? ProjectInfo.LicenseText(r) : null)).ToArray(), runtime.Select(r => new LicenseNotice(Path.GetFileName(r), settings.Full ? File.ReadAllText(r) : null)).ToArray()));
else
{
Console.WriteLine("SidePulse.NET · MIT");
Expand Down
2 changes: 1 addition & 1 deletion src/SidePulse.Cli/Agents.cs
Original file line number Diff line number Diff line change
Expand Up @@ -59,7 +59,7 @@ public override int Execute(CommandContext context, AgentSettings settings, Canc
{
var generated = HookConfiguration.Generate(settings.Agent, HookConfiguration.Executable(settings.Executable), OperatingSystem.IsWindows());
var status = settings.Installation.Install(settings.Target, settings.Agent, generated, settings.DryRun);
if (settings.Json) Output.Print(new { status, managedHooks = settings.DryRun ? generated : null });
if (settings.Json) Output.Print(new AgentInstallReply(status, settings.DryRun ? generated : null));
else
{
AnsiConsole.WriteLine($"{status.State}: {status.Target}");
Expand Down
10 changes: 5 additions & 5 deletions src/SidePulse.Cli/Animations.cs
Original file line number Diff line number Diff line change
Expand Up @@ -45,7 +45,7 @@ public override int Execute(CommandContext context, PatternSettings settings, Ca
var program = settings.File is null && settings.Name is { } name && System.IO.File.Exists(name)
? AnimationLibrary.WithBrightness(new(System.IO.File.ReadAllText(name)), settings.Brightness) : settings.Read();
var animation = Animation.Parse(program, settings.Model);
if (settings.Json) Output.Print(new { valid = true, model = settings.Model, bytes = program.ByteCount, lines = program.LineCount, instructions = animation.Instructions.Count });
if (settings.Json) Output.Print(new ValidationReply(true, settings.Model, program.ByteCount, program.LineCount, animation.Instructions.Count));
else Console.WriteLine($"Valid ({program.ByteCount} bytes, {program.LineCount} lines, {settings.Model}).");
return 0;
}
Expand Down Expand Up @@ -122,7 +122,7 @@ public override async Task<int> ExecuteAsync(CommandContext context, PreviewSett
if (settings.Json)
{
var models = settings.Both ? Enum.GetValues<DeviceModel>() : [settings.Model];
Output.Print(models.Select(m => { var selected = settings.File is null ? AnimationLibrary.WithBrightness(AnimationLibrary.Default.Get(settings.Name!, m), settings.Brightness) : program; var player = new AnimationPlayer(Animation.Parse(selected, m)); player.Advance(settings.At); return new { model = m, at = settings.At, colors = player.Frame.Select(c => c.ToString()).ToArray() }; }).ToArray());
Output.Print(models.Select(m => { var selected = settings.File is null ? AnimationLibrary.WithBrightness(AnimationLibrary.Default.Get(settings.Name!, m), settings.Brightness) : program; var player = new AnimationPlayer(Animation.Parse(selected, m)); player.Advance(settings.At); return new FrameReply(m, settings.At, player.Frame.Select(c => c.ToString()).ToArray()); }).ToArray());
}
else
{
Expand Down Expand Up @@ -177,7 +177,7 @@ public sealed class PatternImportCommand : Command<PatternImportSettings>
public override int Execute(CommandContext context, PatternImportSettings settings, CancellationToken cancellationToken)
{
var path = AnimationLibrary.Default.Save(settings.Name, settings.Model, new(System.IO.File.ReadAllText(settings.File)), settings.Force);
if (settings.Json) Output.Print(new { saved = path }); else Console.WriteLine(path);
if (settings.Json) Output.Print(new SavedReply(path)); else Console.WriteLine(path);
return 0;
}
}
Expand All @@ -192,7 +192,7 @@ public override int Execute(CommandContext context, PatternExportSettings settin
{
var program = settings.Read(); Animation.Parse(program, settings.Model);
if (settings.Destination is { } path) AnimationLibrary.WriteFile(path, program.Text + "\n", settings.Force);
if (settings.Json) Output.Print(new { program = program.Text, output = settings.Destination });
if (settings.Json) Output.Print(new ExportReply(program.Text, settings.Destination));
else if (settings.Destination is null) Console.WriteLine(program.Text);
else Console.WriteLine(Path.GetFullPath(settings.Destination));
return 0;
Expand All @@ -219,7 +219,7 @@ public override int Execute(CommandContext context, ProfileSettings settings, Ca
profile.States[settings.State.Value] = settings.Pattern;
profile = profile with { Brightness = settings.Brightness ?? profile.Brightness };
var path = AnimationLibrary.Default.SaveProfile(settings.Name, profile, true);
if (settings.Json) Output.Print(new { path, profile }); else Console.WriteLine(path);
if (settings.Json) Output.Print(new ProfileReply(path, profile)); else Console.WriteLine(path);
return 0;
}
}
Expand Down
Loading
Loading