icydb-cli 0.220.0

Developer CLI tools for IcyDB
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

//! Module: CLI schema command arguments.
//! Responsibility: define live schema observability clap surfaces.
//! Does not own: schema endpoint execution, endpoint publication, or report rendering.
//! Boundary: exposes parsed schema command values to the observability owner.

use std::path::{Path, PathBuf};

use clap::{Args, Subcommand};

use crate::cli::CanisterTarget;

///
/// SchemaCommand
///
/// SchemaCommand owns accepted live-schema observability.
///

#[derive(Debug, Subcommand)]
pub(crate) enum SchemaCommand {
    /// Read accepted schema metadata from an IcyDB canister.
    Show(CanisterTarget),

    /// Export bounded accepted-schema identity for offline diagnostics.
    DiagnosticArtifact(DiagnosticArtifactArgs),

    /// Bind an accepted diagnostic artifact to generated/source metadata.
    DiagnosticSourceMetadata(DiagnosticSourceMetadataArgs),

    /// Inspect or operate an explicit deployed source migration.
    #[command(subcommand)]
    Migration(SchemaMigrationCommand),
}

/// Target and new output path for one diagnostic schema artifact.
#[derive(Args, Debug)]
pub(crate) struct DiagnosticArtifactArgs {
    #[command(flatten)]
    target: CanisterTarget,

    /// New artifact path; an existing file is never overwritten.
    #[arg(short, long, value_name = "PATH")]
    output: PathBuf,
}

impl DiagnosticArtifactArgs {
    pub(crate) const fn target(&self) -> &CanisterTarget {
        &self.target
    }

    pub(crate) fn output(&self) -> &Path {
        self.output.as_path()
    }
}

/// Exact accepted artifact and source label for one host-only metadata binding.
#[derive(Args, Debug)]
pub(crate) struct DiagnosticSourceMetadataArgs {
    /// Existing exact accepted-schema diagnostic artifact.
    #[arg(long, value_name = "PATH")]
    artifact: PathBuf,

    /// Generated package or source path that owns this metadata.
    #[arg(long, value_name = "SOURCE")]
    source: String,

    /// New metadata path; an existing file is never overwritten.
    #[arg(short, long, value_name = "PATH")]
    output: PathBuf,
}

impl DiagnosticSourceMetadataArgs {
    pub(crate) fn artifact(&self) -> &Path {
        self.artifact.as_path()
    }

    pub(crate) const fn source(&self) -> &str {
        self.source.as_str()
    }

    pub(crate) fn output(&self) -> &Path {
        self.output.as_path()
    }
}

/// Deployed-only source migration operations.
#[derive(Debug, Subcommand)]
pub(crate) enum SchemaMigrationCommand {
    /// Read one bounded migration status page.
    Status(CanisterTarget),
    /// Advance one bounded migration step.
    Advance(CanisterTarget),
    /// Repeatedly advance while deployed identity and plan remain exact.
    Run(CanisterTarget),
    /// Abort a migration before irreversible rewriting begins.
    Abort(ConfirmedMigrationTarget),
    /// Adopt an exact existing version-1 generated schema.
    Adopt(ConfirmedMigrationTarget),
}

/// Destructive migration target requiring explicit confirmation.
#[derive(Args, Debug)]
pub(crate) struct ConfirmedMigrationTarget {
    #[command(flatten)]
    target: CanisterTarget,

    /// Confirm the controller operation explicitly.
    #[arg(long)]
    yes: bool,
}

impl ConfirmedMigrationTarget {
    pub(crate) const fn target(&self) -> &CanisterTarget {
        &self.target
    }

    pub(crate) const fn confirmed(&self) -> bool {
        self.yes
    }
}