cargo-telar 0.2.3

Cargo subcommand for Telar apps: dev server with hot reload, and packaging into native installers.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
//! The subcommands: dev, check, fmt, preview, test, build, package and publish.

use std::path::Path;
use std::process::Command;

use clap::{Parser, ValueEnum};
use telar_project::protocol::{
    PREVIEW_COMPONENT_VAR, PREVIEW_ID_VAR, PREVIEW_LIST_VAR, PREVIEW_PNG_VAR,
    workshop_channel_file, workshop_server_file,
};

mod android;
mod artifacts;
mod bake;
mod cargo_args;
mod check;
mod cli;
mod config;
mod diagnostics;
mod doctor;
mod fmt;
mod interrupt;
mod junit;
mod library;
mod new;
mod package;
mod scratch;
mod test_cmd;
mod transpile;
mod watch;
mod web_dev;
mod workshop_channel;
mod workshop_export;

use android::build_android_package;
use bake::bake_workspace;
use check::run_check_cmd;
use cli::{
    BuildArgs, BuildFormat, Cli, CommonArgs, DevArgs, DevtoolsArg, HotArgs, PreviewArgs, Target,
    TelarCommand, WebRenderer,
};
use config::{TelarSection, load_config, missing_workshop, resolve_package};
use doctor::run_doctor_cmd;
use fmt::run_fmt_cmd;
use library::{run_package_cmd, run_publish_cmd};
use new::{run_init_cmd, run_new_cmd};
use package::{build_appimage, build_deb, build_desktop_dir, build_dmg, build_nsis, build_web};
use test_cmd::run_test_cmd;
use transpile::transpile_workspace;
use watch::{HotLoopOpts, HotMode, run_hot_loop, with_web_features};
use web_dev::run_web_dev;
use workshop_channel::{ServedElsewhere, ServerClaim, WorkshopChannel};
use workshop_export::run_workshop_export;

/// Dispatches a `cargo telar` invocation to its subcommand.
pub fn run(args: Vec<String>) {
    let cli = Cli::parse_from(std::iter::once("cargo-telar".to_string()).chain(args));
    let command = cli.command.unwrap_or_else(default_dev_command);
    let workshop = match &command {
        TelarCommand::Preview(args) => match hold_workshop(args) {
            Some(workshop) => workshop,
            None => return,
        },
        _ => HeldWorkshop::default(),
    };
    // The one place `cargo telar` prepares a build, rather than at each of the nine sites that spawn `cargo`; the ones excluded here compile nothing or prepare for themselves. Bake first: a `src:"…"` transpiles against the artifact the bake writes.
    if !matches!(
        command,
        TelarCommand::New(_)
            | TelarCommand::Init(_)
            | TelarCommand::Doctor
            | TelarCommand::Fmt(_)
            | TelarCommand::Bake
            | TelarCommand::Transpile
            | TelarCommand::Package(_)
            | TelarCommand::Publish(_)
    ) {
        if !bake_workspace() {
            drop(workshop);
            std::process::exit(1);
        }
        transpile_workspace();
    }
    match command {
        TelarCommand::New(args) => run_new_cmd(args),
        TelarCommand::Init(args) => run_init_cmd(args),
        TelarCommand::Dev(args) => run_dev_cmd(args),
        TelarCommand::Preview(args) => run_preview_cmd(args, workshop),
        TelarCommand::Build(args) => run_build_cmd(args),
        TelarCommand::Test(args) => run_test_cmd(args),
        TelarCommand::Check(args) => run_check_cmd(args),
        TelarCommand::Bake => {
            if !bake_workspace() {
                std::process::exit(1);
            }
        }
        TelarCommand::Transpile => {
            let baked = bake_workspace();
            if !transpile_workspace() || !baked {
                std::process::exit(1);
            }
        }
        TelarCommand::Package(args) => run_package_cmd(args),
        TelarCommand::Publish(args) => run_publish_cmd(args),
        TelarCommand::Doctor => run_doctor_cmd(),
        TelarCommand::Fmt(args) => run_fmt_cmd(args),
    }
}

// No subcommand behaves like `cargo telar dev` with default flags.
fn default_dev_command() -> TelarCommand {
    TelarCommand::Dev(DevArgs {
        hot: HotArgs {
            common: CommonArgs {
                package: None,
                features: None,
                target: None,
                backend: None,
                renderer: WebRenderer::Dom,
                cargo_args: vec![],
            },
            release: false,
            no_hot_reload: false,
            port: None,
        },
        devtools: None,
    })
}

/// What every compiling subcommand works out before it does anything of its own: the cargo invocation, the resolved configuration, and whether this run ends up in the terminal.
///
/// It was written out four times. `cargo telar test` is the one that legitimately does not want it — it drops `--backend` and `--renderer` on purpose, because the value is read through `option_env!` and setting it would change the build fingerprint for nothing — so it keeps its own preamble and says why.
struct BuildPlan {
    cargo_args: Vec<String>,
    config: TelarSection,
    target: Target,
    renderer: WebRenderer,
    /// Whether the application will run in the terminal this command was launched from, which only `--target tui` makes true.
    terminal: bool,
}

impl BuildPlan {
    /// `select_frontend` is what names the feature the target needs and points the binary at it, so it runs for every command rather than the two that remembered.
    fn new(common: CommonArgs, release: bool) -> Self {
        let CommonArgs {
            package,
            features,
            target,
            backend,
            renderer,
            cargo_args: extra,
        } = common;
        // A browser build spells release as `--profile web` itself, which cargo refuses beside `--release`.
        let cargo_release = release && target != Some(Target::Web);
        let mut cargo_args = build_cargo_args(&package, cargo_release, &features);
        cargo_args.extend(extra);
        if matches!(target, Some(Target::Android)) {
            cargo_args.push("--android".to_string());
        }
        let terminal = select_frontend(target, renderer, &mut cargo_args);
        let mut config = load_config(&cargo_args);
        if let Some(backend) = backend {
            config.backend = Some(backend.into());
        }
        Self {
            cargo_args,
            config,
            target: target.unwrap_or(Target::Desktop),
            renderer,
            terminal,
        }
    }
}

fn run_dev_cmd(args: DevArgs) {
    let DevArgs { hot, devtools } = args;
    let HotArgs {
        common,
        release,
        no_hot_reload,
        port,
    } = hot;
    let mut plan = BuildPlan::new(common, release);
    // CLI `--devtools off` overrides any config-file setting.
    if let Some(devtools) = devtools {
        plan.config.dev.devtools = Some(matches!(devtools, DevtoolsArg::On));
    }
    if plan.target == Target::Web {
        run_web_dev(
            with_web_features(&HotMode::Dev, plan.cargo_args),
            plan.config,
            port,
            plan.renderer,
            None,
            None,
        );
    }
    let terminal = plan.terminal;
    run_hot_loop(
        HotMode::Dev,
        HotLoopOpts {
            args: plan.cargo_args,
            app_args: Vec::new(),
            config: plan.config,
            // The hot-reload host opens a window of its own, so an app running in the terminal restarts on a change instead. Reloading in place is the only thing lost: the rebuild is the same one.
            no_hot_reload: no_hot_reload || terminal,
            terminal,
            envs: Vec::new(),
            workshop: None,
        },
    );
}

fn run_preview_cmd(args: PreviewArgs, workshop: HeldWorkshop) {
    let PreviewArgs {
        hot,
        preview,
        component,
        list,
        png,
        build,
        base,
    } = args;
    let HotArgs {
        common,
        release,
        no_hot_reload,
        port,
    } = hot;
    // Makes the generated entrypoint print one preview id per line and exit instead of opening a window.
    if list {
        run_preview_once(&common, release, "previews", PREVIEW_LIST_VAR, "1");
    }
    // The only answer for a shell with no display, and what a golden-image run compares.
    if let Some(dir) = &png {
        run_preview_once(
            &common,
            release,
            "preview-headless",
            PREVIEW_PNG_VAR,
            &dir.display().to_string(),
        );
    }
    if let Some(dir) = &build {
        run_workshop_export(common, dir, base.as_deref());
    }
    let plan = BuildPlan::new(common, release);
    if plan.target == Target::Web {
        if component.is_some() {
            eprintln!(
                "[cargo-telar] note: a page is started by its address alone, which carries no `--component`; search the workshop's sidebar for it instead."
            );
        }
        let opening = preview.as_deref().map(workshop_channel::location_of);
        run_web_dev(
            with_web_features(&HotMode::Preview, plan.cargo_args),
            plan.config,
            port,
            plan.renderer,
            opening.as_deref(),
            workshop.page,
        );
    }
    let mut envs = Vec::new();
    if let Some(component) = component {
        envs.push((PREVIEW_COMPONENT_VAR.to_string(), component));
    }
    let mut app_args = Vec::new();
    match preview {
        Some(id) if workshop_channel::is_preview_id(&id) => {
            envs.push((PREVIEW_ID_VAR.to_string(), id));
        }
        // A link carries args and a view as well as a preview, which only the workshop reads, from the location the app is started at.
        Some(link) => app_args = vec!["--location".to_string(), link],
        None => {}
    }
    // A window draws the previews itself, so the plan's `renderer`, which picks how a page draws, goes unread here.
    run_hot_loop(
        HotMode::Preview,
        HotLoopOpts {
            args: plan.cargo_args,
            app_args,
            config: plan.config,
            no_hot_reload,
            terminal: plan.terminal,
            envs,
            workshop: workshop.window,
        },
    );
}

/// What a `cargo telar preview` holds from before it builds anything until it ends, so a later one finds the workshop it runs rather than starting a second: the channel a window takes requests on, or the claim on the page's server file.
#[derive(Default)]
struct HeldWorkshop {
    window: Option<WorkshopChannel>,
    page: Option<ServerClaim>,
}

/// What this `cargo telar preview` holds for the workshop it is about to run, or `None` when one already runs for the package and the request was handed to it. Asked before anything is built: a workshop that is already running needs nothing rebuilt, and a package that declares none is refused before a build could fail on it.
fn hold_workshop(args: &PreviewArgs) -> Option<HeldWorkshop> {
    if args.list || args.png.is_some() {
        return Some(HeldWorkshop::default());
    }
    let common = &args.hot.common;
    let resolved = resolve_package(&build_cargo_args(&common.package, false, &None))
        .unwrap_or_else(|error| error.exit());
    if let Some(refusal) = missing_workshop(&resolved) {
        eprintln!("[cargo-telar] error: {refusal}");
        std::process::exit(1);
    }
    if args.build.is_some() {
        return Some(HeldWorkshop::default());
    }
    let (root, package) = (&resolved.workspace_root, resolved.name.clone());
    if common.target == Some(Target::Web) {
        return match ServerClaim::claim(&workshop_server_file(root, &package)) {
            Ok(claim) => Some(HeldWorkshop {
                page: Some(claim),
                ..HeldWorkshop::default()
            }),
            Err(session) => {
                show_served_workshop(&session, args.preview.as_deref());
                None
            }
        };
    }
    let file = workshop_channel_file(root, &package);
    if open_in_running_window(&file, args) {
        return None;
    }
    // Only a hot-reload session in a window hands requests on, and only a cdylib reloads.
    let takes_requests = matches!(common.target, None | Some(Target::Desktop))
        && !args.hot.no_hot_reload
        && resolved.produces_cdylib;
    Some(HeldWorkshop {
        window: takes_requests
            .then(|| WorkshopChannel::open(file))
            .flatten(),
        ..HeldWorkshop::default()
    })
}

/// Hands the request to the window a running `cargo telar preview` already shows for the package through the channel at `file`, and answers whether there was one: moved to the preview `args` names, or brought forward when it names none.
fn open_in_running_window(file: &Path, args: &PreviewArgs) -> bool {
    // A `--component` narrows the list a workshop starts with, which one already running cannot be asked to do.
    if args.preview.is_none() && args.component.is_some() {
        return false;
    }
    match &args.preview {
        Some(target) => {
            let opened = workshop_channel::goto(file, &workshop_channel::location_of(target));
            if opened {
                eprintln!("[cargo-telar] Opened {target} in the running workshop.");
            }
            opened
        }
        None => {
            let focused = workshop_channel::focus(file);
            if focused {
                eprintln!("[cargo-telar] Brought the running workshop forward.");
            }
            focused
        }
    }
}

/// Says where the page another `cargo telar preview --target web` serves for the package is, and where it opens `preview`, or that it is still starting. A page is not moved, since the browser showing it holds its address.
fn show_served_workshop(session: &ServedElsewhere, preview: Option<&str>) {
    let address = match session {
        ServedElsewhere::Serving(address) => address,
        ServedElsewhere::Starting { pid } => {
            let process = pid.map_or(String::new(), |pid| format!(" (process {pid})"));
            eprintln!(
                "[cargo-telar] The workshop is already starting in another session{process}, which prints its address once it serves."
            );
            return;
        }
    };
    eprintln!("[cargo-telar] The workshop is already served at {address}");
    if let Some(target) = preview {
        eprintln!(
            "[cargo-telar] Open {}",
            web_dev::address_under(address, &workshop_channel::location_of(target))
        );
    }
}

/// Runs the app binary once with `var` set, under the `telar` feature that makes it answer, and exits with its code.
///
/// The feature is the half that was missing. These entry points are reached through an environment variable the generated `run()` reads, and that `run()` only reads one in a build carrying previews — so without naming a feature here the binary starts the application instead, which is what `--png` would have done for as long as the feature behind it existed.
fn run_preview_once(
    common: &CommonArgs,
    release: bool,
    feature: &str,
    var: &str,
    value: &str,
) -> ! {
    let status = preview_once_command(common, release, feature)
        .env(var, value)
        .status()
        .expect("[cargo-telar] failed to invoke cargo");
    std::process::exit(status.code().unwrap_or(1));
}

fn preview_once_command(common: &CommonArgs, release: bool, feature: &str) -> Command {
    let mut cargo_args = vec!["run".to_string()];
    cargo_args.extend(build_cargo_args(&common.package, release, &common.features));
    cargo_args.extend(common.cargo_args.clone());
    // A host binary either way, so a browser target names nothing here; the rest keep the terminal listing and the PNG render off the frontend the project does not build.
    if let Some(target) = common.target.filter(|target| *target != Target::Web) {
        let selected = frontend_args(target, common.renderer, &cargo_args);
        cargo_args.extend(selected);
    }
    let tooling = format!("telar/{feature}");
    config::warn_if_tooling_unlocked(&cargo_args, &[&tooling]);
    cargo_args.push("--features".to_string());
    cargo_args.push(tooling);
    let mut command = Command::new("cargo");
    command.args(&cargo_args);
    command
}

fn run_build_cmd(args: BuildArgs) -> ! {
    let BuildArgs {
        mut common,
        format,
        prerender,
    } = args;

    // All desktop formats reject `--target android`, and `--format apk` implies Android. Resolved before the plan is built, because the format can move the target and the plan is what the target decides.
    match &format {
        Some(
            fmt @ (BuildFormat::Deb | BuildFormat::Appimage | BuildFormat::Dmg | BuildFormat::Nsis),
        ) if common.target == Some(Target::Android) => {
            eprintln!(
                "[cargo-telar] `--format {}` is desktop-only; drop `--target android` (use `--format apk` for Android).",
                fmt.to_possible_value()
                    .expect("no format is hidden")
                    .get_name()
            );
            std::process::exit(2);
        }
        Some(BuildFormat::Apk) => common.target = Some(Target::Android),
        Some(BuildFormat::Dir) if common.target == Some(Target::Android) => {
            eprintln!(
                "[cargo-telar] `--format dir` is desktop-only; use `--target android` (or `--format apk`) for Android."
            );
            std::process::exit(2);
        }
        _ => {}
    }
    if common.target == Some(Target::Web) && format.is_some() {
        eprintln!(
            "[cargo-telar] `--format` is for native installers; a web build is a directory of files."
        );
        std::process::exit(2);
    }
    // Build always implies --release.
    let plan = BuildPlan::new(common, true);
    if prerender && plan.target != Target::Web {
        eprintln!(
            "[cargo-telar] `--prerender` writes the pages of a site; build with `--target web`."
        );
        std::process::exit(2);
    }
    if plan.target == Target::Web {
        build_web(plan.cargo_args, plan.config, true, plan.renderer, prerender);
    }
    if plan.target == Target::Android {
        build_android_package(plan.cargo_args, plan.config)
    } else {
        match format {
            Some(BuildFormat::Deb) => build_deb(plan.cargo_args, plan.config),
            Some(BuildFormat::Appimage) => build_appimage(plan.cargo_args, plan.config),
            Some(BuildFormat::Dmg) => build_dmg(plan.cargo_args, plan.config),
            Some(BuildFormat::Nsis) => build_nsis(plan.cargo_args, plan.config),
            _ => build_desktop_dir(plan.cargo_args, plan.config),
        }
    }
}

fn build_cargo_args(
    package: &Option<String>,
    release: bool,
    features: &Option<String>,
) -> Vec<String> {
    let mut args = Vec::new();
    if let Some(pkg) = package {
        args.push("-p".to_string());
        args.push(pkg.clone());
    }
    if release {
        args.push("--release".to_string());
    }
    if let Some(features) = features {
        args.push("--features".to_string());
        args.push(features.clone());
    }
    args
}

/// The flags that build exactly the frontend `target` names, for the invocation `cargo_args` is becoming.
///
/// A package that declares a feature for the target gets it named on its own, with `--no-default-features` and the rest of its defaults re-named alongside: `default` is where a project says which frontend it builds, so asking for another one has to turn that one off. Adding it on top instead is what made `--target tui` compile a desktop stack beside the terminal one — build time nobody asked for on a desktop, and the whole of the failure under Termux, where `platform-desktop` is `cfg`'d out of the graph and the window it pays for cannot exist.
///
/// A package that declares no such feature reaches the frontend through `telar/` and keeps its defaults, so any project builds for a target without first declaring one.
fn frontend_args(target: Target, renderer: WebRenderer, cargo_args: &[String]) -> Vec<String> {
    let mut args = Vec::new();
    resolve_package(cargo_args)
        .unwrap_or_else(|error| error.exit())
        .frontend_feature(target.feature(renderer))
        .push_to(&mut args);
    args
}

/// Turns on the frontend a `--target` named returning whether the app will run in this terminal.
///
/// No target is a project left to say it in its manifest, which is where it says everything else about the build: nothing is named here, and the terminal is still answered for, because a package whose `default` is the terminal and no window runs in one whether or not anybody passed a flag.
///
/// The hot loop hands a terminal run `TELAR_TARGET` in its launch environment, which picks between the frontends a build ends up with. That is only still a question in the case where the package declared no feature for the target: there it kept a windowed default and the terminal rides along beside it.
fn select_frontend(
    target: Option<Target>,
    renderer: WebRenderer,
    cargo_args: &mut Vec<String>,
) -> bool {
    // A browser build names its own frontend in `build_web_bundle`, which is also where the wasm target and the profile that go with it are decided.
    if let Some(target) = target.filter(|target| *target != Target::Web) {
        let selected = frontend_args(target, renderer, cargo_args);
        cargo_args.extend(selected);
    }
    match target {
        Some(target) => target == Target::Tui,
        None => resolve_package(cargo_args)
            .unwrap_or_else(|error| error.exit())
            .defaults_to_terminal(),
    }
}

#[cfg(test)]
#[path = "runner.test.rs"]
mod tests;