MARKDOWN SOURCE
# Program Design: Once CLI port
Compatibility baseline: Basecamp Once `v0.3.4`, the latest stable release as of 2026-10-08. Keep the CLI and Docker metadata compatible with this tag. The GitHub registry crate named `ino` is unrelated, so self-update uses Cargo installation from `[package].repository` or runs `INO_SELF_UPDATE_SCRIPT` when configured.
## Files
- `Cargo.toml` — add the native Docker/API, async runtime, serialization, archive, HTTP, key-generation, and error dependencies; record the project source used by self-update.
- `Cargo.lock` — lock the added Rust dependency graph.
- `src/main.rs` — register the top-level `once` command while preserving all existing commands and the no-argument automatic release.
- `src/commands/mod.rs` — register the new Once command module.
- `src/commands/once/mod.rs` — run the Once command path and its Tokio runtime without converting existing commands to async.
- `src/commands/once/cli.rs` — define `ino once` subcommands, arguments, flags, and command dispatch inputs.
- `src/commands/once/error.rs` — define user-facing, contextual errors for Docker, metadata, backup, background, and updater failures.
- `src/commands/once/docker.rs` — wrap Bollard/Docker Engine calls and translate Docker responses/errors to port-owned types.
- `src/commands/once/model.rs` — define Once-compatible settings, key, proxy, and operation-state JSON models.
- `src/commands/once/namespace.rs` — discover/restore namespace resources, app metadata, proxy settings, and persisted proxy state.
- `src/commands/once/proxy.rs` — manage the Once-compatible Kamal Proxy container, route changes, and proxy-backed state archive.
- `src/commands/once/backup.rs` — read/write Once gzip-tar backups, safely copy volume data, run hooks, restore data, and trim retained backups.
- `src/commands/once/keys.rs` — generate/validate SECRET_KEY_BASE and VAPID keys using Once-compatible encodings.
- `src/commands/once/operations.rs` — implement high-level list, deploy, backup, restore, lifecycle, teardown, update, and key-change flows over the domain models in `model.rs` and `namespace.rs`.
- `src/commands/once/background.rs` — run scheduled backups/updates and install/uninstall systemd or launchd services with explicit Once-service handoff.
- `src/commands/once/updater.rs` — implement `self-update` using Cargo installation from `[package].repository` or `INO_SELF_UPDATE_SCRIPT`; never target the unrelated crates.io `ino` crate.
- `src/commands/once/settings.rs` — validate deploy settings and apply explicitly supplied changes to existing settings.
- `tests/once_cli.rs` — exercise nested command parsing, help, argument/flag requirements, and no-argument behavior.
- `src/commands/once/model.rs`, `namespace.rs`, `settings.rs`, `keys.rs`, and `backup.rs` — contain unit tests for v0.3.4 JSON, naming, env, keys, backup, and path safety compatibility.
- `tests/once_docker.rs` — feature-gated Docker integration tests against Once-shaped resources and a real app image; run with `cargo test --features docker-tests --test once_docker`.
- `tests/fixtures/once-v0.3.4/application-settings.json` — synthetic v0.3.4 app label/settings payload.
- `tests/fixtures/once-v0.3.4/proxy-settings.json` — synthetic v0.3.4 proxy label payload.
- `tests/fixtures/once-v0.3.4/state.json` — synthetic v0.3.4 proxy-backed operation state.
- `README.md` — document `ino once`, CLI parity, Docker requirements, and the deferred TUI.
- `docs/once-cli.md` — provide the full CLI, compatibility, safety, background-service, and self-update reference.
- `THIRD-PARTY-NOTICES.md` — preserve attribution and MIT license notices for substantially ported Once code.
## Types & signatures
```rust
pub struct OnceCli {
pub namespace: String,
pub command: Option<OnceCommand>,
}
pub enum OnceCommand {
Background { command: BackgroundCommand },
Backup(BackupArgs),
Deploy(DeployArgs),
Exec(ExecArgs),
Keys { command: KeysCommand },
List,
Remove(HostArgs),
Restore(RestoreArgs),
Start(HostArgs),
Stop(HostArgs),
Teardown(TeardownArgs),
Update(UpdateArgs),
SelfUpdate,
Version,
}
pub enum BackgroundCommand {
Install(BackgroundInstallArgs),
Uninstall,
Run(BackgroundRunArgs),
}
pub enum KeysCommand {
Reset(KeysResetArgs),
Set(KeysSetArgs),
}
pub struct BackgroundInstallArgs { pub take_over_once: bool }
pub struct BackgroundRunArgs { pub once: bool, pub no_self_update: bool }
pub struct KeysResetArgs { pub host: String, pub secret_key_base: bool, pub vapid: bool }
pub struct KeysSetArgs { pub host: String, pub secret_key_base: Option<String>, pub vapid: Option<String> }
pub struct UpdateArgs { pub host: String, pub image: Option<String>, pub settings: SettingsFlags }
pub struct DeployArgs {
pub image: String,
pub settings: SettingsFlags,
}
pub struct SettingsFlags {
pub host: Option<String>,
pub disable_tls: Option<bool>,
pub env: Option<Vec<String>>,
pub smtp_server: Option<String>,
pub smtp_port: Option<String>,
pub smtp_username: Option<String>,
pub smtp_password: Option<String>,
pub smtp_from: Option<String>,
pub cpus: Option<u32>,
pub memory: Option<u32>,
pub auto_update: Option<bool>,
pub backup_path: Option<std::path::PathBuf>,
pub auto_backup: Option<bool>,
pub registry_username: Option<String>,
pub registry_password: Option<String>,
pub registry_password_stdin: bool,
}
```
Once-compatible serialized models (use explicit Serde renames where Once's JSON spelling is not Rust's default):
```rust
pub struct AppSettings {
pub name: String,
pub image: String,
pub host: String,
pub disable_tls: bool, // JSON: disableTLS
pub env_vars: std::collections::HashMap<String, String>, // JSON: env
pub smtp: SmtpSettings,
pub resources: ContainerResources,
pub auto_update: bool, // JSON: autoUpdate
pub backup: BackupSettings,
pub keys: Keys,
pub registry: RegistrySettings,
}
pub struct ContainerResources {
pub cpus: u32,
pub memory_mb: u32, // JSON: memoryMB
}
pub struct ProxySettings {
pub http_port: u16,
pub https_port: u16,
pub metrics_port: u16,
}
pub struct OnceState {
pub apps: std::collections::HashMap<String, AppState>,
pub last_self_update: OperationResult,
}
pub struct AppState {
pub last_backup: OperationResult,
pub last_update: OperationResult,
}
pub struct OperationResult {
pub at: String, // RFC3339; zero value is 0001-01-01T00:00:00Z
pub error: String,
}
```
Core interfaces (signatures only):
```rust
pub fn run(cli: OnceCli) -> Result<(), Box<dyn std::error::Error>>;
pub fn exit_code(error: &(dyn std::error::Error + 'static)) -> Option<i32>;
pub struct DockerEngine { /* Bollard Docker client */ }
impl DockerEngine {
pub fn connect() -> Result<Self, OnceError>;
pub async fn list_containers(&self) -> Result<Vec<ContainerRecord>, OnceError>;
pub async fn ensure_network(&self, name: &str) -> Result<(), OnceError>;
pub async fn ensure_volume(&self, name: &str, labels: HashMap<String, String>) -> Result<bool, OnceError>;
pub async fn pull_image_with_credentials(&self, image: &str, registry: Option<&RegistrySettings>) -> Result<(), OnceError>;
pub async fn create_container(&self, name: &str, config: ContainerCreateBody) -> Result<String, OnceError>;
pub async fn start_container(&self, id: &str) -> Result<(), OnceError>;
pub async fn stop_container(&self, id: &str) -> Result<(), OnceError>;
pub async fn exec(&self, id: &str, command: &[String]) -> Result<i32, OnceError>;
pub async fn exec_capture(&self, id: &str, command: &[String]) -> Result<(i32, String), OnceError>;
}
pub struct Application {
pub container_id: String,
pub settings: AppSettings,
pub running: bool,
pub created: i64,
}
pub struct Namespace {
pub name: String,
pub applications: Vec<Application>,
pub proxy_settings: Option<ProxySettings>,
pub engine: std::sync::Arc<DockerEngine>,
}
impl Namespace {
pub async fn restore(engine: std::sync::Arc<DockerEngine>, name: String) -> Result<Self, OnceError>;
pub async fn setup(&mut self) -> Result<(), OnceError>;
pub async fn refresh(&mut self) -> Result<(), OnceError>;
}
mod proxy {
pub async fn boot(namespace: &mut Namespace) -> Result<(), OnceError>;
pub async fn deploy(namespace: &Namespace, app: &Application, target: &str) -> Result<(), OnceError>;
pub async fn load_state(namespace: &Namespace) -> Result<OnceState, OnceError>;
pub async fn save_state(namespace: &Namespace, state: &OnceState) -> Result<(), OnceError>;
}
mod backup {
pub async fn create(namespace: &Namespace, app: &Application, path: &Path) -> Result<PathBuf, OnceError>;
pub fn read_metadata(path: &Path) -> Result<RestoreMetadata, OnceError>;
pub fn data_archive(path: &Path) -> Result<File, OnceError>;
}
pub struct RestoreMetadata { pub app: AppSettings, pub volume_keys: Keys }
pub async fn deploy(namespace: &mut Namespace, image: &str, flags: &SettingsFlags) -> Result<(), OnceError>;
pub async fn update(namespace: &mut Namespace, host: &str, args: &UpdateArgs) -> Result<(), OnceError>;
pub async fn auto_update(namespace: &mut Namespace, app_name: &str) -> Result<bool, OnceError>;
pub async fn backup(namespace: &Namespace, host: &str, path: &Path) -> Result<(), OnceError>;
pub async fn restore(namespace: &mut Namespace, archive: &Path) -> Result<(), OnceError>;
pub fn background(namespace: String, command: BackgroundCommand) -> Result<(), Box<dyn std::error::Error>>;
pub fn updater_run() -> Result<(), OnceError>;
```
## Call stack
### Deploy
`main::run` → `commands::once::run` → create Tokio runtime for Docker commands → `DockerEngine::connect` → `Namespace::restore` → `Namespace::setup` → `operations::deploy` → validate settings and credentials → pull image → find/create compatible volume and keys → create/start container → `proxy::deploy` → HTTP `/up` verification → remove superseded container only after successful health verification → refresh namespace → print result.
### Existing app operation (list/start/stop/exec/remove/update)
`main::run` → Once CLI dispatch → Docker connection → `Namespace::restore` from v0.3.4 resource names and labels → resolve app by host → run the selected operation through `operations` and `DockerEngine` → persist compatible operation state if applicable → print result.
### Backup/restore
Backup: resolve app → check absolute/non-overwriting destination → run `/hooks/pre-backup` when present, otherwise pause a running app → write gzip-tar metadata and `/storage` data → always attempt unpause → record operation result.
Restore: parse and validate gzip-tar metadata → reject hostname collision → pull image → create compatible volume → extract `data/` safely → run `/hooks/post-restore` → deploy and verify → refresh namespace; clean temporary containers/volumes on failure without touching unrelated app data.
### Background and self-update
`ino once background run` → restore namespace → load proxy-backed state → check self-update, due image updates, and due backups → record/save compatible state. `background install` detects an installed Once service and requires `--take-over-once` before disabling it and installing an Ino service. `self-update` calls the isolated updater: Cargo install from `[package].repository`, unless `INO_SELF_UPDATE_SCRIPT` is set.
## Test plan
- `once_without_command_prints_help_without_connecting_to_docker` and `once_help_lists_the_non_ui_command_tree` — help is available without a TUI and includes the implemented non-UI commands.
- `top_level_help_keeps_existing_commands_and_lists_once` and existing release tests — all previous top-level commands remain present and their release logic tests still pass.
- `app_settings_decode_and_encode_once_v034_json_names`, `proxy_settings_decode_once_v034_json_names`, `operation_state_decodes_once_v034_fixture`, and `operation_state_uses_once_due_and_error_rules` — metadata fields, zero timestamps, and operation state remain compatible.
- `discovers_once_apps_deduplicates_old_containers_and_restores_proxy_settings` and `restores_legacy_keys_from_volume_label_only_when_app_label_is_empty` — namespace discovery covers old/stopped containers and legacy key metadata.
- `application_environment_matches_once_deployment_contract`, settings parsing tests, and key tests — env, SMTP, TLS, resource, registry, backup, and key behavior are validated.
- `creates_gzip_tar_with_once_metadata_names_and_storage_prefix`, `reads_once_app_and_volume_settings_from_archive`, `rejects_archive_without_volume_metadata`, and `rejects_storage_archive_path_traversal` — backup/restore archive structure and path safety are asserted.
- `existing_once_app_can_start_stop_and_exec_without_replacement` — Docker-backed lifecycle, exec output/exit status, and default remove-data retention.
- `deploys_once_compatible_image_through_isolated_proxy_and_cleans_up` — real Docker integration covers deploy/settings, backup/restore, update replacement and state, keys, one-shot background backup, and teardown.
- `self_update_uses_configured_script_without_docker_and_propagates_exit_status`, `background_handoff_requires_explicit_flag_when_once_service_exists`, `systemd_unit_runs_ino_once_background_and_restarts_it`, and `service_arguments_are_escaped_for_systemd_and_launchd` — updater and service decisions are validated without mutating host services.
## Least confident decisions
1. **Docker client/runtime:** Bollard with a Tokio runtime isolated to `ino once` keeps existing synchronous commands unchanged; the Docker-backed tests exercise the local Docker Engine.
2. **Self-update source:** Cargo installation uses the current project repository URL, not crates.io; a script override is supported for another distribution method.
3. **Background-service handoff:** an existing Once service is left untouched unless `--take-over-once` is passed; service installation itself is not run as a test because it modifies host service state.
4. **Compatibility baseline:** Docker resource, proxy state, and archive fixtures target Once v0.3.4; future upstream releases require explicit compatibility work.
Program Design: Once CLI port
Compatibility baseline: Basecamp Once v0.3.4, the latest stable release as of 2026-10-08. Keep the CLI and Docker metadata compatible with this tag. The GitHub registry crate named ino is unrelated, so self-update uses Cargo installation from [package].repository or runs INO_SELF_UPDATE_SCRIPT when configured.
Files
Cargo.toml— add the native Docker/API, async runtime, serialization, archive, HTTP, key-generation, and error dependencies; record the project source used by self-update.Cargo.lock— lock the added Rust dependency graph.src/main.rs— register the top-leveloncecommand while preserving all existing commands and the no-argument automatic release.src/commands/mod.rs— register the new Once command module.src/commands/once/mod.rs— run the Once command path and its Tokio runtime without converting existing commands to async.src/commands/once/cli.rs— defineino oncesubcommands, arguments, flags, and command dispatch inputs.src/commands/once/error.rs— define user-facing, contextual errors for Docker, metadata, backup, background, and updater failures.src/commands/once/docker.rs— wrap Bollard/Docker Engine calls and translate Docker responses/errors to port-owned types.src/commands/once/model.rs— define Once-compatible settings, key, proxy, and operation-state JSON models.src/commands/once/namespace.rs— discover/restore namespace resources, app metadata, proxy settings, and persisted proxy state.src/commands/once/proxy.rs— manage the Once-compatible Kamal Proxy container, route changes, and proxy-backed state archive.src/commands/once/backup.rs— read/write Once gzip-tar backups, safely copy volume data, run hooks, restore data, and trim retained backups.src/commands/once/keys.rs— generate/validate SECRET_KEY_BASE and VAPID keys using Once-compatible encodings.src/commands/once/operations.rs— implement high-level list, deploy, backup, restore, lifecycle, teardown, update, and key-change flows over the domain models inmodel.rsandnamespace.rs.src/commands/once/background.rs— run scheduled backups/updates and install/uninstall systemd or launchd services with explicit Once-service handoff.src/commands/once/updater.rs— implementself-updateusing Cargo installation from[package].repositoryorINO_SELF_UPDATE_SCRIPT; never target the unrelated crates.ioinocrate.src/commands/once/settings.rs— validate deploy settings and apply explicitly supplied changes to existing settings.tests/once_cli.rs— exercise nested command parsing, help, argument/flag requirements, and no-argument behavior.src/commands/once/model.rs,namespace.rs,settings.rs,keys.rs, andbackup.rs— contain unit tests for v0.3.4 JSON, naming, env, keys, backup, and path safety compatibility.tests/once_docker.rs— feature-gated Docker integration tests against Once-shaped resources and a real app image; run withcargo test --features docker-tests --test once_docker.tests/fixtures/once-v0.3.4/application-settings.json— synthetic v0.3.4 app label/settings payload.tests/fixtures/once-v0.3.4/proxy-settings.json— synthetic v0.3.4 proxy label payload.tests/fixtures/once-v0.3.4/state.json— synthetic v0.3.4 proxy-backed operation state.README.md— documentino once, CLI parity, Docker requirements, and the deferred TUI.docs/once-cli.md— provide the full CLI, compatibility, safety, background-service, and self-update reference.THIRD-PARTY-NOTICES.md— preserve attribution and MIT license notices for substantially ported Once code.
Types & signatures
pub struct OnceCli {
pub namespace: String,
pub command: Option<OnceCommand>,
}
pub enum OnceCommand {
Background { command: BackgroundCommand },
Backup(BackupArgs),
Deploy(DeployArgs),
Exec(ExecArgs),
Keys { command: KeysCommand },
List,
Remove(HostArgs),
Restore(RestoreArgs),
Start(HostArgs),
Stop(HostArgs),
Teardown(TeardownArgs),
Update(UpdateArgs),
SelfUpdate,
Version,
}
pub enum BackgroundCommand {
Install(BackgroundInstallArgs),
Uninstall,
Run(BackgroundRunArgs),
}
pub enum KeysCommand {
Reset(KeysResetArgs),
Set(KeysSetArgs),
}
pub struct BackgroundInstallArgs { pub take_over_once: bool }
pub struct BackgroundRunArgs { pub once: bool, pub no_self_update: bool }
pub struct KeysResetArgs { pub host: String, pub secret_key_base: bool, pub vapid: bool }
pub struct KeysSetArgs { pub host: String, pub secret_key_base: Option<String>, pub vapid: Option<String> }
pub struct UpdateArgs { pub host: String, pub image: Option<String>, pub settings: SettingsFlags }
pub struct DeployArgs {
pub image: String,
pub settings: SettingsFlags,
}
pub struct SettingsFlags {
pub host: Option<String>,
pub disable_tls: Option<bool>,
pub env: Option<Vec<String>>,
pub smtp_server: Option<String>,
pub smtp_port: Option<String>,
pub smtp_username: Option<String>,
pub smtp_password: Option<String>,
pub smtp_from: Option<String>,
pub cpus: Option<u32>,
pub memory: Option<u32>,
pub auto_update: Option<bool>,
pub backup_path: Option<std::path::PathBuf>,
pub auto_backup: Option<bool>,
pub registry_username: Option<String>,
pub registry_password: Option<String>,
pub registry_password_stdin: bool,
}
Once-compatible serialized models (use explicit Serde renames where Once's JSON spelling is not Rust's default):
pub struct AppSettings {
pub name: String,
pub image: String,
pub host: String,
pub disable_tls: bool, // JSON: disableTLS
pub env_vars: std::collections::HashMap<String, String>, // JSON: env
pub smtp: SmtpSettings,
pub resources: ContainerResources,
pub auto_update: bool, // JSON: autoUpdate
pub backup: BackupSettings,
pub keys: Keys,
pub registry: RegistrySettings,
}
pub struct ContainerResources {
pub cpus: u32,
pub memory_mb: u32, // JSON: memoryMB
}
pub struct ProxySettings {
pub http_port: u16,
pub https_port: u16,
pub metrics_port: u16,
}
pub struct OnceState {
pub apps: std::collections::HashMap<String, AppState>,
pub last_self_update: OperationResult,
}
pub struct AppState {
pub last_backup: OperationResult,
pub last_update: OperationResult,
}
pub struct OperationResult {
pub at: String, // RFC3339; zero value is 0001-01-01T00:00:00Z
pub error: String,
}
Core interfaces (signatures only):
pub fn run(cli: OnceCli) -> Result<(), Box<dyn std::error::Error>>;
pub fn exit_code(error: &(dyn std::error::Error + 'static)) -> Option<i32>;
pub struct DockerEngine { /* Bollard Docker client */ }
impl DockerEngine {
pub fn connect() -> Result<Self, OnceError>;
pub async fn list_containers(&self) -> Result<Vec<ContainerRecord>, OnceError>;
pub async fn ensure_network(&self, name: &str) -> Result<(), OnceError>;
pub async fn ensure_volume(&self, name: &str, labels: HashMap<String, String>) -> Result<bool, OnceError>;
pub async fn pull_image_with_credentials(&self, image: &str, registry: Option<&RegistrySettings>) -> Result<(), OnceError>;
pub async fn create_container(&self, name: &str, config: ContainerCreateBody) -> Result<String, OnceError>;
pub async fn start_container(&self, id: &str) -> Result<(), OnceError>;
pub async fn stop_container(&self, id: &str) -> Result<(), OnceError>;
pub async fn exec(&self, id: &str, command: &[String]) -> Result<i32, OnceError>;
pub async fn exec_capture(&self, id: &str, command: &[String]) -> Result<(i32, String), OnceError>;
}
pub struct Application {
pub container_id: String,
pub settings: AppSettings,
pub running: bool,
pub created: i64,
}
pub struct Namespace {
pub name: String,
pub applications: Vec<Application>,
pub proxy_settings: Option<ProxySettings>,
pub engine: std::sync::Arc<DockerEngine>,
}
impl Namespace {
pub async fn restore(engine: std::sync::Arc<DockerEngine>, name: String) -> Result<Self, OnceError>;
pub async fn setup(&mut self) -> Result<(), OnceError>;
pub async fn refresh(&mut self) -> Result<(), OnceError>;
}
mod proxy {
pub async fn boot(namespace: &mut Namespace) -> Result<(), OnceError>;
pub async fn deploy(namespace: &Namespace, app: &Application, target: &str) -> Result<(), OnceError>;
pub async fn load_state(namespace: &Namespace) -> Result<OnceState, OnceError>;
pub async fn save_state(namespace: &Namespace, state: &OnceState) -> Result<(), OnceError>;
}
mod backup {
pub async fn create(namespace: &Namespace, app: &Application, path: &Path) -> Result<PathBuf, OnceError>;
pub fn read_metadata(path: &Path) -> Result<RestoreMetadata, OnceError>;
pub fn data_archive(path: &Path) -> Result<File, OnceError>;
}
pub struct RestoreMetadata { pub app: AppSettings, pub volume_keys: Keys }
pub async fn deploy(namespace: &mut Namespace, image: &str, flags: &SettingsFlags) -> Result<(), OnceError>;
pub async fn update(namespace: &mut Namespace, host: &str, args: &UpdateArgs) -> Result<(), OnceError>;
pub async fn auto_update(namespace: &mut Namespace, app_name: &str) -> Result<bool, OnceError>;
pub async fn backup(namespace: &Namespace, host: &str, path: &Path) -> Result<(), OnceError>;
pub async fn restore(namespace: &mut Namespace, archive: &Path) -> Result<(), OnceError>;
pub fn background(namespace: String, command: BackgroundCommand) -> Result<(), Box<dyn std::error::Error>>;
pub fn updater_run() -> Result<(), OnceError>;
Call stack
Deploy
main::run → commands::once::run → create Tokio runtime for Docker commands → DockerEngine::connect → Namespace::restore → Namespace::setup → operations::deploy → validate settings and credentials → pull image → find/create compatible volume and keys → create/start container → proxy::deploy → HTTP /up verification → remove superseded container only after successful health verification → refresh namespace → print result.
Existing app operation (list/start/stop/exec/remove/update)
main::run → Once CLI dispatch → Docker connection → Namespace::restore from v0.3.4 resource names and labels → resolve app by host → run the selected operation through operations and DockerEngine → persist compatible operation state if applicable → print result.
Backup/restore
Backup: resolve app → check absolute/non-overwriting destination → run /hooks/pre-backup when present, otherwise pause a running app → write gzip-tar metadata and /storage data → always attempt unpause → record operation result.
Restore: parse and validate gzip-tar metadata → reject hostname collision → pull image → create compatible volume → extract data/ safely → run /hooks/post-restore → deploy and verify → refresh namespace; clean temporary containers/volumes on failure without touching unrelated app data.
Background and self-update
ino once background run → restore namespace → load proxy-backed state → check self-update, due image updates, and due backups → record/save compatible state. background install detects an installed Once service and requires --take-over-once before disabling it and installing an Ino service. self-update calls the isolated updater: Cargo install from [package].repository, unless INO_SELF_UPDATE_SCRIPT is set.
Test plan
once_without_command_prints_help_without_connecting_to_dockerandonce_help_lists_the_non_ui_command_tree— help is available without a TUI and includes the implemented non-UI commands.top_level_help_keeps_existing_commands_and_lists_onceand existing release tests — all previous top-level commands remain present and their release logic tests still pass.app_settings_decode_and_encode_once_v034_json_names,proxy_settings_decode_once_v034_json_names,operation_state_decodes_once_v034_fixture, andoperation_state_uses_once_due_and_error_rules— metadata fields, zero timestamps, and operation state remain compatible.discovers_once_apps_deduplicates_old_containers_and_restores_proxy_settingsandrestores_legacy_keys_from_volume_label_only_when_app_label_is_empty— namespace discovery covers old/stopped containers and legacy key metadata.application_environment_matches_once_deployment_contract, settings parsing tests, and key tests — env, SMTP, TLS, resource, registry, backup, and key behavior are validated.creates_gzip_tar_with_once_metadata_names_and_storage_prefix,reads_once_app_and_volume_settings_from_archive,rejects_archive_without_volume_metadata, andrejects_storage_archive_path_traversal— backup/restore archive structure and path safety are asserted.existing_once_app_can_start_stop_and_exec_without_replacement— Docker-backed lifecycle, exec output/exit status, and default remove-data retention.deploys_once_compatible_image_through_isolated_proxy_and_cleans_up— real Docker integration covers deploy/settings, backup/restore, update replacement and state, keys, one-shot background backup, and teardown.self_update_uses_configured_script_without_docker_and_propagates_exit_status,background_handoff_requires_explicit_flag_when_once_service_exists,systemd_unit_runs_ino_once_background_and_restarts_it, andservice_arguments_are_escaped_for_systemd_and_launchd— updater and service decisions are validated without mutating host services.
Least confident decisions
- Docker client/runtime: Bollard with a Tokio runtime isolated to
ino oncekeeps existing synchronous commands unchanged; the Docker-backed tests exercise the local Docker Engine. - Self-update source: Cargo installation uses the current project repository URL, not crates.io; a script override is supported for another distribution method.
- Background-service handoff: an existing Once service is left untouched unless
--take-over-onceis passed; service installation itself is not run as a test because it modifies host service state. - Compatibility baseline: Docker resource, proxy state, and archive fixtures target Once v0.3.4; future upstream releases require explicit compatibility work.