# 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, } 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, pub vapid: Option } pub struct UpdateArgs { pub host: String, pub image: Option, pub settings: SettingsFlags } pub struct DeployArgs { pub image: String, pub settings: SettingsFlags, } pub struct SettingsFlags { pub host: Option, pub disable_tls: Option, pub env: Option>, pub smtp_server: Option, pub smtp_port: Option, pub smtp_username: Option, pub smtp_password: Option, pub smtp_from: Option, pub cpus: Option, pub memory: Option, pub auto_update: Option, pub backup_path: Option, pub auto_backup: Option, pub registry_username: Option, pub registry_password: Option, 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, // 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, 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>; pub fn exit_code(error: &(dyn std::error::Error + 'static)) -> Option; pub struct DockerEngine { /* Bollard Docker client */ } impl DockerEngine { pub fn connect() -> Result; pub async fn list_containers(&self) -> Result, OnceError>; pub async fn ensure_network(&self, name: &str) -> Result<(), OnceError>; pub async fn ensure_volume(&self, name: &str, labels: HashMap) -> Result; 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; 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; 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, pub proxy_settings: Option, pub engine: std::sync::Arc, } impl Namespace { pub async fn restore(engine: std::sync::Arc, name: String) -> Result; 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; pub async fn save_state(namespace: &Namespace, state: &OnceState) -> Result<(), OnceError>; } mod backup { pub async fn create(namespace: &Namespace, app: &Application, path: &Path) -> Result; pub fn read_metadata(path: &Path) -> Result; pub fn data_archive(path: &Path) -> Result; } 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; 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>; 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.