portaki-cli 8.6.0

//! `portaki dev` — build, push to the hosted sandbox, and show what happened.
//!
//! Deliberately **not** a local gateway. A parallel engine always drifts from the real host, so
//! the module runs against the actual runtime in the sandbox; the difference with running
//! locally is latency, not nature — and no line of code leaves the infrastructure.

use std::path::Path;
use std::sync::mpsc;
use std::time::Duration;

use anyhow::{bail, Context, Result};
use clap::Parser;
use notify::{RecursiveMode, Watcher};
use sha2::{Digest as _, Sha256};

use crate::ui;

/// How long to wait for the editor to finish writing before rebuilding.
const DEBOUNCE: Duration = Duration::from_millis(300);

/// Le manifeste du module — lu à chaque cycle, et désormais surveillé comme les sources.
use crate::manifest::source::MODULE_MANIFEST as MANIFEST;

/// Les migrations de la base du module, rejouées à chaque push.
const MIGRATIONS: &str = "db/migrations";

#[derive(Debug, Parser)]
/// Arguments for `portaki dev`.
pub struct DevArgs {
    /// Rebuild and redeploy on every save; follow the sandbox logs and replay the 7 scenarios
    /// after each deploy.
    #[arg(long)]
    pub watch: bool,

    /// Base URL of the dev platform. Defaults to PORTAKI_DEV_URL, then PORTAKI_API_URL,
    /// then production.
    #[arg(long)]
    pub url: Option<String>,

    /// Remove this module from the sandbox, and deploy nothing.
    #[arg(long, conflicts_with_all = ["watch", "dispatch"])]
    pub forget: bool,

    /// Operation to dispatch after each deploy. Bare, it lists what this module exposes.
    // `num_args = 0..=1` : sans valeur, `clap` refusait avec « a value is required » et
    // laissait chercher les noms ailleurs. C'est pourtant le moment où on ne les connaît pas.
    #[arg(long, num_args = 0..=1, default_missing_value = "")]
    pub dispatch: Option<String>,

    /// JSON parameters for `--dispatch`.
    #[arg(long, default_value = "{}")]
    pub params: String,

    /// `query` reads, `command` writes — the SDK's own distinction.
    #[arg(long, default_value = "query")]
    pub kind: String,

    /// In a repository holding several modules, the one to deploy.
    #[arg(long)]
    pub module: Option<String>,
}

/// Runs `portaki dev`.
pub async fn run(args: DevArgs) -> Result<()> {
    ui::header(
        "portaki dev",
        "Runs against the real host in the hosted sandbox — not a local mock.",
    );

    // Un seul module à la fois : le bac à sable et son bail se tiennent par module.
    if let Some(member) = crate::workspace::resolve(args.module.as_deref(), None)?.first() {
        crate::workspace::enter(member)?;
    }
    let module_root = std::env::current_dir().context("current_dir")?;

    // `--dispatch` nu ne demande pas un déploiement : il demande les noms. On les montre et on
    // s'arrête — compiler et pousser pour finir sur « laquelle ? » serait une minute perdue.
    if args.dispatch.as_deref() == Some("") {
        return list_operations(&module_root);
    }

    let mut token = crate::auth::access_token()?;
    let module_id = read_module_id(&module_root)?;
    let base_url = base_url(&args);

    // Avant le bail : oublier n'est pas déployer, et prendre la place pour la rendre aussitôt
    // ferait attendre une autre session pour rien.
    if args.forget {
        return forget(&base_url, &module_id, &token).await;
    }

    // Prise pour tout déploiement, `--watch` ou non. Un `portaki dev` seul écrase le bac à
    // sable exactement comme une session qui boucle — une fois au lieu de sans fin, ce qui ne
    // le rend pas moins surprenant pour celui dont le module vient de disparaître.
    //
    // Avant le premier build, pas après : refuser une fois compilé et déployé aurait déjà
    // écrasé ce que l'autre session tenait.
    let auth_url = crate::auth::api_base_url(args.url.as_deref());
    let session = crate::dev_session::start(&base_url, &auth_url, &module_id, &token).await?;

    // Ctrl-c ne déroule rien : sans ceci, le bail resterait pris jusqu'à son échéance et le
    // verrou local jusqu'au prochain lancement. Ni l'un ni l'autre n'est grave — les deux se
    // reprennent seuls — mais rendre la place tout de suite évite une attente pour rien.
    {
        // Une poignée, pas la session : une tâche qui la retiendrait empêcherait son `Drop` de
        // s'exécuter au retour normal, et le verrou local survivrait à chaque échec.
        let release = session.release();
        tokio::spawn(async move {
            if tokio::signal::ctrl_c().await.is_ok() {
                release.now().await;
                ui::blank();
                std::process::exit(130);
            }
        });
    }

    // Ouvert avant le premier déploiement : ce que le module journalise en démarrant compte aussi.
    // Le flux suit la session jusqu'à ctrl-c ; c'est aussi ce qui dit « connecté » au dock.
    if args.watch {
        tokio::spawn(crate::commands::logs::follow_forever(
            base_url.clone(),
            auth_url.clone(),
            module_id.clone(),
            token.clone(),
        ));
    }

    let mut last_digest = String::new();
    let first = cycle(
        &args,
        &base_url,
        &module_root,
        &module_id,
        &mut token,
        &mut last_digest,
        session.session_id(),
    )
    .await;

    // Rendue dès qu'on n'en a plus besoin : un déploiement ponctuel a fini, et un échec ne
    // gardera rien. Le `Drop` de la session ne peut pas s'en charger — rendre un bail distant
    // demande d'attendre une réponse, ce qu'un `Drop` ne sait pas faire — donc sans ceci un
    // build raté interdirait le suivant pendant une minute et demie.
    if first.is_err() || !args.watch {
        session.release().now().await;
    }
    first?;

    if !args.watch {
        ui::blank();
        return Ok(());
    }

    let src = module_root.join("src");
    let manifest = module_root.join(MANIFEST);
    // Les chemins sont dits depuis la racine du module, pas depuis celle du disque : un chemin
    // absolu de soixante-dix caractères repousse son explication à la ligne suivante, et la
    // liste cesse de se lire en colonnes.
    ui::list(
        "watching",
        &[
            (
                "src/",
                "every save rebuilds, redeploys and dispatches again",
            ),
            (
                "Cargo.toml",
                "a portaki-sdk feature added or dropped changes the permissions",
            ),
            (
                "i18n/",
                "the module's name, description and tab labels are read there",
            ),
            (
                "db/migrations/",
                "an edited migration replays from zero in the sandbox",
            ),
        ],
    );
    ui::blank();
    ui::advice("a build that fails does not stop the loop — fix and save again");
    ui::detail(format!("from {}", module_root.display()));

    let (tx, rx) = mpsc::channel();
    let mut watcher = notify::recommended_watcher(move |event| {
        let _ = tx.send(event);
    })
    .context("start file watcher")?;
    watcher
        .watch(&src, RecursiveMode::Recursive)
        .with_context(|| format!("watch {}", src.display()))?;
    // Le manifeste aussi : chaque cycle le relit et l'envoie, mais rien ne déclenchait de cycle
    // quand il changeait. Ajouter une surface ou une permission restait donc sans effet visible
    // jusqu'à la prochaine sauvegarde d'un fichier Rust — de quoi croire qu'il n'est pas lu.
    //
    // `NonRecursive` sur le fichier lui-même : surveiller la racine du module ferait entrer
    // `target/`, que chaque build réécrit — la boucle se relancerait elle-même sans fin.
    //
    // Le manifeste n'existe plus forcément : ce qu'il disait vient du code, de `Cargo.toml`
    // (les features, donc les permissions) et d'`i18n/` (noms et libellés).
    for watched in [manifest, module_root.join("Cargo.toml")] {
        if watched.is_file() {
            watcher
                .watch(&watched, RecursiveMode::NonRecursive)
                .with_context(|| format!("watch {}", watched.display()))?;
        }
    }
    let i18n_dir = module_root.join("i18n");
    if i18n_dir.is_dir() {
        watcher
            .watch(&i18n_dir, RecursiveMode::Recursive)
            .with_context(|| format!("watch {}", i18n_dir.display()))?;
    }
    // Une migration éditée se rejoue depuis zéro dans la sandbox : encore faut-il qu'un cycle parte.
    let migrations_dir = module_root.join(MIGRATIONS);
    if migrations_dir.is_dir() {
        watcher
            .watch(&migrations_dir, RecursiveMode::Recursive)
            .with_context(|| format!("watch {}", migrations_dir.display()))?;
    }

    loop {
        // Bloque jusqu'à la première sauvegarde…
        if rx.recv().is_err() {
            return Ok(());
        }
        // …puis absorbe la rafale qu'un éditeur produit en écrivant un fichier.
        while rx.recv_timeout(DEBOUNCE).is_ok() {}

        ui::blank();
        ui::rule(&chrono::Local::now().format("%H:%M:%S").to_string());

        if let Err(failure) = cycle(
            &args,
            &base_url,
            &module_root,
            &module_id,
            &mut token,
            &mut last_digest,
            session.session_id(),
        )
        .await
        {
            // Une erreur de compilation ne doit pas arrêter la boucle : c'est le cas courant.
            ui::report(&failure);
        }
    }
}

/// Ce que ce module expose, et comment l'appeler.
///
/// Lu du manifeste, pas de la sandbox : la question se pose avant le premier déploiement, et
/// souvent sans réseau.
fn list_operations(module_root: &Path) -> Result<()> {
    let (manifest, source) = crate::manifest::load_manifest(module_root, None)?;

    match source {
        crate::manifest::ManifestSource::Built(path) => ui::detail(format!(
            "from {}",
            path.strip_prefix(module_root).unwrap_or(&path).display()
        )),
        crate::manifest::ManifestSource::Emissions => {
            ui::detail("from the SDK emissions — no build output yet")
        }
    }

    if manifest.queries.is_empty() && manifest.commands.is_empty() {
        ui::warn(format!("{} exposes no operation", manifest.id));
        ui::detail("add a #[portaki_sdk::query] or #[portaki_sdk::command] function, then build");
        ui::blank();
        return Ok(());
    }

    show(
        "queries · read-only",
        manifest
            .queries
            .iter()
            .map(|query| (query.name.as_str(), query.r#fn.as_str())),
    );
    show(
        "commands · mutating",
        manifest
            .commands
            .iter()
            .map(|command| (command.name.as_str(), command.r#fn.as_str())),
    );

    // L'exemple porte un vrai nom du module : une syntaxe illustrée sur `<operation>` se recopie
    // mal, et le `--kind` qui va avec se devine encore moins.
    let sample = manifest
        .queries
        .first()
        .map(|query| query.name.as_str())
        .or_else(|| {
            manifest
                .commands
                .first()
                .map(|command| command.name.as_str())
        })
        .unwrap_or("listThings");

    ui::next(&[(
        &format!("portaki dev --dispatch {sample}"),
        "build, deploy, then run it",
    )]);
    ui::blank();
    // `--kind query` est le défaut : le rappeler n'apprendrait rien. C'est `command` qu'il faut
    // penser à poser, et c'est justement celui qu'on oublie.
    ui::advice("--kind command for a mutating one · --params '{…}' passes arguments");
    ui::blank();
    Ok(())
}

/// Un groupe d'opérations : le nom qu'on appelle, puis la fonction qui le sert.
///
/// Le symbole Rust est la seconde colonne parce que c'est lui qu'on cherche ensuite dans les
/// sources ; répéter « read-only » à chaque ligne n'aurait rien appris que le titre ne dise.
fn show<'a>(title: &str, operations: impl Iterator<Item = (&'a str, &'a str)>) {
    let rows: Vec<(&str, &str)> = operations.collect();
    if rows.is_empty() {
        return;
    }
    ui::list(title, &rows);
}

/// One pass: build, upload if it changed, optionally dispatch.
async fn cycle(
    args: &DevArgs,
    base_url: &str,
    module_root: &Path,
    module_id: &str,
    token: &mut String,
    last_digest: &mut String,
    session: Option<&str>,
) -> Result<()> {
    build(module_root)?;
    // Ce que `portaki build` fait après la compilation, et que `dev` sautait : régénérer le
    // manifeste depuis les émissions. Sans ça, la sandbox recevait celui du dernier `build`
    // lancé à la main — une requête ajoutée restait invisible jusqu'à ce qu'on y pense.
    crate::commands::build::refresh_outputs(module_root)?;

    // Le même résolveur que `publish`, et pas un chemin deviné : cargo nomme l'artefact
    // d'après la cible, donc `access-guide` produit `access_guide.wasm`.
    let wasm_path = crate::oci::pack::find_wasm_artifact(module_root, module_id)?;
    let wasm = std::fs::read(&wasm_path)
        .with_context(|| format!("read {} — did the build produce it?", wasm_path.display()))?;

    let manifest = sandbox_manifest(module_root)?;
    let migrations = migrations_bundle(module_root)?;

    // L'empreinte porte sur le Wasm, le manifeste ET les migrations. Sur le seul Wasm, un
    // `--watch` qui relisait `portaki.module.json` modifié répondait « unchanged » et ne l'envoyait
    // jamais : le fichier était surveillé pour rien. Une migration éditée, pareil. Elle reste
    // locale — le digest serveur, lui, est celui du Wasm.
    let fingerprint =
        upload_fingerprint(&wasm, &manifest, migrations.as_deref().unwrap_or_default());
    if fingerprint == *last_digest {
        ui::skipped(format!(
            "unchanged ({}) — nothing to upload",
            short(&sha256(&wasm))
        ));
        return Ok(());
    }

    // Le résultat est lié avant le match : garder l'appel comme sujet du match retiendrait
    // l'emprunt du jeton pendant qu'on cherche à le remplacer.
    let uploading = ui::step(format!("deploying {module_id} to the sandbox"));
    let first = deploy(
        base_url,
        module_id,
        token,
        &wasm,
        &manifest,
        migrations.as_deref(),
        session,
    )
    .await;
    let deployed = match first {
        Err(failure) if failure.is::<Unauthorized>() => {
            uploading.say("renewing the access token");
            *token = reauthenticate(args, token).await?;
            uploading.say(format!("deploying {module_id} to the sandbox"));
            deploy(
                base_url,
                module_id,
                token,
                &wasm,
                &manifest,
                migrations.as_deref(),
                session,
            )
            .await?
        }
        other => other.map_err(|failure| {
            uploading.abandon();
            failure
        })?,
    };
    uploading.done(format!("deployed {module_id}"));
    ui::field("digest", short(&deployed.digest));
    ui::field("size", ui::bytes(deployed.size_bytes));
    if let Some(install) = &deployed.install {
        print_install(install);
    }
    *last_digest = fingerprint;

    if args.watch {
        run_scenarios(args, base_url, module_id, token).await;
    }

    if let Some(operation) = &args.dispatch {
        let running = ui::step(format!("dispatching {} {operation}", args.kind));
        let first = dispatch(args, base_url, module_id, token, operation).await;
        let trace = match first {
            Err(failure) if failure.is::<Unauthorized>() => {
                running.say("renewing the access token");
                *token = reauthenticate(args, token).await?;
                dispatch(args, base_url, module_id, token, operation).await?
            }
            other => other.map_err(|failure| {
                running.abandon();
                failure
            })?,
        };
        running.done(format!(
            "{} {operation} — {} ms",
            args.kind, trace.duration_ms
        ));
        print_trace(&trace);
    }
    Ok(())
}

/// Une case de la grille Scénarios : une surface sur un cas pathologique.
#[derive(Debug, serde::Deserialize)]
struct ScenarioCell {
    surface: String,
    case: String,
    /// `ok`, `watch` ou `fail`.
    status: String,
    #[serde(default)]
    code: Option<String>,
    #[serde(default)]
    message: Option<String>,
}

/// Rejoue les sept cas sur ce qui vient d'être déployé, et affiche la grille.
///
/// Jamais fatal : un cas en échec est ce qu'on vient chercher, pas une raison d'arrêter la
/// boucle — et une plateforme qui ne sait pas les jouer n'empêche pas de développer.
async fn run_scenarios(args: &DevArgs, base_url: &str, module_id: &str, token: &mut String) {
    let running = ui::step("replaying the 7 scenarios");
    let mut outcome = post_scenarios(base_url, module_id, token).await;
    if outcome
        .as_ref()
        .is_err_and(|failure| failure.is::<Unauthorized>())
    {
        if let Ok(renewed) = reauthenticate(args, token).await {
            *token = renewed;
            outcome = post_scenarios(base_url, module_id, token).await;
        }
    }
    let cells = match outcome {
        Ok(cells) => cells,
        Err(failure) => {
            running.abandon();
            ui::warn(format!("scenarios not replayed — {failure:#}"));
            return;
        }
    };
    let failing = cells.iter().filter(|cell| cell.status != "ok").count();
    running.done(format!(
        "scenarios — {} of {} ok",
        cells.len() - failing,
        cells.len()
    ));
    for row in matrix(&cells) {
        ui::detail(row);
    }
    for cell in cells.iter().filter(|cell| cell.status != "ok") {
        let why = [cell.code.as_deref(), cell.message.as_deref()]
            .into_iter()
            .flatten()
            .collect::<Vec<_>>()
            .join(" — ");
        let line = format!("{} · {}  {why}", cell.surface, cell.case);
        if cell.status == "fail" {
            ui::failure(line);
        } else {
            ui::warn(line);
        }
    }
}

async fn post_scenarios(base_url: &str, module_id: &str, token: &str) -> Result<Vec<ScenarioCell>> {
    // Patient : la plateforme rend chaque surface sur chaque cas avant de répondre.
    let response = crate::http::patient_client()
        .post(format!(
            "{base_url}/dev/v1/modules/{module_id}/scenarios/run"
        ))
        .bearer_auth(token)
        .send()
        .await
        .context("replay the scenarios")?;
    read_json(response).await
}

/// La grille, une ligne par surface et une colonne par cas, dans l'ordre du dock.
fn matrix(cells: &[ScenarioCell]) -> Vec<String> {
    let cases = portaki_test_utils::scenarios::CASES;
    // Dans l'ordre d'arrivée, quel que soit celui de la réponse.
    let mut surfaces: Vec<&str> = Vec::new();
    for cell in cells {
        if !surfaces.contains(&cell.surface.as_str()) {
            surfaces.push(&cell.surface);
        }
    }
    let width = surfaces
        .iter()
        .map(|s| s.chars().count())
        .max()
        .unwrap_or(0);
    let mut rows = vec![format!("{:width$}  {}", "", cases.join("  "))];
    for surface in surfaces {
        let marks: Vec<String> = cases
            .iter()
            .map(|case| {
                let mark = match cells
                    .iter()
                    .find(|cell| cell.surface == surface && cell.case == *case)
                    .map(|cell| cell.status.as_str())
                {
                    Some("ok") => "✓",
                    Some("watch") => "!",
                    Some("fail") => "✗",
                    _ => "·",
                };
                format!("{mark:^w$}", w = case.len())
            })
            .collect();
        rows.push(format!("{surface:width$}  {}", marks.join("  ")));
    }
    rows
}

/// Un jeton d'accès vit quinze minutes ; une session `--watch` bien plus longtemps.
///
/// Le renouvellement est tenté une fois, pas en boucle : si le jeton de rafraîchissement est
/// lui aussi hors d'usage, réessayer ne ferait que masquer la seule chose à dire — il faut se
/// reconnecter.
async fn reauthenticate(args: &DevArgs, stale: &str) -> Result<String> {
    renew(&crate::auth::api_base_url(args.url.as_deref()), stale).await
}

pub(crate) async fn renew(auth_url: &str, stale: &str) -> Result<String> {
    crate::auth::refresh(auth_url, stale)
        .await
        .context("renew the session — run `portaki login` if this keeps failing")
}

pub(crate) fn build(module_root: &Path) -> Result<()> {
    // Release, pas debug : un build debug pèse dix fois plus et se fait refuser par le plafond
    // d'ingestion de 5 Mo. Mieux vaut compiler plus longtemps que découvrir le refus au push.
    let mut cmd = std::process::Command::new("cargo");
    cmd.current_dir(module_root)
        .args(["build", "--release", "--target", "wasm32-unknown-unknown"]);
    ui::command("compiling wasm32-unknown-unknown (release)", &mut cmd)
        .context("cargo build wasm32")
}

/// devapi rend du camelCase, comme toutes les API Portaki. Sans ce rename, `size_bytes` ne
/// trouvait rien et le déploiement échouait à la lecture de sa propre réponse — alors qu'il
/// avait réussi côté serveur.
#[derive(Debug, serde::Deserialize)]
#[serde(rename_all = "camelCase")]
pub(crate) struct DeployResponse {
    pub(crate) digest: String,
    pub(crate) size_bytes: u64,
    /// L'installation rejouée dans la sandbox. Absente d'une plateforme qui ne la rejoue pas.
    #[serde(default)]
    pub(crate) install: Option<InstallCheck>,
}

/// La case `install` de la checklist, telle que devapi la rend : `PASS`, `FAIL` ou `BLOCKED`.
#[derive(Debug, serde::Deserialize)]
pub(crate) struct InstallCheck {
    pub(crate) status: String,
    #[serde(default)]
    pub(crate) detail: String,
}

/// Ce qu'un hôte verrait en installant : migrations, isolation par logement, réinstallation,
/// deux installations à la fois. Rouge n'arrête pas la boucle — la checklist le retiendra.
pub(crate) fn print_install(install: &InstallCheck) {
    let line = format!("installation  {}", install.detail);
    match install.status.as_str() {
        "PASS" => ui::success(line),
        "FAIL" => ui::failure(line),
        _ => ui::warn(line),
    }
}

/// Le `migrations.bundle.json` que `refresh_outputs` vient d'écrire, s'il y en a un.
///
/// Sans lui, la sandbox n'installait jamais les tables du module : une migration cassée ne se
/// découvrait qu'à l'installation chez un hôte.
pub(crate) fn migrations_bundle(module_root: &Path) -> Result<Option<Vec<u8>>> {
    let path = module_root.join("target/portaki/migrations.bundle.json");
    match std::fs::read(&path) {
        Ok(bytes) => Ok(Some(bytes)),
        Err(missing) if missing.kind() == std::io::ErrorKind::NotFound => Ok(None),
        Err(failure) => Err(failure).with_context(|| format!("read {}", path.display())),
    }
}

/// `session` est celle du bail, quand nous l'avons obtenu.
///
/// Elle dit au serveur que ce push est celui du détenteur. Sans elle — bail non obtenu — il
/// n'admet le push que si personne d'autre ne tient la place, ce qui est exactement la garantie
/// que le verrou local ne peut pas donner.
pub(crate) async fn deploy(
    base_url: &str,
    module_id: &str,
    token: &str,
    wasm: &[u8],
    manifest: &str,
    migrations: Option<&[u8]>,
    session: Option<&str>,
) -> Result<DeployResponse> {
    let mut form = reqwest::multipart::Form::new()
        .part(
            "wasm",
            reqwest::multipart::Part::bytes(wasm.to_vec()).file_name("backend.wasm"),
        )
        .text("manifest", manifest.to_owned());
    if let Some(migrations) = migrations {
        form = form.part(
            "migrations",
            reqwest::multipart::Part::bytes(migrations.to_vec())
                .file_name("migrations.bundle.json"),
        );
    }
    if let Some(session) = session {
        form = form.text("sessionId", session.to_owned());
    }

    // Patient : un `.wasm` de plusieurs mégaoctets part d'ici, et le couper au bout de quinze
    // secondes casserait le déploiement normal. L'échéance de connexion, elle, reste courte.
    let response = crate::http::patient_client()
        .post(format!(
            "{}/dev/v1/modules/{module_id}/dev-deploy",
            base_url
        ))
        .bearer_auth(token)
        .multipart(form)
        .send()
        .await
        .context("upload to the dev platform")?;

    read_json(response).await
}

/// Retire ce module du bac à sable.
///
/// Un déploiement dev s'écrase à chaque push mais ne s'efface jamais : un module essayé une fois
/// restait dans l'inventaire, à côté de ceux sur lesquels on travaille. Rien n'est recompilé ici
/// — c'est une ligne qu'on retire, pas un artefact qu'on remplace.
async fn forget(base_url: &str, module_id: &str, token: &str) -> Result<()> {
    let forgetting = ui::step(format!("forgetting {module_id}"));
    let response = crate::http::client()
        .delete(format!("{base_url}/dev/v1/modules/{module_id}/dev-deploy"))
        .bearer_auth(token)
        .send()
        .await
        .map_err(|failure| {
            forgetting.abandon();
            failure
        })
        .context("ask the dev platform to forget this module")?;

    let status = response.status();
    if !status.is_success() {
        forgetting.abandon();
        let body = response.text().await.unwrap_or_default();
        anyhow::bail!("the dev platform answered {status}: {}", body.trim());
    }
    forgetting.done(format!("{module_id} is gone from the sandbox"));
    ui::advice("its inventory row is what goes — a published version, if any, is untouched");
    ui::blank();
    Ok(())
}

/// Même remarque, en pire : les `serde(default)` ci-dessous avalaient la non-correspondance en
/// silence. `--dispatch` affichait un résultat vide, une durée nulle et aucun host call sur une
/// invocation qui avait parfaitement tourné.
#[derive(Debug, serde::Deserialize)]
#[serde(rename_all = "camelCase")]
struct DispatchResponse {
    #[serde(default)]
    result_json: String,
    #[serde(default)]
    duration_ms: u64,
    #[serde(default)]
    host_calls: Vec<HostCall>,
    #[serde(default)]
    captured_effects: Vec<CapturedEffect>,
    #[serde(default)]
    published_events: Vec<String>,
}

#[derive(Debug, serde::Deserialize)]
#[serde(rename_all = "camelCase")]
struct HostCall {
    op: String,
    duration_micros: u64,
    #[serde(default)]
    error_code: String,
    /// Ce que le module a demandé. La sandbox garde les valeurs, la production ne les garde pas :
    /// absent veut dire « le runtime ne les a pas transmises », pas « le module n'a rien passé ».
    #[serde(default)]
    args_json: Option<String>,
    #[serde(default)]
    result_json: Option<String>,
}

#[derive(Debug, serde::Deserialize)]
#[serde(rename_all = "camelCase")]
struct CapturedEffect {
    op: String,
    detail_json: String,
}

async fn dispatch(
    args: &DevArgs,
    base_url: &str,
    module_id: &str,
    token: &str,
    operation: &str,
) -> Result<DispatchResponse> {
    let body = serde_json::json!({
        "operation": operation,
        "kind": args.kind,
        "paramsJson": args.params,
    });
    // Patient aussi : la plateforme exécute l'opération avant de répondre.
    let response = crate::http::patient_client()
        .post(format!("{}/dev/v1/modules/{module_id}/dispatch", base_url))
        .bearer_auth(token)
        .json(&body)
        .send()
        .await
        .context("dispatch on the dev platform")?;

    read_json(response).await
}

/// Prints what the run did — and what the sandbox refused to do.
fn print_trace(trace: &DispatchResponse) {
    if !trace.host_calls.is_empty() || !trace.captured_effects.is_empty() {
        ui::detail("what the run asked the host for:");
    }
    for call in &trace.host_calls {
        // Dans l'ordre des appels, la voix du module au milieu de ce qu'il a demandé : un `log`
        // sorti de la liste dirait tout sauf entre quels appels il a été écrit.
        if let Some(line) = log_line(call) {
            ui::detail(line);
            continue;
        }
        let outcome = if call.error_code.is_empty() {
            String::new()
        } else {
            format!("  ← {}", call.error_code)
        };
        ui::detail(format!(
            "{:>7} µs  {}{}",
            call.duration_micros, call.op, outcome
        ));
        if ui::verbose() {
            if let Some(args) = value_line("args", call.args_json.as_deref()) {
                ui::detail(args);
            }
            if let Some(result) = value_line("result", call.result_json.as_deref()) {
                ui::detail(result);
            }
        }
    }
    for effect in &trace.captured_effects {
        ui::detail(format!("captured  {}  {}", effect.op, effect.detail_json));
    }
    for event in &trace.published_events {
        ui::detail(format!("would publish  {event}"));
    }
    // « captured » et « would publish » se ressemblent assez pour qu'on les prenne pour des
    // choses faites. Elles ne le sont pas : la sandbox les note et les retient.
    if !trace.captured_effects.is_empty() || !trace.published_events.is_empty() {
        ui::detail("captured and would-publish lines were held, not performed");
    }
    if !trace.result_json.is_empty() {
        ui::result(&trace.result_json);
    }
}

/// Au-delà, une valeur noie la trace — le détail entier se lit dans l'espace développeur.
const VALUE_WIDTH: usize = 160;

/// Une ligne écrite par le module lui-même, ou `None` si cet appel n'est pas un `host::log`.
///
/// Un `log` passe par le même canal que `kv.get` : sans lire ses arguments, la trace affichait
/// « 41 µs  log », et le message que le développeur venait d'écrire restait invisible.
fn log_line(call: &HostCall) -> Option<String> {
    if call.op != "log" {
        return None;
    }
    let args: serde_json::Value = serde_json::from_str(call.args_json.as_deref()?).ok()?;
    let level = args
        .get("level")
        .and_then(serde_json::Value::as_str)
        .unwrap_or("info");
    let message = args.get("message").and_then(serde_json::Value::as_str)?;
    let fields = args
        .get("fieldsJson")
        .and_then(serde_json::Value::as_str)
        .filter(|fields| !fields.is_empty() && *fields != "{}")
        .map(|fields| format!("  {}", truncate(fields)))
        .unwrap_or_default();
    // Cinq espaces, pas deux : le message se pose sous la colonne des opérations, là où « µs »
    // décale les autres lignes.
    Some(format!("{level:>7}     {message}{fields}"))
}

/// Ce qu'un appel a demandé ou reçu, sous sa ligne. Rien quand le runtime ne l'a pas transmis.
fn value_line(label: &str, value: Option<&str>) -> Option<String> {
    let value = value?.trim();
    if value.is_empty() {
        return None;
    }
    Some(format!("{label:>7}  {}", truncate(value)))
}

fn truncate(value: &str) -> String {
    if value.chars().count() <= VALUE_WIDTH {
        return value.to_string();
    }
    let kept: String = value.chars().take(VALUE_WIDTH).collect();
    format!("{kept}…")
}

/// Le seul échec dont on sait quoi faire : renouveler et rejouer. Il porte un type pour que
/// l'appelant le distingue d'un 500, qu'il serait absurde de rejouer avec un autre jeton.
#[derive(Debug)]
pub(crate) struct Unauthorized;

impl std::fmt::Display for Unauthorized {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.write_str("the dev platform refused the token")
    }
}

impl std::error::Error for Unauthorized {}

pub(crate) async fn read_json<T: serde::de::DeserializeOwned>(
    response: reqwest::Response,
) -> Result<T> {
    let status = response.status();
    if status == reqwest::StatusCode::UNAUTHORIZED {
        return Err(anyhow::Error::new(Unauthorized));
    }
    let body = response.text().await.unwrap_or_default();
    if !status.is_success() {
        bail!("the dev platform answered {status}: {body}");
    }
    serde_json::from_str(&body).with_context(|| format!("unexpected answer: {body}"))
}

/// `--url`, then `PORTAKI_DEV_URL`, then `PORTAKI_API_URL`, then production.
fn base_url(args: &DevArgs) -> String {
    resolve_base_url(
        args.url.as_deref(),
        std::env::var("PORTAKI_DEV_URL").ok().as_deref(),
        std::env::var("PORTAKI_API_URL").ok().as_deref(),
    )
}

/// The precedence itself, free of the environment so it can be tested without touching it.
///
/// `PORTAKI_API_URL` is the variable `login` and `publish` read. Pointing at a staging platform
/// is a per-shell decision that applies to all three, and honouring it in only two sent `dev` to
/// production with a token minted elsewhere — a DNS failure at best, the wrong platform at
/// worst. `PORTAKI_DEV_URL` still wins, for the rarer case of a sandbox that lives apart.
///
/// An exported-but-empty variable means "unset", not "use the empty string as a URL".
pub(crate) fn resolve_base_url(
    explicit: Option<&str>,
    dev_var: Option<&str>,
    api_var: Option<&str>,
) -> String {
    let candidate = [explicit, dev_var, api_var]
        .into_iter()
        .flatten()
        .map(str::trim)
        .find(|value| !value.is_empty())
        .unwrap_or("https://api.portaki.app");
    candidate.trim_end_matches('/').to_string()
}

pub(crate) fn read_module_id(module_root: &Path) -> Result<String> {
    crate::manifest::source::module_id(module_root).with_context(|| {
        format!(
            "{} is not a module — run from the module root",
            module_root.display()
        )
    })
}

/// Le manifeste que la sandbox reçoit : celui écrit à la main s'il existe, `{ id, version }` du
/// crate sinon, tamponné de la version du SDK résolue par cargo et de ce que le build a émis.
///
/// Partagé avec `portaki sdk upgrade`, qui déploie deux fois — avant et après la montée de
/// version — et doit envoyer exactement ce que `dev` enverrait.
pub(crate) fn sandbox_manifest(module_root: &Path) -> Result<String> {
    let raw_manifest = crate::manifest::source::source_manifest(module_root)?;
    // Ce que le code dit du module — nom, icône, maturité… — comble ce que le manifeste tait.
    let raw_manifest =
        match std::fs::read_to_string(module_root.join(crate::manifest::catalog::BUILT_CATALOG)) {
            Ok(catalog) => crate::manifest::catalog::fill_catalog(&raw_manifest, &catalog)?,
            Err(_) => raw_manifest,
        };
    // Le même tampon que `publish`, et pour la même raison : `requiresModuleSdk` désigne le jeu
    // de contrats contre lequel typer un arbre SDUI, et il ne peut être exact que s'il vient du
    // graphe résolu par cargo. Sans lui, la sandbox recevait un manifeste muet et
    // l'inspecteur refusait de typer — pour tous les modules, toujours.
    let manifest = crate::oci::pack::stamp_sdk_version(
        &raw_manifest,
        crate::oci::pack::resolved_sdk_version(module_root)?,
    )?;
    // Et ce que le build a emis — surfaces, queries, commands. Sans les surfaces, la sandbox
    // prend le `pathSegment` pour un identifiant et demande un symbole qui n'existe pas ; sans
    // les operations, elle ne peut proposer qu'une saisie libre du nom a dispatcher.
    let manifest =
        match std::fs::read_to_string(module_root.join(crate::manifest::loader::BUILT_MANIFEST)) {
            Ok(built) => crate::oci::pack::stamp_built_declarations(&manifest, &built)?,
            // Pas de manifeste de build : on envoie ce qu'on a, comme avant.
            Err(_) => manifest,
        };
    Ok(manifest)
}

/// Ce qui décide qu'un cycle a quelque chose à envoyer : le binaire, le manifeste et les
/// migrations ensemble.
fn upload_fingerprint(wasm: &[u8], manifest: &str, migrations: &[u8]) -> String {
    sha256(&[wasm, b"\0", manifest.as_bytes(), b"\0", migrations].concat())
}

fn sha256(bytes: &[u8]) -> String {
    format!("sha256:{:x}", Sha256::digest(bytes))
}

/// Digests are unreadable in full; the first bytes are enough to tell two builds apart.
pub(crate) fn short(digest: &str) -> String {
    digest.chars().take("sha256:".len() + 12).collect()
}

#[cfg(test)]
mod tests {
    use super::DevArgs;
    use clap::Parser;

    #[test]
    fn the_scenario_matrix_reads_like_the_dock() {
        let cell = |surface: &str, case: &str, status: &str| ScenarioCell {
            surface: surface.into(),
            case: case.into(),
            status: status.into(),
            code: None,
            message: None,
        };
        let cells = [
            cell("home.card", "normal", "ok"),
            cell("home.card", "no_email", "watch"),
            cell("home.card", "no_photo", "fail"),
        ];

        let rows = matrix(&cells);

        assert_eq!(rows.len(), 2);
        assert!(
            rows[0].trim_start().starts_with("normal  no_email"),
            "{}",
            rows[0]
        );
        assert!(
            rows[1].starts_with("home.card    ✓        !    "),
            "{}",
            rows[1]
        );
        assert!(rows[1].trim_end().ends_with('✗'), "{}", rows[1]);
    }

    /// Oublier n'est pas déployer : les deux drapeaux qui poussent sont refusés avec lui.
    #[test]
    fn forget_does_not_go_with_the_flags_that_deploy() {
        let forgetting = DevArgs::try_parse_from(["dev", "--forget"]).expect("forget alone");
        assert!(forgetting.forget);
        assert!(!forgetting.watch && forgetting.dispatch.is_none());

        for pushing in [
            vec!["dev", "--forget", "--watch"],
            vec!["dev", "--forget", "--dispatch", "getConfig"],
        ] {
            assert!(DevArgs::try_parse_from(&pushing).is_err(), "{pushing:?}");
        }
    }

    /// Un manifeste modifié sans toucher au code doit repartir : c'est ce que `--watch` surveille.
    #[test]
    fn a_manifest_change_alone_is_something_to_upload() {
        let wasm = b"\0asm same bytes";
        assert_ne!(
            upload_fingerprint(wasm, r#"{"version":"0.4.0"}"#, b""),
            upload_fingerprint(wasm, r#"{"version":"0.4.1"}"#, b"")
        );
        assert_eq!(
            upload_fingerprint(wasm, "{}", b""),
            upload_fingerprint(wasm, "{}", b"")
        );
    }

    /// Une migration éditée, sans toucher au code ni au manifeste, doit repartir aussi.
    #[test]
    fn a_migration_change_alone_is_something_to_upload() {
        let wasm = b"\0asm same bytes";
        assert_ne!(
            upload_fingerprint(
                wasm,
                "{}",
                br#"{"revisions":[{"sql":"CREATE TABLE a (id INT);"}]}"#
            ),
            upload_fingerprint(
                wasm,
                "{}",
                br#"{"revisions":[{"sql":"CREATE TABLE b (id INT);"}]}"#
            )
        );
    }

    #[test]
    fn the_migrations_bundle_is_the_one_the_build_wrote() {
        let dir = tempfile::tempdir().unwrap();
        assert!(migrations_bundle(dir.path()).unwrap().is_none());

        std::fs::create_dir_all(dir.path().join("target/portaki")).unwrap();
        std::fs::write(
            dir.path().join("target/portaki/migrations.bundle.json"),
            "{}",
        )
        .unwrap();

        assert_eq!(
            migrations_bundle(dir.path()).unwrap().as_deref(),
            Some(&b"{}"[..])
        );
    }

    /// Une plateforme qui ne rejoue pas l'installation n'en dit rien : la réponse reste lisible.
    #[test]
    fn a_deploy_response_reads_the_install_outcome_when_there_is_one() {
        let body = r#"{"digest":"sha256:ab","sizeBytes":1,
            "install":{"id":"install","status":"FAIL",
              "detail":"installation : migration_apply_failed revision=002_add_status"}}"#;

        let parsed: DeployResponse = serde_json::from_str(body).expect("réponse lisible");

        let install = parsed.install.expect("install rendu");
        assert_eq!(install.status, "FAIL");
        assert!(install.detail.contains("002_add_status"));
    }

    use super::*;

    const PROD: &str = "https://api.portaki.app";

    /// Valeur obtenue par `printf '\0asm' | shasum -a 256`, pas recopiée de la sortie du test.
    #[test]
    fn a_digest_is_computed_on_the_bytes() {
        assert_eq!(
            sha256(b"\0asm"),
            "sha256:cd5d4935a48c0672cb06407bb443bc0087aff947c6b864bac886982c73b3027f"
        );
    }

    #[test]
    fn a_short_digest_stays_recognisable() {
        assert_eq!(short("sha256:abcdef0123456789"), "sha256:abcdef012345");
    }

    #[test]
    fn the_module_id_comes_from_the_manifest() {
        let dir = tempfile::tempdir().unwrap();
        std::fs::write(
            dir.path().join("portaki.module.json"),
            r#"{"id":"nuki","version":"1.4.0"}"#,
        )
        .unwrap();

        assert_eq!(read_module_id(dir.path()).unwrap(), "nuki");
    }

    /// La charge exacte que devapi renvoie, recopiée d'un déploiement réel.
    ///
    /// C'est le test qui manquait : la structure attendait `size_bytes`, la réponse portait
    /// `sizeBytes`, et le déploiement échouait à lire sa propre réussite.
    #[test]
    fn a_deploy_response_is_read_as_devapi_writes_it() {
        let body = r#"{"moduleId":"access-guide","version":"0.3.2",
            "digest":"sha256:3e9fc0c17866a50a005799fc53c854e696a101a9a6be0884b701cf157b4a9d1a",
            "permissions":["email","kv","platform"],"sizeBytes":1024374,
            "deployedAt":"2026-09-09T10:21:22.119744997Z"}"#;

        let parsed: DeployResponse = serde_json::from_str(body).expect("réponse de deploy lisible");

        assert_eq!(parsed.size_bytes, 1_024_374);
        assert!(parsed.digest.starts_with("sha256:"));
        assert!(
            parsed.install.is_none(),
            "devapi antérieur : pas d'installation rejouée"
        );
    }

    /// Les `serde(default)` d'une réponse de dispatch avalent une non-correspondance en silence :
    /// sans assertion sur les valeurs, un test de désérialisation passerait sur du vide.
    #[test]
    fn a_dispatch_response_carries_its_values_not_defaults() {
        let body = r#"{"runId":"4d7a","hasResult":true,"resultJson":"{\"ok\":true}",
            "durationMs":42,"publishedEvents":[],
            "capturedEffects":[{"op":"email.send","detailJson":"{}","at":"2026-09-09T10:00:00Z"}],
            "hostCalls":[{"op":"kv.get","durationMicros":128,"errorCode":""}]}"#;

        let parsed: DispatchResponse =
            serde_json::from_str(body).expect("réponse de dispatch lisible");

        assert_eq!(parsed.duration_ms, 42);
        assert_eq!(parsed.host_calls.len(), 1);
        assert_eq!(parsed.host_calls[0].duration_micros, 128);
        assert_eq!(parsed.captured_effects[0].detail_json, "{}");
    }

    /// La sandbox transmet les valeurs ; la CLI les ignorait, et c'est par là que passent les
    /// lignes de journal du module.
    #[test]
    fn a_host_call_keeps_the_values_the_sandbox_sent() {
        let body = r#"{"runId":"4d7a","hasResult":false,"resultJson":"","durationMs":3,
            "hostCalls":[{"op":"kv.get","durationMicros":128,"errorCode":"",
            "argsJson":"{\"key\":\"wifi\"}","resultJson":"{\"value\":\"soleil\"}"}]}"#;

        let parsed: DispatchResponse =
            serde_json::from_str(body).expect("réponse de dispatch lisible");

        assert_eq!(
            parsed.host_calls[0].args_json.as_deref(),
            Some(r#"{"key":"wifi"}"#)
        );
        assert_eq!(
            parsed.host_calls[0].result_json.as_deref(),
            Some(r#"{"value":"soleil"}"#)
        );
    }

    /// « 41 µs  log » ne disait pas ce que le module avait écrit — c'est tout l'intérêt d'un log.
    #[test]
    fn a_log_call_reads_as_the_line_the_module_wrote() {
        let call = HostCall {
            op: "log".into(),
            duration_micros: 41,
            error_code: String::new(),
            args_json: Some(
                r#"{"level":"warn","message":"clé absente","fieldsJson":"{\"key\":\"wifi\"}"}"#
                    .into(),
            ),
            result_json: None,
        };

        let line = log_line(&call).expect("une ligne de journal");

        assert!(line.contains("warn"), "{line}");
        assert!(line.contains("clé absente"), "{line}");
        assert!(line.contains(r#"{"key":"wifi"}"#), "{line}");
    }

    /// Des champs vides ajouteraient « {} » au bout de chaque ligne, pour rien.
    #[test]
    fn a_log_line_drops_empty_fields() {
        let call = HostCall {
            op: "log".into(),
            duration_micros: 12,
            error_code: String::new(),
            args_json: Some(r#"{"level":"info","message":"prêt","fieldsJson":"{}"}"#.into()),
            result_json: None,
        };

        assert_eq!(log_line(&call).unwrap().trim_end(), "   info     prêt");
    }

    /// Hors sandbox, le runtime ne transmet pas les valeurs : la ligne de journal est alors
    /// indisponible, et l'appel doit rester affiché comme un appel hôte ordinaire.
    #[test]
    fn a_call_without_values_is_not_a_log_line() {
        let without_values = HostCall {
            op: "log".into(),
            duration_micros: 41,
            error_code: String::new(),
            args_json: None,
            result_json: None,
        };
        let other_op = HostCall {
            op: "kv.get".into(),
            duration_micros: 41,
            error_code: String::new(),
            args_json: Some(r#"{"key":"wifi"}"#.into()),
            result_json: None,
        };

        assert!(log_line(&without_values).is_none());
        assert!(log_line(&other_op).is_none());
    }

    #[test]
    fn a_value_line_is_cut_before_it_floods_the_trace() {
        let long = format!("{{\"v\":\"{}\"}}", "a".repeat(400));

        let line = value_line("result", Some(&long)).expect("une ligne de valeur");

        assert!(line.ends_with('…'), "{line}");
        assert!(line.chars().count() <= VALUE_WIDTH + 12, "{line}");
        assert!(value_line("result", None).is_none());
        assert!(value_line("result", Some("   ")).is_none());
    }

    /// `PORTAKI_API_URL` est la variable que lisent `login` et `publish`. `dev` l'ignorait, et
    /// partait en production avec un jeton émis ailleurs.
    #[test]
    fn falls_back_to_the_shared_api_variable() {
        assert_eq!(
            resolve_base_url(None, None, Some("https://api-staging.portaki.app")),
            "https://api-staging.portaki.app"
        );
    }

    /// La sandbox peut vivre à part : sa variable dédiée reste prioritaire.
    #[test]
    fn prefers_the_dedicated_variable() {
        assert_eq!(
            resolve_base_url(
                None,
                Some("https://sandbox.example"),
                Some("https://api.example")
            ),
            "https://sandbox.example"
        );
    }

    /// `--url` l'emporte sur tout, et la barre finale ne double jamais celle du chemin.
    #[test]
    fn prefers_the_flag_and_trims_the_trailing_slash() {
        assert_eq!(
            resolve_base_url(
                Some("https://explicit.example/"),
                Some("https://ignored.example"),
                None
            ),
            "https://explicit.example"
        );
    }

    /// Une variable exportée vide vaut « non définie », pas « URL vide ».
    #[test]
    fn ignores_empty_and_blank_variables() {
        assert_eq!(resolve_base_url(None, Some(""), Some("   ")), PROD);
        assert_eq!(resolve_base_url(Some(""), None, None), PROD);
    }

    #[test]
    fn falls_back_to_production_when_nothing_is_set() {
        assert_eq!(resolve_base_url(None, None, None), PROD);
    }
}