# Nexus Package System 1.0 — Evidence Summary

Foundation for the Nexus Package (`.nxp`) format — manifest model, local repository, semver comparison, Store read-only integration. **No real install, deployment, or registry changes.**

## Scope delivered

| Area | Status |
|------|--------|
| `.nxp` format design (ZIP + `manifest.json`) | Done |
| `NexusPackageManifest` model | Done |
| `NexusPackageReader` | Done |
| `NexusPackageValidator` | Done |
| `NexusPackageRepository` (`%LocalAppData%/NinjaNexus/packages/`) | Done |
| `NexusInstalledPackage` + `NexusPackageState` | Done |
| `NexusPackageService` orchestration | Done |
| Semver comparison (`NexusPackageVersionComparer`) | Done |
| Update model interfaces + stubs | Done |
| Deployment model interfaces + stubs (design only) | Done |
| Store read manifest/status via `NexusPackageService` | Done |
| Install/Update buttons disabled ("Kommer snart") | Done |
| Sample manifests (browser, files, media, photos) | Done |
| `dotnet build NexusShell.csproj -c Release` | **PASS** (0 errors) |

## Changed / added files

### Models
- `Models/NexusPackageManifest.cs` — extended with `dependencies`, `icon`, `minNexusVersion`, `releaseDate`
- `Models/NexusPackageModels.cs` — `NexusPackageState`, `NexusInstalledPackage`, index/installed records, validation result
- `Models/NexusPackageUpdateModels.cs` — update coordinator + dependency resolver stubs
- `Models/NexusPackageDeploymentModels.cs` — deployment scope/target/request stubs (no execution)
- `Models/NexusStoreModels.cs` — `PackageState`, `Broken`/`Disabled` install states, `InstallActionLabel`

### Services
- `Services/NexusPackageReader.cs` — read manifest from `.nxp` ZIP, folder, or JSON
- `Services/NexusPackageValidator.cs` — required fields + semver validation
- `Services/NexusPackageVersionComparer.cs` — semver compare (major.minor.patch, pre-release)
- `Services/NexusPackageRepository.cs` — local repo layout, seeding, index rebuild
- `Services/NexusPackageService.cs` — catalog, state resolution, update planning stubs
- `Services/NexusStoreService.cs` — wired to `NexusPackageService`; install/update disabled

### Store UI
- `ViewModels/NexusStoreViewModel.cs` — version/status from package service; install shows "kommer snart"
- `Views/NexusStoreView.xaml` — disabled install/update buttons, installed version in details

### Bootstrap
- `App.xaml.cs` — DI wiring for reader, validator, repository, package service
- `NexusShell.csproj` — copy `Assets/Packages/**/manifest.json` to output

### Sample packages
- `Assets/Packages/nexus-browser/manifest.json`
- `Assets/Packages/nexus-files/manifest.json`
- `Assets/Packages/nexus-media/manifest.json`
- `Assets/Packages/nexus-photos/manifest.json`

### Evidence
- `docs/evidence/nexus-package-system-v1/SUMMARY.md` (this file)
- `docs/evidence/nexus-package-system-v1/SCREENSHOT-NOTES.md`

## Manifest model

`manifest.json` inside `.nxp` (camelCase JSON):

| Field | Required | Notes |
|-------|----------|-------|
| `id` | Yes | Package identifier |
| `name` | Yes | Display name |
| `version` | Yes | Semver |
| `publisher` | Yes | Publisher label |
| `description` | No | Store details |
| `entryPoint` | Yes | `nexus:` URI or future `.exe` |
| `dependencies` | No | Package IDs |
| `icon` / `iconKey` | No | Lucide key for Store |
| `category` | Yes | Store grouping |
| `minNexusVersion` | No | Shell compatibility |
| `releaseDate` | No | ISO date string |

Store-only metadata (`changelog`, `sizeLabel`, `isNexusApp`, `popularity`, etc.) retained for catalog UX.

## Repository model

Local path: `%LocalAppData%/NinjaNexus/packages/`

```
packages/
  index.json          # catalog index (id, version, packageFile, cachedAt)
  repository/         # cached .nxp archives (ZIP with manifest.json)
  installed/          # per-package metadata: {id}.json
```

First run seeds:
1. Bundled `Assets/Packages/*/manifest.json` → `repository/{id}-{version}.nxp`
2. Remaining `Assets/store-repository.json` entries → manifest-only `.nxp` if missing
3. Default installed records for `nexus-files` and `nexus-browser` at v1.0.0 (update demo)

Installed record shape (`installed/{id}.json`):

```json
{
  "id": "nexus-browser",
  "installedVersion": "1.0.0",
  "installedAt": "2026-05-29T12:00:00Z",
  "state": "Installed"
}
```

## Package states

| State | Store label | Detection |
|-------|-------------|-----------|
| `Available` | Tilgængelig | Not in `installed/` |
| `Installed` | Installeret | Installed version ≥ catalog version |
| `UpdateAvailable` | Opdatering tilgængelig | Installed version &lt; catalog version |
| `Broken` | Beskadiget | Explicit state in installed metadata |
| `Disabled` | Deaktiveret | Explicit state in installed metadata |

## Version model

`NexusPackageVersionComparer.Compare(left, right)` returns `-1/0/1` using semver rules:
- Numeric `major.minor.patch` (missing segments = 0)
- Pre-release: empty &gt; non-empty; dot-separated identifiers; numeric segments sort before strings
- Optional `+build` metadata (lexical, after pre-release)

Used by `NexusPackageService.ResolveState` for `UpdateAvailable` detection.

## Update model (foundation)

Interfaces in `NexusPackageUpdateModels.cs`:
- `INexusPackageUpdateCoordinator` — mandatory updates, rollback candidates, update plans
- `INexusPackageDependencyResolver` — install order, missing dependencies
- `NexusPackageUpdateCoordinatorStub` / `NexusPackageDependencyResolverStub` — no execution

`NexusPackageService.PlanUpdateAsync` returns a plan with from/to versions and dependency gaps.

## Deployment model (design only)

Interfaces in `NexusPackageDeploymentModels.cs`:
- Scopes: `Local`, `Remote`, `Group`, `Organization`
- `INexusPackageDeploymentCoordinator` — queue/list deployments (stub returns "not available in 1.0")

No deployment execution, agent changes, or Control Center wiring in this phase.

## Store integration

- `NexusStoreService` reads catalog and states from `NexusPackageService`
- Cards show catalog version + `StatusLabel` from package state
- Detail panel: catalog version, installed version, status, publisher, category
- **Install** and **Opdater** buttons disabled with "Kommer snart"
- **Åbn** still works for installed Nexus apps via `nexus:` protocol
- Favorites/history remain in legacy `%LocalAppData%/NinjaNexus/store/installed.json` (`NexusInstalledAppsService`)

## Build

```powershell
dotnet build "source/nexus-shell/NexusShell/NexusShell.csproj" -c Release
```

Result: **Build succeeded** — 0 errors, 7 pre-existing warnings.

## Git status (at evidence time)

Modified/new paths under this mission (uncommitted):

- `source/nexus-shell/NexusShell/Models/NexusPackage*.cs`
- `source/nexus-shell/NexusShell/Models/NexusStoreModels.cs`
- `source/nexus-shell/NexusShell/Services/NexusPackage*.cs`
- `source/nexus-shell/NexusShell/Services/NexusStoreService.cs`
- `source/nexus-shell/NexusShell/ViewModels/NexusStoreViewModel.cs`
- `source/nexus-shell/NexusShell/Views/NexusStoreView.xaml`
- `source/nexus-shell/NexusShell/App.xaml.cs`
- `source/nexus-shell/NexusShell/NexusShell.csproj`
- `source/nexus-shell/NexusShell/Assets/Packages/**`
- `docs/evidence/nexus-package-system-v1/**`

No commit created per mission scope.

## Next phase (not in scope)

1. Real `.nxp` install — extract payload, register entry points, lockdown `allowedApps`
2. Signed packages + remote repository sync
3. Wire `INexusPackageDeploymentCoordinator` to Control Center / Agent
4. Replace `store-repository.json` with remote catalog feed
5. Migrate favorites/history into `packages/` metadata
