Flujo de instalación

flowchart TD
    accTitle: Apothem install workflow
    accDescr: Top-down flowchart of the apothem install command from CLI invocation through adapter lookup, profile load, adapter install call, native config write, and final apothem verify check.
    A[apothem install --harness X] --> B[Resolve adapter through registry]
    B --> C[Load and validate profile YAML<br/>before writes]
    C --> D[Adapter.install(profile, project)]
    D --> E[Write native config and support cohorts]
    E --> F[apothem verify --harness X]
    F --> G{All checks pass?}
    G -- yes --> H[Done]
    G -- no --> I[Report failures]

Flujo de actualización

En apothem update --harness X:

Carga y valida ~/.config/apothem/profile.yaml o --profile PATH.
Resuelve el harness seleccionado o all a través del registro central.
Valida el plan de materialización completo antes de la primera escritura.
Llama a Adapter.update(profile, project=...).
Informa de los resultados creados, actualizados, sin cambios, omitidos, con advertencia y con error.

Flujo de desinstalación

En apothem uninstall --harness X:

Llama a Adapter.uninstall().
El adaptador elimina solo los archivos que escribió; el perfil compartido YAML y los archivos no relacionados escritos por el operador quedan intactos.

Cada adaptador escribe en su propia raíz de instalación fija: el directorio personal del usuario para los adaptadores de alcance de usuario y la ruta local del proyecto para los adaptadores de alcance de proyecto. La CLI no expone un indicador --scope; los adaptadores de alcance de proyecto requieren --project <path>. Cada destino se documenta en site/content/docs/harnesses/<harness>.mdx.

Manejo de errores

Las operaciones de instalación/actualización validan antes de escribir, hacen una copia de seguridad de los destinos coincidentes existentes antes de reemplazarlos, y fusionan solo las entradas hijas gestionadas por Apothem en los directorios de descubrimiento compartidos. --dry-run ejecuta la misma validación y devuelve resultados omitidos o sin cambios sin crear directorios ni archivos.

Reversibility (backup and rollback)

Every install pass is reversible. Replaced bytes are captured into the Apothem backup root and the pass is recorded in the harness ledger under a ULID install id; apothem rollback selects a recorded pass and restores those captured backups.

%% provenance: hand-authored %%
%% verified: 2026-07-06 %%
%% cross-reference: this page's Error handling section (back up before replace); /docs/cli-reference/rollback %%
flowchart LR
    accTitle: Apothem backup and rollback lifecycle
    accDescr: At install time each replaced target's prior bytes are captured into the Apothem backup root and the pass is recorded in the harness ledger under a ULID install id. The rollback command selects a recorded install pass by latest or install-id, restores every captured backup from the backup root, and appends a rollback record to the ledger.
    subgraph Install
        direction TB
        I1["Back up existing targets<br/>before replacement"] --> I2["Apothem backup root"]
        I1 --> I3["Ledger install record<br/>ULID install-id"]
    end
    subgraph Rollback
        direction TB
        R1["Select install pass<br/>--last or --install-id ULID"] --> R2["Restore captured backups<br/>from the backup root"]
        R2 --> R3["Append rollback record<br/>to the harness ledger"]
    end
    I2 -.->|captured bytes| R2
    I3 -.->|resolves pass| R1

Flujo de instalación