node-app-build 6.4.3

//! `node-app` — Mini app developer CLI.
//!
//! Subcommands:
//!   - `new [name] [--type TYPE]`  scaffold a project (wizard when --type omitted)
//!   - `validate`                   validate manifest.json + tier rules
//!   - `package --target <arch>`    wraps the .deb build pipeline
//!   - `skills list`                list agent skills in the agentskills repo
//!   - `skills install [names...]`  install skills into ~/.claude/skills/
//!   - `completions <shell>`        print shell completion script to stdout
//!
//! Spec: `specs/456-node-app-distribution-infrastructure/`
//! Tasks: T113 (crate), T114 (new), T115 (validate), T116 (package),
//!        T117 (templates), T118 (validate rejects non-bundled cdylib),
//!        T123 (scaffold integration test).

use anyhow::Result;
use clap::{builder::ValueHint, CommandFactory, Parser, Subcommand, ValueEnum};
use clap_complete::Shell;
use std::path::PathBuf;

mod blueprint;
mod commands;
mod manifest;
mod tui;

#[derive(Parser, Debug)]
#[command(
    name = "node-app",
    about = "Scaffold, validate, and package Node mini-app .deb files",
    long_about = None,
    version,
)]
struct Cli {
    #[command(subcommand)]
    command: Command,
}

#[derive(Subcommand, Debug)]
enum Command {
    /// Scaffold a new mini app project.
    ///
    /// Two scaffolding paths:
    ///
    ///   * `--profile <profile>` (phases 2 + 4ab/4b of econ-v1/node#868):
    ///     writes fixture files embedded into this CLI binary at compile
    ///     time, with `{{...}}` placeholder substitution. No network, no
    ///     `gh`, no `git`. This is the DEFAULT when `--type` is omitted —
    ///     `node-app new foo` ≡ `node-app new foo --profile bun`. Eight
    ///     profiles ship today: `bun` (default), `bun-stage`, `stage` (a
    ///     fuller, self-stamping client-node stage teaching template —
    ///     see `node-app new --profile stage`), `bun-fullstack`, `native`,
    ///     `native-fullstack`, plus the `standalone-bun` and
    ///     `standalone-native` escape hatches (friction-prompted at
    ///     scaffold time; bypass with `--yes`).
    ///
    ///   * `--type <kind>` (legacy): clones a GitHub template repo at
    ///     scaffold time (or reads from a local dir via `--templates`).
    ///     Requires the `gh` CLI to be authenticated. Override the
    ///     template repo with `--templates` or `NODE_APP_TEMPLATES_REPO`.
    ///     When NEITHER `--type` NOR `--profile` are given AND `name` is
    ///     omitted, drops into the interactive wizard for the legacy path.
    New {
        /// Name of the new app (lowercase alphanumeric + hyphens).
        /// Wizard will ask if omitted.
        name: Option<String>,
        /// Profile to scaffold from (phase 2 of econ-v1/node#868).
        /// Uses embedded fixtures — no `gh` / no `git` required.
        /// Defaults to `bun` when neither `--profile` NOR `--type` is given.
        #[arg(short = 'p', long, value_enum)]
        profile: Option<commands::new_profile::Profile>,
        /// Template type (legacy GitHub-clone path). Wizard will ask if
        /// omitted. Mutually exclusive with `--profile`.
        #[arg(short = 't', long = "type", value_enum, conflicts_with = "profile")]
        kind: Option<AppKind>,
        /// Destination directory (defaults to ./<name>/ for `--profile`,
        /// ./node-app-<name>/ for `--type`).
        #[arg(short, long, visible_alias = "output", value_hint = ValueHint::DirPath)]
        out: Option<PathBuf>,
        /// Initialize a git repo in the scaffolded directory and create an
        /// initial commit. Implied by --github. Ignored by `--profile`.
        #[arg(long)]
        git: bool,
        /// Create a GitHub repo for the scaffold and push the initial commit.
        /// Format: `<org>/<repo>` (e.g. `econ-v1/node-app-foo`). Requires the
        /// `gh` CLI to be authenticated. Ignored by `--profile`.
        #[arg(long, value_name = "ORG/REPO")]
        github: Option<String>,
        /// Skip the post-scaffold dependency-fetch step (`bun install` for Bun
        /// templates, `cargo generate-lockfile` for cdylib/standalone-rust).
        /// Ignored by `--profile` (which never runs deps update).
        #[arg(long)]
        no_deps_update: bool,
        /// Template repository to clone (GitHub `org/repo` slug or local
        /// directory path). Defaults to econ-v1/node-app-templates.
        /// Can also be set via NODE_APP_TEMPLATES_REPO env var.
        /// Ignored by `--profile`.
        #[arg(long, value_name = "ORG/REPO-OR-PATH")]
        templates: Option<String>,
        /// Maintainer name for the package (defaults to `git config user.name`).
        /// Substituted into debian/control.template, Cargo.toml authors, package.json author.
        #[arg(long, value_name = "NAME")]
        maintainer_name: Option<String>,
        /// Maintainer email for the package (defaults to `git config user.email`).
        #[arg(long, value_name = "EMAIL")]
        maintainer_email: Option<String>,
        /// One-line description (`--profile` path only — the legacy path
        /// gets this from the wizard or hardcodes a placeholder).
        #[arg(long, value_name = "TEXT")]
        description: Option<String>,
        /// Author name (`--profile` path only). Falls back to `--maintainer-name`
        /// if given, otherwise the empty string.
        #[arg(long, value_name = "NAME")]
        author: Option<String>,
        /// Author email (`--profile` path only). Falls back to `--maintainer-email`
        /// if given, otherwise the empty string.
        #[arg(long, value_name = "EMAIL")]
        author_email: Option<String>,
        /// (`--profile` path only) Scaffold into an existing directory
        /// instead of refusing. Does not delete existing files — writes
        /// fixtures over the top.
        #[arg(long)]
        force: bool,
        /// (`--profile` path only) Bypass the `standalone-*` friction
        /// prompt. Useful for CI / scripted use. Has no effect for
        /// non-standalone profiles.
        #[arg(long, alias = "y")]
        yes: bool,
    },
    /// Validate a mini app project (run from project root or use --path).
    Validate {
        /// Path to the project root (defaults to current directory).
        #[arg(short, long, default_value = ".", value_hint = ValueHint::DirPath)]
        path: PathBuf,
    },
    /// Bundle the app's source. Bun → `dist/index.js`; native/standalone →
    /// a cross-compiled artifact under `target/node-app/<arch>/`.
    /// When `manifest.json#has_ui` is true, also runs the UI build step
    /// to produce `ui/dist/` (required before `node-app package`).
    Build {
        /// Path to the project root (defaults to current directory).
        #[arg(short, long, default_value = ".", value_hint = ValueHint::DirPath)]
        path: PathBuf,
        /// Target architecture for native/standalone apps (`arm64` or `amd64`).
        /// Defaults to the host arch. Ignored for bun apps.
        #[arg(short, long)]
        arch: Option<String>,
    },
    /// Build a `.deb` for the current app.
    ///
    /// Supports all app types: `bun` (arch `all`), `native` (arch `arm64|amd64`),
    /// and `standalone` (arch `arm64|amd64`). When `manifest.json#has_ui` is true
    /// the built UI bundle (`ui/dist` by default) is staged into the package.
    /// Run `node-app build` first to produce the artifact and UI bundle.
    Package {
        /// Path to the project root (defaults to current directory).
        #[arg(short, long, default_value = ".", value_hint = ValueHint::DirPath)]
        path: PathBuf,
        /// Target architecture: `all` (bun apps), `arm64`, or `amd64`
        /// (native/standalone apps).
        #[arg(short, long, default_value = "all")]
        arch: String,
        /// Output directory for the staged tree and `.deb`.
        #[arg(short, long, default_value = "target", value_hint = ValueHint::DirPath)]
        out: PathBuf,
        /// Where to run `dpkg-deb`. `auto` picks the container on non-Linux
        /// hosts where `dpkg-deb` isn't available; `force` always uses
        /// `debian:stable-slim`; `never` requires `dpkg-deb` on PATH.
        #[arg(long, value_enum, default_value_t = commands::package::DockerMode::Auto)]
        docker: commands::package::DockerMode,
        /// Sign a sidecar `manifest.json.sig` next to the `.deb`
        /// (apt.economy1.cloud verifies provenance from this).
        #[arg(long)]
        sign: bool,
        /// GPG key ID to sign with. Also reads `GPG_KEY` env var.
        /// Required when `--sign` is set.
        #[arg(long, env = "GPG_KEY")]
        gpg_key: Option<String>,
    },
    /// Manage agent skills from econ-v1/agentskills.
    Agentskills {
        #[command(subcommand)]
        action: SkillsAction,
    },
    /// Hot-reload dev loop: bring up a daemon, build the app, sideload
    /// over IPC, watch source files, rebuild + reload on every save
    /// (plan 457 phase C + C+).
    ///
    /// Daemon-host modes (autodetected if --daemon omitted):
    ///   --daemon deb                            apt + systemd (Linux only, sudo)
    ///   --daemon docker                         docker compose (cross-platform)
    ///   --daemon clone                          gh clone econ-v1/node + cargo run
    ///   --daemon monorepo --monorepo-path PATH  use a local checkout (cargo run)
    ///     add --instances alice,bob             run two nodes for P2P/Lightning testing
    ///   --socket /path/to/control.sock          connect to existing daemon socket
    ///
    /// Autodetect priority: monorepo cwd → existing /run/node/control.sock
    /// → linux+apt → docker → error with explicit instructions.
    Dev {
        /// Path to the project root (defaults to current directory).
        #[arg(short, long, default_value = ".", value_hint = ValueHint::DirPath)]
        path: PathBuf,
        /// Daemon-host mode.
        #[arg(long, value_parser = ["deb", "docker", "clone", "monorepo"])]
        daemon: Option<String>,
        /// Path to a local monorepo checkout. Required when --daemon monorepo.
        #[arg(long, value_hint = ValueHint::DirPath)]
        monorepo_path: Option<PathBuf>,
        /// Override the daemon IPC socket path (legacy MVP flag — when
        /// no --daemon/--monorepo is given, implies --daemon <socket>).
        #[arg(long, value_hint = ValueHint::FilePath)]
        socket: Option<PathBuf>,
        /// Override the daemon's $NODE_DEV_APPS_DIR. Each host has its
        /// own default (e.g. monorepo writes under XDG cache).
        #[arg(long, value_hint = ValueHint::DirPath)]
        dev_dir: Option<PathBuf>,
        /// Skip the source-file watcher and exit after one build+sideload.
        /// Useful for CI / scripted one-shot loads.
        #[arg(long)]
        once: bool,
        /// Path to a dependency app repo to build and stage before the dev
        /// loop. Repeat for multiple deps (e.g. --dep ../node-app-cron).
        #[arg(long, value_name = "PATH", action = clap::ArgAction::Append, value_hint = ValueHint::DirPath)]
        dep: Vec<PathBuf>,
        /// Disable the split-pane TUI and print raw interleaved logs instead.
        /// Auto-disabled when stdout is not a TTY (CI, pipe).
        #[arg(long)]
        no_tui: bool,
        /// Override an app config key for this dev session (KEY=VALUE).
        /// Repeat for multiple keys. Also reads from node-app.toml [config].
        /// Example: --config UART_DEVICE=/dev/ttyUSB0
        #[arg(long = "config", value_name = "KEY=VALUE", action = clap::ArgAction::Append)]
        config_overrides: Vec<String>,
        /// Node instances to run. Built-in names: alice (http=3001, p2p=9735)
        /// and bob (http=3002, p2p=9736). Default: alice.
        /// Comma-separated or repeatable: --instances alice,bob
        /// Only supported with --daemon monorepo.
        #[arg(long, value_parser = ["alice", "bob"], value_delimiter = ',', action = clap::ArgAction::Append)]
        instances: Vec<String>,
        /// AI-agent friendly mode: after each instance is healthy, onboard
        /// (or log in) with a generated BIP39 seed, then persist
        /// `<dev_dir>/<instance>-agent-session.json` containing the JWT,
        /// refresh token, public key, node id, and mnemonic so an AI agent
        /// can drive authed endpoints without re-implementing the auth
        /// handshake. When two instances are up, also cross-seeds peer
        /// HTTP endpoints in each node's IP pool. Idempotent: re-running
        /// reuses the existing identity and rotates only the JWT.
        ///
        /// Monorepo daemon mode only in v1. Combine with --once for CI.
        #[arg(long)]
        agent: bool,
        /// Serve the client-node PWA (`system/pwa`) instead of the legacy
        /// `system/ui` bundle. Sets `DEVELOPMENT_MODE=1` +
        /// `CLIENT_NODE_PWA_ENABLED=1` + `CLIENT_NODE_PWA_STATIC_DIR_PATH`
        /// on the daemon (the same seam production boot reads — see
        /// `core/foundation/src/config.rs::parse_client_node_pwa_enabled`),
        /// skips spawning the legacy Vite dev server, and runs under a
        /// separate cache dir + offset ports (HTTP/HTTPS/UI/OTA *and* the
        /// LDK P2P listen port — see `CLIENT_NODE_PORT_OFFSET` and the
        /// `LDK_LISTENING_ADDRESS` override in
        /// `commands::dev::host::monorepo::MonorepoHost::ensure_running`)
        /// so it doesn't collide with a plain `node-app dev` for the same
        /// instance, and both lanes can run concurrently (#1529). Monorepo
        /// daemon mode only — `node-app dev --client-node` on any other
        /// `--daemon` refuses to run.
        #[arg(long)]
        client_node: bool,
    },
    /// Agent-drivable live full-stack harness (regtest bitcoind + alice/bob
    /// Lightning nodes) with channel/payment probes for validation.
    Harness {
        #[command(subcommand)]
        action: commands::harness::HarnessAction,
    },
    /// Monitor and control the node development infrastructure
    /// (postgres + RGS rapid-gossip-sync server).
    ///
    /// Override infra directory with NODE_INFRA_PATH=/path/to/infra.
    Infra {
        #[command(subcommand)]
        action: Option<commands::infra::InfraAction>,
    },
    /// Generate or install shell completion scripts.
    #[command(hide = true)]
    Completions {
        #[command(subcommand)]
        action: CompletionsAction,
    },
    /// Inspect the blueprint this CLI version embeds.
    ///
    /// The blueprint codifies today's node-app conventions (shared
    /// externals, manifest schema version, apt deps, auditable patterns) as
    /// data. Phase 1 of econ-v1/node#868.
    Blueprint {
        #[command(subcommand)]
        cmd: BlueprintCmd,
    },
    /// Audit the current node-app against the embedded blueprint.
    ///
    /// Soft mode (default) emits warnings only and exits 0. `--strict`
    /// makes any warning a hard error (exit 1). Phase 1 of econ-v1/node#868.
    Audit {
        /// Project path (defaults to current directory).
        #[arg(short, long, default_value = ".", value_hint = ValueHint::DirPath)]
        path: PathBuf,
        /// Exit non-zero on any finding.
        #[arg(long)]
        strict: bool,
        /// Emit JSON instead of human-readable output.
        #[arg(long)]
        json: bool,
    },
    /// Rebuild one app by name and hot-load it into the running
    /// `node-app dev` daemon — no daemon restart, other apps untouched.
    ///
    /// The name resolves through the same chain dev uses (sources.lock →
    /// sibling ../node-app-<name> → cache → clone); `node-app deps` shows
    /// which source wins. Not applicable to `standalone` apps (own OS
    /// process — use `node-app restart`) or platform-runtime deps.
    Reload {
        /// App names (as in platform-depends, without the node-app- prefix).
        names: Vec<String>,
        /// Target instances (default: alice).
        #[arg(short = 'i', long, value_parser = ["alice", "bob"], value_delimiter = ',', action = clap::ArgAction::Append)]
        instances: Vec<String>,
        /// Platform repo root (defaults to cwd).
        #[arg(short, long, default_value = ".", value_hint = ValueHint::DirPath)]
        path: PathBuf,
    },
    /// Restart the platform daemon of a RUNNING `node-app dev` session,
    /// optionally rebuilding node-server first — from a second terminal,
    /// without touching the TUI or the staged apps.
    ///
    /// Equivalent to the dev TUI's `r` key; `--build` ≈ `b` → system scope.
    /// Data (DB, LDK state) is kept — process restart, not a reset.
    Restart {
        /// Target instances (default: alice).
        #[arg(short = 'i', long, value_parser = ["alice", "bob"], value_delimiter = ',', action = clap::ArgAction::Append)]
        instances: Vec<String>,
        /// Rebuild node-server (`cargo build -p node-server`) before the
        /// restart — the way to apply host-code changes to a live session.
        #[arg(long)]
        build: bool,
        /// Seconds to wait for the restart to complete (default 300;
        /// a --build on a cold workspace may need more).
        #[arg(long, default_value_t = 300)]
        timeout: u64,
        /// Platform repo root (defaults to cwd).
        #[arg(short, long, default_value = ".", value_hint = ValueHint::DirPath)]
        path: PathBuf,
    },
    /// Inspect and manage the node-app dep sources `node-app dev` resolves.
    ///
    /// Bare `node-app deps` prints a status table: where each dep listed in
    /// infra/debian/platform-depends resolves from (sources.lock pin, sibling
    /// checkout ../node-app-<name>, or the global cache ~/.cache/node-app/deps),
    /// its git rev, and working-tree state.
    ///
    /// Resolution is sticky: sources.lock pins whichever source won a dep's
    /// FIRST resolution, and a cache-pinned dep never auto-updates. `deps
    /// update` refreshes cached clones, `deps use` re-pins a dep, and `deps
    /// rm` drops cache + pin so the next dev run re-resolves from scratch.
    Deps {
        #[command(subcommand)]
        action: Option<DepsAction>,
        /// Project root (defaults to cwd).
        #[arg(short, long, default_value = ".", value_hint = ValueHint::DirPath)]
        path: PathBuf,
        /// (status view) Also `git fetch` each repo and report how far
        /// behind upstream it is. Network-heavy — off by default.
        #[arg(long)]
        fetch: bool,
    },
}

#[derive(Subcommand, Debug)]
enum DepsAction {
    /// Fetch + reset cached dep clones to upstream HEAD.
    ///
    /// Only touches ~/.cache/node-app/deps — sibling checkouts and custom
    /// pins are never reset. Dirty clones are skipped unless --force.
    Update {
        /// Dep names (as in platform-depends, without the node-app- prefix).
        names: Vec<String>,
        /// Update every cached dep clone.
        #[arg(long, conflicts_with = "names")]
        all: bool,
        /// Reset clones even if they have uncommitted changes.
        #[arg(long)]
        force: bool,
        /// Project root holding .node-app/sources.lock (defaults to cwd).
        #[arg(short, long, default_value = ".", value_hint = ValueHint::DirPath)]
        path: PathBuf,
    },
    /// Pin a dep to an explicit source in sources.lock.
    ///
    /// Examples: `deps use lcd ../node-app-lcd`, `deps use lcd --sibling`,
    /// `deps use lcd --cache`.
    Use {
        /// Dep name (as in platform-depends, without the node-app- prefix).
        name: String,
        /// Path to the source checkout (manifest name must match).
        #[arg(value_hint = ValueHint::DirPath)]
        source: Option<PathBuf>,
        /// Pin to the sibling checkout ../node-app-<name>.
        #[arg(long, conflicts_with = "source")]
        sibling: bool,
        /// Pin to the cached clone ~/.cache/node-app/deps/<name>.
        #[arg(long, conflicts_with_all = ["source", "sibling"])]
        cache: bool,
        /// Project root holding .node-app/sources.lock (defaults to cwd).
        #[arg(short, long, default_value = ".", value_hint = ValueHint::DirPath)]
        path: PathBuf,
    },
    /// Remove cached dep clones and prune matching sources.lock entries.
    Rm {
        /// Dep names as in platform-depends, without the node-app- prefix
        /// (e.g. `agent`, `ldk-node`).
        names: Vec<String>,
        /// Remove every cached dep clone.
        #[arg(long, conflicts_with = "names")]
        all: bool,
        /// Project root holding .node-app/sources.lock (defaults to cwd).
        #[arg(short, long, default_value = ".", value_hint = ValueHint::DirPath)]
        path: PathBuf,
    },
}

#[derive(Subcommand, Debug)]
enum BlueprintCmd {
    /// Print the embedded blueprint (version, rules, shared externals, layout).
    Show {
        /// Emit JSON instead of the human-readable table.
        #[arg(long)]
        json: bool,
    },
}

#[derive(Subcommand, Debug)]
enum SkillsAction {
    /// List available skills in the remote repository.
    List {
        /// Source repository slug (e.g. org/repo).
        #[arg(long, default_value = "econ-v1/agentskills")]
        repo: String,
    },
    /// Download and install skills into the Claude Code skills directory.
    ///
    /// With no names given, installs all available skills.
    /// Default install location: ~/.claude/skills/ (global, all projects).
    /// Use --local to install into .claude/skills/ in the current directory.
    Install {
        /// Names of skills to install (omit to install all).
        names: Vec<String>,
        /// Install into .claude/skills/ relative to the current directory.
        #[arg(long)]
        local: bool,
        /// Overwrite already-installed skills.
        #[arg(long)]
        update: bool,
        /// Source repository slug (e.g. org/repo).
        #[arg(long, default_value = "econ-v1/agentskills")]
        repo: String,
    },
}

#[derive(Subcommand, Debug)]
enum CompletionsAction {
    /// Print the completion script to stdout (pipe to a file to install manually).
    Generate {
        /// Target shell.
        shell: Shell,
    },
    /// Install the completion script to the canonical per-user path for your shell.
    ///
    /// Shell is auto-detected from $SHELL. Override with --shell.
    /// Supported paths:
    ///   bash  → ~/.local/share/bash-completion/completions/node-app  (auto-loaded)
    ///   zsh   → ~/.zfunc/_node-app  (add fpath + compinit to ~/.zshrc)
    ///   fish  → ~/.config/fish/completions/node-app.fish  (auto-loaded)
    Install {
        /// Shell to install for (auto-detected from $SHELL if omitted).
        #[arg(long)]
        shell: Option<Shell>,
    },
}

/// All scaffold template variants.
#[derive(Copy, Clone, Debug, PartialEq, Eq, ValueEnum)]
pub enum AppKind {
    /// TypeScript/Bun subprocess app with IPC-based capabilities.
    Bun,
    /// TypeScript/Bun app with an embedded React UI served by the platform.
    #[value(name = "bun-fullstack")]
    BunFullstack,
    /// Native Rust compiled shared library (cdylib) for maximum performance.
    Cdylib,
    /// Native Rust cdylib with an embedded React UI served by the platform.
    #[value(name = "cdylib-fullstack")]
    CdylibFullstack,
    /// Standalone Rust binary that runs as its own systemd service.
    /// Communicates with the platform via /run/node/control.sock when available.
    #[value(name = "standalone-rust")]
    StandaloneRust,
    /// Standalone Bun/TypeScript daemon that runs as its own systemd service.
    /// Communicates with the platform via /run/node/control.sock when available.
    #[value(name = "standalone-bun")]
    StandaloneBun,
    /// Standalone Rust binary that serves its own embedded React/Vite UI over
    /// HTTP, running as its own systemd service. UI assets are embedded into
    /// the binary at compile time (rust-embed) for single-binary distribution.
    #[value(name = "standalone-rust-fullstack")]
    StandaloneRustFullstack,
    /// Standalone Bun/TypeScript daemon that serves its own embedded React/Vite
    /// UI via Bun.serve, running as its own systemd service.
    #[value(name = "standalone-bun-fullstack")]
    StandaloneBunFullstack,
}

impl AppKind {
    pub fn label(self) -> &'static str {
        match self {
            AppKind::Bun => "bun",
            AppKind::BunFullstack => "bun-fullstack",
            AppKind::Cdylib => "cdylib",
            AppKind::CdylibFullstack => "cdylib-fullstack",
            AppKind::StandaloneRust => "standalone-rust",
            AppKind::StandaloneBun => "standalone-bun",
            AppKind::StandaloneRustFullstack => "standalone-rust-fullstack",
            AppKind::StandaloneBunFullstack => "standalone-bun-fullstack",
        }
    }

    /// Subdirectory name in the template repo/directory.
    pub fn template_dir_name(self) -> &'static str {
        self.label()
    }
}

fn main() -> Result<()> {
    let cli = Cli::parse();
    match cli.command {
        Command::Agentskills { action } => match action {
            SkillsAction::List { repo } => commands::skills::list(&repo),
            SkillsAction::Install {
                names,
                local,
                update,
                repo,
            } => commands::skills::install(commands::skills::SkillsInstallArgs {
                names: &names,
                global: !local,
                update,
                repo: &repo,
            }),
        },
        Command::New {
            name,
            profile,
            kind,
            out,
            git,
            github,
            no_deps_update,
            templates,
            maintainer_name,
            maintainer_email,
            description,
            author,
            author_email,
            force,
            yes,
        } => {
            // Dispatch rules:
            //   --profile <p>       → embedded-fixture path (phase 2 #868)
            //   --type <kind>       → legacy GitHub-template-clone path
            //   neither, name given → default to --profile bun
            //   neither, no name    → legacy wizard
            // `clap` enforces `profile` ⊕ `kind` (conflicts_with) so we never
            // see both at once.
            let resolved_profile: Option<commands::new_profile::Profile> = match (profile, &kind, &name) {
                (Some(p), _, _) => Some(p),
                (None, None, Some(_)) => Some(commands::new_profile::Profile::Bun),
                _ => None,
            };

            if let Some(profile) = resolved_profile {
                let name = name.ok_or_else(|| {
                    anyhow::anyhow!("`node-app new --profile <profile> <name>` requires a name")
                })?;
                // `--profile` ignores the legacy git/github/templates/no_deps_update flags
                // (documented on each flag above). If the user passed them along, no-op.
                let _ = (git, github, no_deps_update, templates);
                commands::new_profile::run(commands::new_profile::ProfileScaffoldArgs {
                    name,
                    profile,
                    output_dir: out,
                    description,
                    // Fall back to --maintainer-* when the profile-specific
                    // flags weren't passed — saves typing the same name twice.
                    author: author.or(maintainer_name),
                    author_email: author_email.or(maintainer_email),
                    force,
                    yes,
                })
            } else {
                // Legacy path. Reject the `--profile`-only flags so the user
                // gets a loud error instead of silently-ignored arguments.
                if description.is_some() || author.is_some() || author_email.is_some() || force || yes {
                    anyhow::bail!(
                        "--description, --author, --author-email, --force, and --yes \
                         are only valid with --profile (the embedded-fixture path); \
                         the legacy template path uses --maintainer-name/--maintainer-email \
                         and a hard-coded description"
                    );
                }
                let templates_repo = templates
                    .or_else(|| std::env::var("NODE_APP_TEMPLATES_REPO").ok())
                    .unwrap_or_else(|| commands::new::DEFAULT_TEMPLATES_REPO.to_string());
                commands::new::run(
                    name,
                    kind,
                    out,
                    git,
                    github,
                    no_deps_update,
                    templates_repo,
                    maintainer_name,
                    maintainer_email,
                )
            }
        }
        Command::Validate { path } => commands::validate::run(&path).map(|_| ()),
        Command::Build { path, arch } => commands::build::run(path, arch),
        Command::Package {
            path,
            arch,
            out,
            docker,
            sign,
            gpg_key,
        } => commands::package::run(path, arch, out, docker, sign, gpg_key),
        Command::Dev {
            path,
            daemon,
            monorepo_path,
            socket,
            dev_dir,
            once,
            dep,
            no_tui,
            config_overrides,
            instances,
            agent,
            client_node,
        } => {
            let config: Vec<(String, String)> = config_overrides
                .into_iter()
                .filter_map(|s| {
                    let (k, v) = s.split_once('=')?;
                    Some((k.to_string(), v.to_string()))
                })
                .collect();
            commands::dev::run(commands::dev::DevArgs {
                project_path: &path,
                daemon: daemon.as_deref(),
                monorepo_path: monorepo_path.as_deref(),
                socket_override: socket.as_deref(),
                dev_dir_override: dev_dir.as_deref(),
                once,
                dep_paths: dep,
                no_tui,
                config,
                instances,
                agent,
                client_node,
            })
        }
        Command::Harness { action } => commands::harness::run(action),
        Command::Infra { action } => commands::infra::run(action),
        Command::Completions { action } => match action {
            CompletionsAction::Generate { shell } => {
                commands::completions::generate_to_stdout(shell, &mut Cli::command());
                Ok(())
            }
            CompletionsAction::Install { shell } => {
                commands::completions::install(shell, &mut Cli::command())
            }
        },
        Command::Blueprint { cmd } => match cmd {
            BlueprintCmd::Show { json } => commands::blueprint::show(json),
        },
        Command::Audit { path, strict, json } => commands::audit::run(&path, strict, json),
        Command::Reload { names, instances, path } => {
            commands::reload::run(&path, &names, &instances)
        }
        Command::Restart { instances, build, timeout, path } => {
            commands::restart::run(&path, &instances, build, timeout)
        }
        Command::Deps { action, path, fetch } => match action {
            None => commands::deps::status(&path, fetch),
            Some(DepsAction::Update { names, all, force, path }) => {
                commands::deps::update(&path, &names, all, force)
            }
            Some(DepsAction::Use { name, source, sibling, cache, path }) => {
                commands::deps::use_source(&path, &name, source.as_deref(), sibling, cache)
            }
            Some(DepsAction::Rm { names, all, path }) => commands::deps::rm(&path, &names, all),
        },
    }
}