320 lines
15 KiB
Markdown
320 lines
15 KiB
Markdown
# Mjolnir CLI v1 Contract
|
|
|
|
`mjolnirctl` — user-accepted command-line contract for Mjolnir v1.
|
|
|
|
## 1. Context and constraints
|
|
|
|
- `mjolnirctl` is an unprivileged client.
|
|
- All communication uses the `org.bongbetic.Mjolnir` name on the D-Bus system bus.
|
|
- No direct hardware or store access.
|
|
- No daemon auto-start; a missing daemon is reported immediately.
|
|
|
|
## 2. Command hierarchy
|
|
|
|
Canonical hierarchy:
|
|
|
|
```
|
|
mode status telemetry battery rule config calibration
|
|
validate diagnostics capabilities gpu never-touch why
|
|
```
|
|
|
|
- `mjolnirctl <command> <subcommand> [args]`
|
|
- Sole alias: `mjolnirctl --why <write-id>` is the required equivalent of `mjolnirctl why <write-id>`.
|
|
- No other aliases, short options, or inferred subcommands.
|
|
|
|
## 3. Command contract
|
|
|
|
### 3.1 `mode`
|
|
|
|
- `mode get` — report the active mode plus thermal-override and external-profile annotations.
|
|
- `mode set <auto|powersaver|normal>` — wait for daemon confirmation and report the resulting mode.
|
|
- Invalid enum values are rejected locally before any daemon call.
|
|
- Bare `mode` (no subcommand) does nothing.
|
|
|
|
### 3.2 `status`
|
|
|
|
Reports: daemon version, active mode, probe completion, thermal override, external profile, module/autoload state, degradation reason.
|
|
|
|
- Capability detail stays in `capabilities`.
|
|
- Current sample stays in `telemetry`.
|
|
|
|
### 3.3 `telemetry`
|
|
|
|
- `telemetry get` — current sample.
|
|
- `telemetry history` — time-series history.
|
|
- Default window: `--since 1h`.
|
|
- Alternative: `--from <RFC3339> --to <RFC3339>`.
|
|
- Output ascending by timestamp.
|
|
- Empty result is success (exit 0).
|
|
- No watch in v1.
|
|
|
|
### 3.4 `battery`
|
|
|
|
- `battery health` — current health record.
|
|
- `battery history` — time-series; same time flags as `telemetry history`.
|
|
- `battery thresholds get` — current charge thresholds.
|
|
- `battery thresholds set --start <percent> --end <percent>`.
|
|
- Both threshold values required; applied atomically.
|
|
- Local validation: `0 <= start < end <= 100`, integers.
|
|
- Daemon validates against hardware.
|
|
- Preset aliases deferred to the charge-preset decision.
|
|
- Dependency note: ADR-003 currently exposes `ChargeStartThreshold` and `ChargeEndThreshold` as independent readwrite properties, so the open D-Bus contract must provide or define an atomic two-value update mechanism before implementation. This CLI document does not choose that wire shape; see section 5 and section 6.
|
|
|
|
### 3.5 `rule`
|
|
|
|
- `rule list`
|
|
- `rule add`
|
|
- `rule update <rule-id>`
|
|
- `rule delete <rule-id>`
|
|
- Canonical rule fields deferred to the per-app rule decision.
|
|
- No arbitrary D-Bus dictionary input.
|
|
- Delete has no confirmation prompt.
|
|
|
|
### 3.6 `config`
|
|
|
|
- `config export <path>`
|
|
- `config import <path>`
|
|
- Export refuses to overwrite an existing file unless `--force`.
|
|
- Import validates the complete document before atomic apply.
|
|
- Unreadable path fails.
|
|
- No prompts.
|
|
- `--dry-run` validates without mutation.
|
|
|
|
### 3.7 `never-touch`
|
|
|
|
- `never-touch list`
|
|
- `never-touch set <process>...` — atomically replaces the full list.
|
|
- `never-touch set --clear` — clears the list.
|
|
- No add/remove variants; avoid them in v1.
|
|
|
|
### 3.8 `calibration`
|
|
|
|
- `calibration start`
|
|
- `calibration status`
|
|
- `start` remains attached through terminal daemon state and relays progress.
|
|
- No cancel, stop, or background mode.
|
|
|
|
### 3.9 `validate`
|
|
|
|
- Sole validation command.
|
|
- Starts interactive validation, relays progress, stays attached through terminal state.
|
|
- No status or cancel subcommands.
|
|
|
|
### 3.10 `diagnostics`
|
|
|
|
- `diagnostics generate`
|
|
- No destination path argument.
|
|
- Daemon creates a redacted bundle and returns its path.
|
|
- Human output prints path and size.
|
|
- JSON output: `{"path": ..., "size_bytes": ...}`.
|
|
- CLI does not copy, rename, or inspect the bundle.
|
|
|
|
### 3.11 `capabilities`
|
|
|
|
- `capabilities get` — normalized stable fields:
|
|
- knob ID
|
|
- support state
|
|
- reason
|
|
- range
|
|
- topology
|
|
|
|
### 3.12 `gpu`
|
|
|
|
- `gpu get` — dGPU power and display topology.
|
|
- Unsupported hardware is data, not an error: exit 0.
|
|
|
|
### 3.13 `why` / `--why`
|
|
|
|
- `why <write-id>` and `--why <write-id>`; write ID is an opaque daemon-issued identifier.
|
|
- Output full attribution:
|
|
- `write_id`
|
|
- `timestamp`
|
|
- `knob_id`
|
|
- `trigger_event_id`
|
|
- `policy_rule`
|
|
- `principal`
|
|
- `prior_value`
|
|
- `new_value`
|
|
- `mode`
|
|
- `external_profile_state`
|
|
- Daemon resolves `policy_rule`; non-policy writes use `"none"`.
|
|
- Unknown write ID: exit 2.
|
|
|
|
## 4. Cross-cutting decisions
|
|
|
|
### 4.1 Global options
|
|
|
|
Only:
|
|
|
|
- `--help`
|
|
- `--version`
|
|
- `--output human|json`
|
|
- `--timeout <duration>`
|
|
|
|
No CSV, watch, shell completion, color/verbose/quiet flags, cancellation, background workflows, daemon start, or retries.
|
|
|
|
### 4.2 Output
|
|
|
|
- Human is the default regardless of TTY.
|
|
- Singleton resources use key/value blocks; lists and history use aligned tables.
|
|
- Explicit units on all values.
|
|
- Lowercase enums.
|
|
- Status annotations included.
|
|
- No required color or Unicode.
|
|
|
|
JSON success is one object:
|
|
|
|
```json
|
|
{"schema_version": 1, "command": "...", "data": {...}}
|
|
```
|
|
|
|
- snake_case keys, lowercase enums, UTC RFC3339 timestamps, explicit units.
|
|
- Long workflows use JSON Lines with the same versioned event shape.
|
|
- JSON errors: one structured object on stderr; stdout carries only successful data; no partial-success output.
|
|
|
|
### 4.3 Exit codes
|
|
|
|
| Code | Meaning |
|
|
| ---- | -------------------------------------------- |
|
|
| 0 | Success (incl. degraded/unsupported, exit 0) |
|
|
| 2 | Usage / validation / not-found |
|
|
| 3 | Daemon / module unavailable |
|
|
| 4 | Authorization denied |
|
|
| 5 | Unsupported capability |
|
|
| 6 | Policy conflict / rate limit |
|
|
| 7 | Internal operation failure |
|
|
| 124 | Timeout |
|
|
| 130 | Ctrl-C detach |
|
|
|
|
Successful degraded/unsupported-capability responses remain exit 0.
|
|
|
|
D-Bus errors from `org.bongbetic.Mjolnir.Error.*` map to exit codes as follows; these are CLI mappings of settled D-Bus errors:
|
|
|
|
| D-Bus error | Exit |
|
|
| ----------------------- | ---- |
|
|
| `UnknownKnob` | 2 |
|
|
| `InvalidConfig` | 2 |
|
|
| `ModuleAbsent` | 3 |
|
|
| `NotAuthorized` | 4 |
|
|
| `CapabilityLocked` | 5 |
|
|
| `UnsupportedOperation` | 5 |
|
|
| `RateLimited` | 6 |
|
|
| `ThermalOverride` | 6 |
|
|
| `CalibrationInProgress` | 6 |
|
|
|
|
### 4.4 Timeouts
|
|
|
|
- D-Bus default deadline 5 seconds, overridable by global `--timeout`.
|
|
- Daemon absence reported immediately; no retries.
|
|
- Long workflows (calibration/validate) default 30 minutes and have a separate timeout override.
|
|
- Ctrl-C on calibration/validate detaches, returns 130, daemon safely continues.
|
|
|
|
### 4.5 Time arguments
|
|
|
|
- `--since <duration>` with `s|m|h` suffix, or
|
|
- `--from <RFC3339> --to <RFC3339>`.
|
|
- No mixing of forms.
|
|
- Output always UTC RFC3339.
|
|
|
|
### 4.6 Numeric and ID rules
|
|
|
|
- Percentages: integer 0..100, no suffix.
|
|
- Reject locale-dependent numbers and implicit conversions.
|
|
- IDs opaque; CLI never interprets them.
|
|
- Human labels units according to D-Bus fields.
|
|
|
|
### 4.7 Authorization
|
|
|
|
- PolKit delegated to the active agent; CLI never prompts or embeds credentials.
|
|
- No agent or denied authorization gives actionable stderr and exit 4.
|
|
- JSON error stable: `authorization_denied` plus action ID. This is the stable CLI code mapped from the D-Bus error `org.bongbetic.Mjolnir.Error.NotAuthorized`.
|
|
|
|
### 4.8 Battery health record
|
|
|
|
`battery health` output must include the complete record fields:
|
|
|
|
- `timestamp`
|
|
- `cycle_count`
|
|
- `design_capacity`
|
|
- `full_charge_capacity`
|
|
- `wear_percent`
|
|
- `charge_temperature`
|
|
- `validity_status`
|
|
- `staleness_status`
|
|
|
|
The exact types/enums and source contract for `charge_temperature`, `validity_status`, and `staleness_status` must be settled by the data-model/D-Bus work; no enum values or wire types are invented here. No derived fade prediction.
|
|
|
|
## 5. Required and Pending D-Bus Dependencies
|
|
|
|
This section records CLI prerequisites for the open D-Bus contract ticket and separates them from the surface already settled in ADR-003 and the XML. `EditNeverTouchList(as)` is already settled in ADR-003 and the current XML and is therefore **not** labelled required or `[REQUIRED]` here.
|
|
|
|
### Required additions — absent from ADR-003/XML
|
|
|
|
These four additions are absent from ADR-003 and the current XML. They are **required** CLI prerequisites for the open D-Bus contract ticket; they are not settled ADR-003 interfaces.
|
|
|
|
| Addition | Type / shape | Purpose |
|
|
| -------------------- | ------------------------------ | ---------------------------------------- |
|
|
| `NeverTouchList` | read-only property `as` | read the current never-touch list |
|
|
| `StartValidationRun` | method | start validation |
|
|
| `ValidationStage` | progress signal | validate progress reporting |
|
|
| `ExplainWrite` | method `(s write_id) -> a{sv}` | `why` full attribution; read/audit-gated |
|
|
|
|
`NeverTouchList`, `StartValidationRun`, `ValidationStage`, and `ExplainWrite` are absent from ADR-003 and the current XML. `ValidationStage`'s signature is pending: ADR-006 shows both a single-stage string form and a failed-with-reason form, so this document does not invent a wire signature.
|
|
|
|
### Pending read surfaces for `status`
|
|
|
|
The accepted `status` command reports module/autoload state and degradation reason. Both are required read surfaces, but their final property names and wire types are pending; descriptive labels only are used here:
|
|
|
|
- current module/autoload state — wire shape pending
|
|
- overall degradation reason — wire shape pending
|
|
|
|
The existing `AutoloadDisabled` signal is transition-only: it fires when autoload is disabled and cannot replace a current-state read. `status` needs read surfaces for the present module/autoload state and degradation reason; no final property names are invented here.
|
|
|
|
### Pending atomic threshold mechanism
|
|
|
|
`battery thresholds set --start <percent> --end <percent>` applies both values atomically. The current `ChargeStartThreshold`/`ChargeEndThreshold` independent readwrite properties are insufficient for atomicity. The open D-Bus contract ticket must settle a two-value atomic update mechanism; its exact wire shape is pending. This is separate from the four absent additions and the two pending read surfaces above: it concerns the existing settled threshold properties rather than a new named surface.
|
|
|
|
## 6. Command-to-D-Bus mapping
|
|
|
|
Where known. `[REQUIRED]` marks one of the four absent additions from section 5 — a required CLI prerequisite for the open D-Bus contract, not a settled ADR-003 interface. `[PENDING]` marks a surface whose wire shape is unresolved: the two `status` read surfaces, the `ValidationStage` signature, and the atomic threshold mechanism. `EditNeverTouchList(as)` is current settled ADR-003/XML surface and carries no tag.
|
|
|
|
| Command | D-Bus surface |
|
|
| -------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
|
|
| `mode get` / `mode set` | mode property / setter; thermal-override, external-profile properties |
|
|
| `status` | daemon version, mode, probe, override, profile properties; module/autoload state read `[PENDING]`; degradation reason read `[PENDING]` |
|
|
| `telemetry get` / `history` | telemetry property; history method |
|
|
| `battery health` / `history` | battery health property; history method |
|
|
| `battery thresholds get` / `set` | `ChargeStartThreshold`/`ChargeEndThreshold` properties; atomic two-value update mechanism `[PENDING]` (see 3.4) |
|
|
| `rule list/add/update/delete` | rule methods (fields deferred to per-app rule decision) |
|
|
| `config export/import` | `ExportConfig(s path)` / `ImportConfig(s path)` with validation and atomic semantics as CLI requirements |
|
|
| `calibration start/status` | calibration start/status; progress signal |
|
|
| `validate` | `StartValidationRun()` `[REQUIRED]`; `ValidationStage` signal `[REQUIRED]` (signature `[PENDING]`) |
|
|
| `diagnostics generate` | diagnostics method returning bundle path |
|
|
| `capabilities get` | capabilities introspection |
|
|
| `gpu get` | dGPU power/topology properties |
|
|
| `never-touch list` | `NeverTouchList` read-only property `as` `[REQUIRED]` |
|
|
| `never-touch set` | `EditNeverTouchList(as)` — current settled ADR-003/XML surface |
|
|
| `why` / `--why` | `ExplainWrite(s write_id) -> a{sv}` `[REQUIRED]`, read/audit-gated |
|
|
|
|
## 7. Scope exclusions and deferred work
|
|
|
|
Excluded in v1:
|
|
|
|
- CSV, watch, shell completion, color/verbose/quiet flags
|
|
- Cancellation, background workflows
|
|
- Daemon start, retries
|
|
|
|
Deferred:
|
|
|
|
- Rule field syntax — waits for _Per-app rule contract — identity, precedence, and restoration_.
|
|
- Charge preset aliases/wiring — waits for _Charge preset mapping — start hysteresis for 60, 80, and 100 percent_.
|
|
|
|
## 8. Rationale
|
|
|
|
- Single-command, explicit-hierarchy CLI keeps v1 small and auditable.
|
|
- Unprivileged D-Bus-only client keeps the surface safe; no direct hardware paths.
|
|
- Degraded/unsupported hardware is data (exit 0) so scripts can distinguish capability from failure.
|
|
- Atomicity (thresholds, never-touch replace, config import) avoids partial states.
|
|
- Human default regardless of TTY keeps output deterministic for users and tools alike.
|
|
- JSON Lines for long workflows keeps progress streamable without breaking the single-object success shape.
|