146 lines
3.7 KiB
Markdown
146 lines
3.7 KiB
Markdown
|
# Local Protocol
|
||
|
|
|
||
|
|
## Goals
|
||
|
|
|
||
|
|
- Provide a stable local contract between UI, worker, and helper components.
|
||
|
|
- Avoid parsing terminal-oriented text output.
|
||
|
|
- Support progress, execution, history, recovery, settings, and helper handoff.
|
||
|
|
|
||
|
|
## Protocol Version
|
||
|
|
|
||
|
|
- Current implementation version: `0.3.0`
|
||
|
|
|
||
|
|
## UI ↔ Worker Commands
|
||
|
|
|
||
|
|
- `health.snapshot`
|
||
|
|
- `permissions.inspect`
|
||
|
|
- `scan.start`
|
||
|
|
- `plan.preview`
|
||
|
|
- `plan.execute`
|
||
|
|
- `recovery.restore`
|
||
|
|
- `apps.list`
|
||
|
|
- `apps.uninstall.preview`
|
||
|
|
- `apps.uninstall.execute`
|
||
|
|
- `settings.get`
|
||
|
|
- `settings.set`
|
||
|
|
|
||
|
|
## Worker ↔ Helper Models
|
||
|
|
|
||
|
|
### `AtlasHelperAction`
|
||
|
|
|
||
|
|
- `id`
|
||
|
|
- `kind`
|
||
|
|
- `targetPath`
|
||
|
|
- `destinationPath` (required for restore-style actions)
|
||
|
|
|
||
|
|
### `AtlasHelperActionResult`
|
||
|
|
|
||
|
|
- `action`
|
||
|
|
- `success`
|
||
|
|
- `message`
|
||
|
|
- `resolvedPath`
|
||
|
|
|
||
|
|
## Response Payloads
|
||
|
|
|
||
|
|
- `accepted(task)`
|
||
|
|
- `health(snapshot)`
|
||
|
|
- `permissions(permissionStates)`
|
||
|
|
- `apps(appFootprints)`
|
||
|
|
- `preview(actionPlan)`
|
||
|
|
- `settings(settings)`
|
||
|
|
- `rejected(code, reason)`
|
||
|
|
|
||
|
|
### Error Codes in Current Use
|
||
|
|
|
||
|
|
- `unsupportedCommand`
|
||
|
|
- `permissionRequired`
|
||
|
|
- `helperUnavailable`
|
||
|
|
- `executionUnavailable`
|
||
|
|
- `invalidSelection`
|
||
|
|
|
||
|
|
## Event Payloads
|
||
|
|
|
||
|
|
- `taskProgress(taskID, completed, total)`
|
||
|
|
- `taskFinished(taskRun)`
|
||
|
|
- `permissionUpdated(permissionState)`
|
||
|
|
|
||
|
|
## Core Schemas
|
||
|
|
|
||
|
|
### Finding
|
||
|
|
|
||
|
|
- `id`
|
||
|
|
- `category`
|
||
|
|
- `title`
|
||
|
|
- `detail`
|
||
|
|
- `bytes`
|
||
|
|
- `risk`
|
||
|
|
- `targetPaths` (optional structured execution targets derived from the scan adapter)
|
||
|
|
|
||
|
|
### ActionPlan
|
||
|
|
|
||
|
|
- `id`
|
||
|
|
- `title`
|
||
|
|
- `items`
|
||
|
|
- `estimatedBytes`
|
||
|
|
|
||
|
|
### TaskRun
|
||
|
|
|
||
|
|
- `id`
|
||
|
|
- `kind`
|
||
|
|
- `status`
|
||
|
|
- `summary`
|
||
|
|
- `startedAt`
|
||
|
|
- `finishedAt`
|
||
|
|
|
||
|
|
### AppFootprint
|
||
|
|
|
||
|
|
- `id`
|
||
|
|
- `name`
|
||
|
|
- `bundleIdentifier`
|
||
|
|
- `bundlePath`
|
||
|
|
- `bytes`
|
||
|
|
- `leftoverItems`
|
||
|
|
|
||
|
|
### RecoveryItem
|
||
|
|
|
||
|
|
- `id`
|
||
|
|
- `title`
|
||
|
|
- `detail`
|
||
|
|
- `originalPath`
|
||
|
|
- `bytes`
|
||
|
|
- `deletedAt`
|
||
|
|
- `expiresAt`
|
||
|
|
- `payload`
|
||
|
|
- `restoreMappings` (optional original-path ↔ trashed-path records for physical restoration)
|
||
|
|
|
||
|
|
### AtlasSettings
|
||
|
|
|
||
|
|
- `recoveryRetentionDays`
|
||
|
|
- `notificationsEnabled`
|
||
|
|
- `excludedPaths`
|
||
|
|
- `language`
|
||
|
|
- `acknowledgementText`
|
||
|
|
- `thirdPartyNoticesText`
|
||
|
|
|
||
|
|
## Protocol Rules
|
||
|
|
|
||
|
|
- Progress must be monotonic.
|
||
|
|
- Rejected requests return a stable code plus a user-facing reason.
|
||
|
|
- Destructive flows must end in a history record.
|
||
|
|
- Recoverable flows must produce structured recovery items.
|
||
|
|
- Helper actions must remain allowlisted structured actions, never arbitrary command strings.
|
||
|
|
|
||
|
|
## Current Implementation Note
|
||
|
|
|
||
|
|
- `health.snapshot` is backed by `lib/check/health_json.sh` through `MoleHealthAdapter`.
|
||
|
|
- `scan.start` is backed by `bin/clean.sh --dry-run` through `MoleSmartCleanAdapter` when the upstream workflow succeeds. If it cannot complete, the worker now rejects the request instead of silently fabricating scan results.
|
||
|
|
- `apps.list` is backed by `MacAppsInventoryAdapter`, which scans local app bundles and derives leftover counts.
|
||
|
|
- The worker persists a local JSON-backed workspace state containing the latest snapshot, current Smart Clean plan, and settings, including the persisted app-language preference.
|
||
|
|
- Atlas localizes user-facing shell copy through a package-scoped resource bundle and uses the persisted language to keep summaries and settings text aligned.
|
||
|
|
- App uninstall can invoke the packaged or development helper executable through structured JSON actions.
|
||
|
|
- Structured Smart Clean findings can now carry executable target paths, and a safe subset of those targets can be moved to Trash and physically restored later.
|
||
|
|
- The app shell communicates with the worker over structured XPC `Data` payloads that encode Atlas request and result envelopes.
|
||
|
|
|
||
|
|
- `executePlan` is fail-closed for unsupported targets, but now supports a real Trash-based execution path for a safe structured subset of Smart Clean items.
|
||
|
|
- `recovery.restore` can physically restore items when `restoreMappings` are present; otherwise it falls back to model rehydration only.
|