cmdlore 0.4.0

A command library that lives in your shell
Documentation 
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

//! Types describing a command library.

use std::collections::BTreeMap;

use serde::{Deserialize, Serialize};

/// One command definition file.
#[derive(Debug, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct Library {
    pub version: u32,

    #[serde(default)]
    pub commands: Vec<Entry>,

    /// Glob patterns matched against entry ids, used to hide entries from
    /// earlier layers without redefining them.
    #[serde(default)]
    pub disabled: Vec<String>,
}

/// A single command a user can pick.
#[derive(Debug, Clone, PartialEq, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct Entry {
    pub id: String,
    pub cmd: CommandBody,
    pub desc: String,

    #[serde(default)]
    pub tags: Vec<String>,

    #[serde(default)]
    pub params: BTreeMap<String, ParamSpec>,

    /// Marks a destructive command so the picker can warn before it is inserted.
    #[serde(default)]
    pub danger: bool,

    #[serde(skip)]
    pub layer: Layer,
}

/// A command string, optionally specialised per shell family.
#[derive(Debug, Clone, PartialEq, Deserialize, Serialize)]
#[serde(untagged)]
pub enum CommandBody {
    Shared(String),
    PerShell(BTreeMap<ShellFamily, String>),
}

/// Optional metadata for a placeholder used in a command.
#[derive(Debug, Clone, Default, PartialEq, Deserialize, Serialize)]
#[serde(deny_unknown_fields)]
pub struct ParamSpec {
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub desc: Option<String>,

    /// Command whose output supplies selectable values for this placeholder.
    /// Reserved by the schema; the current runtime ignores it and falls back to
    /// a free text prompt.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub from: Option<String>,
}

/// Where an entry came from. Later layers shadow earlier ones by id.
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, PartialOrd, Ord)]
pub enum Layer {
    #[default]
    Builtin,
    Project,
    User,
}

/// Shells that share a command dialect.
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Deserialize, Serialize)]
#[serde(rename_all = "lowercase")]
pub enum ShellFamily {
    Posix,
    PowerShell,
}

impl Entry {
    /// The command text for `family`, or `None` when this entry has no variant
    /// for it and should be hidden from that shell.
    pub fn cmd_for(&self, family: ShellFamily) -> Option<&str> {
        match &self.cmd {
            CommandBody::Shared(cmd) => Some(cmd),
            CommandBody::PerShell(variants) => variants.get(&family).map(String::as_str),
        }
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    fn entry(cmd: CommandBody) -> Entry {
        Entry {
            id: "test".into(),
            cmd,
            desc: "test".into(),
            tags: Vec::new(),
            params: BTreeMap::new(),
            danger: false,
            layer: Layer::Builtin,
        }
    }

    #[test]
    fn shared_command_serves_every_family() {
        let e = entry(CommandBody::Shared("git status".into()));
        assert_eq!(e.cmd_for(ShellFamily::Posix), Some("git status"));
        assert_eq!(e.cmd_for(ShellFamily::PowerShell), Some("git status"));
    }

    #[test]
    fn missing_variant_hides_entry_from_that_shell() {
        let e = entry(CommandBody::PerShell(BTreeMap::from([(
            ShellFamily::Posix,
            "ss -tulpn".into(),
        )])));
        assert_eq!(e.cmd_for(ShellFamily::Posix), Some("ss -tulpn"));
        assert_eq!(e.cmd_for(ShellFamily::PowerShell), None);
    }

    #[test]
    fn layers_order_from_weakest_to_strongest() {
        assert!(Layer::Builtin < Layer::Project);
        assert!(Layer::Project < Layer::User);
    }
}