mod.rs 68.5%

87 of 127 lines run, 17 of 48 functions · run #9 on main · run missed

//! The `spectra` command line (spec §19). Output follows `oxy`: colour and
//! glyphs on a UTF-8 terminal, plain when piped, with `--plain` or with
//! `NO_COLOR`; `--json` prints one document on stdout and nothing else.

pub mod admin;
pub mod agent;
pub mod format;
pub mod identity;
pub mod json;
pub mod marks;
pub mod project;
pub mod serve;
pub mod ui;

use anyhow::{bail, Result};
use clap::{Parser, Subcommand};
use std::path::PathBuf;

#[derive(Parser)]
#[command(name = "spectra", version = env!("SPECTRA_VERSION_LONG"), about = "A control plane for AI coding agents")]
pub struct Cli {
    /// Plain output: no colour or glyphs (also NO_COLOR, or when not a terminal)
    #[arg(long, global = true)]
    pub plain: bool,
    /// The data directory (default: $XDG_DATA_HOME/spectra, else ~/.local/share/spectra)
    #[arg(long, global = true, env = "SPECTRA_DATA")]
    pub data: Option<PathBuf>,
    #[command(subcommand)]
    pub command: Command,
}

#[derive(Subcommand)]
pub enum Command {
    /// The version and build of this binary
    Version {
        /// Machine-readable output
        #[arg(long)]
        json: bool,
    },
    /// Make this machine's Spectra: record the owner's identity (read from
    /// their OXY_HOME and proven by signing) and make the instance key
    Init {
        /// The owner's OXY_HOME (default: $OXY_HOME, else ~/.config/oxy)
        #[arg(long)]
        owner_home: Option<PathBuf>,
        /// This instance's name (default: the host name)
        #[arg(long)]
        name: Option<String>,
    },
    /// The owner's and the instance's identities: show, refresh
    Identity {
        #[command(subcommand)]
        command: IdentityCmd,
    },
    /// Run the daemon: the ledger, Tuner on the Unix socket and a loopback port
    Serve {
        /// The loopback address and port for browsers and HTTP clients
        #[arg(long, default_value = "127.0.0.1:7350")]
        bind: String,
        /// Allow a non-loopback address in plain HTTP
        #[arg(long)]
        insecure: bool,
    },
    /// The checkouts agents work in: add, list
    Project {
        #[command(subcommand)]
        command: ProjectCmd,
    },
    /// Agents, each its owner's delegate: add, list, disable
    Agent {
        #[command(subcommand)]
        command: AgentCmd,
    },
    /// The ledger's own checks: verify, check, rebuild
    Admin {
        #[command(subcommand)]
        command: Admin,
    },
}

#[derive(Subcommand)]
pub enum IdentityCmd {
    /// The owner and the instance as the ledger knows them
    Show {
        #[arg(long)]
        json: bool,
    },
    /// Record the owner's current identity after `oxy identity delegate add|remove`
    Refresh {
        #[arg(long)]
        owner_home: Option<PathBuf>,
    },
}

#[derive(Subcommand)]
pub enum ProjectCmd {
    /// Register a checkout: its repository id, remote and pinned subrepos
    Add {
        path: PathBuf,
        /// Its name (default: the directory's)
        #[arg(long)]
        name: Option<String>,
        /// Its remote URL (default: the checkout's origin)
        #[arg(long)]
        remote: Option<String>,
        #[arg(long)]
        owner_home: Option<PathBuf>,
    },
    /// Every project with what it pins, what pins it, and its agents
    List {
        #[arg(long)]
        json: bool,
    },
}

#[derive(Subcommand)]
pub enum AgentCmd {
    /// Make an agent's key in its own home and record it once you delegate to it
    Add {
        /// Lower-case letters, digits and dashes
        name: String,
        /// claude-code, antigravity, kimi-code, codex or other
        #[arg(long)]
        kind: String,
        /// The project it works in
        #[arg(long)]
        project: String,
        /// The agent's own OXY_HOME, where its key is made and kept
        #[arg(long)]
        home: PathBuf,
        /// Bind the key to this Unix user: a request from another is refused
        #[arg(long)]
        uid: Option<u32>,
        /// Bind the key to the Unix user of its first signed connection
        #[arg(long, conflicts_with = "uid")]
        learn_uid: bool,
        /// How long to wait for your delegation, in seconds
        #[arg(long, default_value_t = 600)]
        wait: u64,
        /// The owner's OXY_HOME
        #[arg(long)]
        owner_home: Option<PathBuf>,
    },
    /// Every agent with its owner, key, delegation and state
    List {
        #[arg(long)]
        json: bool,
    },
    /// Refuse an agent's key from now on
    Disable {
        name: String,
        #[arg(long)]
        owner_home: Option<PathBuf>,
    },
}

#[derive(Subcommand)]
pub enum Admin {
    /// Recompute the hash chain and check every checkpoint and proof (exit 1 on any finding)
    Verify {
        /// Machine-readable output
        #[arg(long)]
        json: bool,
    },
    /// Whether the projections equal a rebuild from the ledger
    Check,
    /// Replay the ledger into every projection
    Rebuild,
}

/// What every command needs: where the data lives.
pub struct Ctx {
    pub data: PathBuf,
}

impl Ctx {
    /// The ledger's database, which must exist.
    pub fn db(&self) -> Result<PathBuf> {
        let db = self.data.join("spectra.db");
        if !db.exists() {
            bail!("no Spectra in {} (run `spectra init`, or pass --data)", self.data.display());
        }
        Ok(db)
    }

    /// The ledger, for writing: the instance key signs its checkpoints, and
    /// the lock keeps any other writer out.
    pub async fn writer(&self) -> Result<spectra_core::ledger::Ledger> {
        let db = self.db()?;
        let instance = spectra_core::keys::KeyPair::instance(&self.data, "spectra")?;
        spectra_core::ledger::Ledger::open(&db, Some(instance)).await
    }

    /// The daemon's Unix socket.
    pub fn socket(&self) -> PathBuf {
        self.data.join("spectra.sock")
    }

    /// Somewhere to append the owner's signed events: straight to the
    /// ledger, or through the daemon when it is serving (spec §8.5).
    pub async fn owner_writer(&self, owner_home: &std::path::Path) -> Result<Writer> {
        let db = self.db()?;
        if spectra_mcp::client::Client::alive(&self.socket()).await {
            let ledger = spectra_core::ledger::Ledger::open_read_only(&db).await?;
            let transport = identity::recorded_owner(&ledger, owner_home).await?;
            return Ok(Writer::Daemon { ledger, client: Box::new(spectra_mcp::client::Client::new(&self.socket(), Some(transport))) });
        }
        Ok(Writer::Direct(self.writer().await?))
    }

    /// `[owner] home` from spectra.toml.
    pub fn config_owner_home(&self) -> Option<PathBuf> {
        let text = std::fs::read_to_string(self.data.join("spectra.toml")).ok()?;
        let t: toml::Table = text.parse().ok()?;
        t.get("owner")?.get("home")?.as_str().map(PathBuf::from)
    }
}

/// Where the owner's events go.
pub enum Writer {
    Direct(spectra_core::ledger::Ledger),
    Daemon { ledger: spectra_core::ledger::Ledger, client: Box<spectra_mcp::client::Client> },
}

impl Writer {
    /// The ledger, for reading.
    pub fn ledger(&self) -> &spectra_core::ledger::Ledger {
        match self {
            Writer::Direct(l) | Writer::Daemon { ledger: l, .. } => l,
        }
    }

    /// Append events signed over their payload, then checkpoint.
    pub async fn append(&self, events: Vec<spectra_core::event::NewEvent>) -> Result<()> {
        match self {
            Writer::Direct(l) => {
                l.append(events).await?;
                l.checkpoint().await?;
            }
            Writer::Daemon { client, .. } => {
                let wire: Vec<_> = events.iter().map(spectra_core::daemon::WireEvent::from_new).collect();
                let r = client.send("POST", "/api/v1/ledger/events", &[], serde_json::to_vec(&wire)?).await?;
                if r.status != 200 {
                    let why = r
                        .json()
                        .ok()
                        .and_then(|v| v.get("title").and_then(|t| t.as_str()).map(String::from))
                        .unwrap_or_else(|| String::from_utf8_lossy(&r.body).into());
                    bail!("the daemon refused: {why}");
                }
            }
        }
        Ok(())
    }
}

fn init_logging() {
    let filter = tracing_subscriber::EnvFilter::try_from_env("SPECTRA_LOG").unwrap_or_else(|_| tracing_subscriber::EnvFilter::new("warn"));
    tracing_subscriber::fmt().with_env_filter(filter).with_writer(std::io::stderr).init();
}

fn default_data() -> PathBuf {
    if let Ok(x) = std::env::var("XDG_DATA_HOME") {
        return PathBuf::from(x).join("spectra");
    }
    let home = std::env::var("HOME").unwrap_or_else(|_| ".".into());
    PathBuf::from(home).join(".local").join("share").join("spectra")
}

fn runtime() -> Result<tokio::runtime::Runtime> {
    Ok(tokio::runtime::Builder::new_multi_thread().enable_all().build()?)
}

pub fn run() -> Result<i32> {
    let cli = Cli::parse();
    ui::init(cli.plain);
    let ctx = Ctx { data: cli.data.unwrap_or_else(default_data) };
    match cli.command {
        Command::Version { json } => version(json),
        Command::Init { owner_home, name } => runtime()?.block_on(identity::init(&ctx, owner_home, name)),
        Command::Identity { command } => runtime()?.block_on(async {
            match command {
                IdentityCmd::Show { json } => identity::show(&ctx, json).await,
                IdentityCmd::Refresh { owner_home } => identity::refresh(&ctx, owner_home).await,
            }
        }),
        Command::Serve { bind, insecure } => {
            init_logging();
            runtime()?.block_on(serve::serve(&ctx, &bind, insecure))
        }
        Command::Project { command } => runtime()?.block_on(async {
            match command {
                ProjectCmd::Add { path, name, remote, owner_home } => project::add(&ctx, &path, name, remote, owner_home).await,
                ProjectCmd::List { json } => project::list(&ctx, json).await,
            }
        }),
        Command::Agent { command } => runtime()?.block_on(async {
            match command {
                AgentCmd::Add { name, kind, project, home, uid, learn_uid, wait, owner_home } => {
                    agent::add(&ctx, agent::Add { name, kind, project, home, uid, learn_uid, wait_secs: wait, owner_home }).await
                }
                AgentCmd::List { json } => agent::list(&ctx, json).await,
                AgentCmd::Disable { name, owner_home } => agent::disable(&ctx, &name, owner_home).await,
            }
        }),
        Command::Admin { command } => runtime()?.block_on(async {
            match command {
                Admin::Verify { json } => admin::verify(&ctx, json).await,
                Admin::Check => admin::check(&ctx).await,
                Admin::Rebuild => admin::rebuild(&ctx).await,
            }
        }),
    }
}

fn version(as_json: bool) -> Result<i32> {
    if as_json {
        println!(
            "{}",
            serde_json::json!({
                "version": env!("CARGO_PKG_VERSION"),
                "build": env!("SPECTRA_BUILD_ID"),
                "mcp_protocol_versions": spectra_mcp::PROTOCOL_VERSIONS,
                "ledger_format": spectra_core::LEDGER_FORMAT,
            })
        );
    } else {
        println!("spectra {}", env!("SPECTRA_VERSION_LONG"));
    }
    Ok(0)
}

`/`	Search
`g` `c`	Code
`g` `h`	History
`g` `b`	Bookmarks
`g` `t`	Trust
`y`	Permalink to this state (files and trees)
`?`	This sheet

1		//! The `spectra` command line (spec §19). Output follows `oxy`: colour and
2		//! glyphs on a UTF-8 terminal, plain when piped, with `--plain` or with
3		//! `NO_COLOR`; `--json` prints one document on stdout and nothing else.
4
5		pub mod admin;
6		pub mod agent;
7		pub mod format;
8		pub mod identity;
9		pub mod json;
10		pub mod marks;
11		pub mod project;
12		pub mod serve;
13		pub mod ui;
14
15		use anyhow::{bail, Result};
16		use clap::{Parser, Subcommand};
17		use std::path::PathBuf;
18
19		#[derive(Parser)]
20		#[command(name = "spectra", version = env!("SPECTRA_VERSION_LONG"), about = "A control plane for AI coding agents")]
21		pub struct Cli {
22		/// Plain output: no colour or glyphs (also NO_COLOR, or when not a terminal)
23		#[arg(long, global = true)]
24		pub plain: bool,
25		/// The data directory (default: $XDG_DATA_HOME/spectra, else ~/.local/share/spectra)
26		#[arg(long, global = true, env = "SPECTRA_DATA")]
27		pub data: Option<PathBuf>,
28		#[command(subcommand)]
29		pub command: Command,
30		}
31
32		#[derive(Subcommand)]
33		pub enum Command {
34		/// The version and build of this binary
35		Version {
36		/// Machine-readable output
37		#[arg(long)]
38		json: bool,
39		},
40		/// Make this machine's Spectra: record the owner's identity (read from
41		/// their OXY_HOME and proven by signing) and make the instance key
42		Init {
43		/// The owner's OXY_HOME (default: $OXY_HOME, else ~/.config/oxy)
44		#[arg(long)]
45		owner_home: Option<PathBuf>,
46		/// This instance's name (default: the host name)
47		#[arg(long)]
48		name: Option<String>,
49		},
50		/// The owner's and the instance's identities: show, refresh
51		Identity {
52		#[command(subcommand)]
53		command: IdentityCmd,
54		},
55		/// Run the daemon: the ledger, Tuner on the Unix socket and a loopback port
56		Serve {
57		/// The loopback address and port for browsers and HTTP clients
58		#[arg(long, default_value = "127.0.0.1:7350")]
59		bind: String,
60		/// Allow a non-loopback address in plain HTTP
61		#[arg(long)]
62		insecure: bool,
63		},
64		/// The checkouts agents work in: add, list
65		Project {
66		#[command(subcommand)]
67		command: ProjectCmd,
68		},
69		/// Agents, each its owner's delegate: add, list, disable
70		Agent {
71		#[command(subcommand)]
72		command: AgentCmd,
73		},
74		/// The ledger's own checks: verify, check, rebuild
75		Admin {
76		#[command(subcommand)]
77		command: Admin,
78		},
79		}
80
81		#[derive(Subcommand)]
82		pub enum IdentityCmd {
83		/// The owner and the instance as the ledger knows them
84		Show {
85		#[arg(long)]
86		json: bool,
87		},
88		/// Record the owner's current identity after `oxy identity delegate add\|remove`
89		Refresh {
90		#[arg(long)]
91		owner_home: Option<PathBuf>,
92		},
93		}
94
95		#[derive(Subcommand)]
96		pub enum ProjectCmd {
97		/// Register a checkout: its repository id, remote and pinned subrepos
98		Add {
99		path: PathBuf,
100		/// Its name (default: the directory's)
101		#[arg(long)]
102		name: Option<String>,
103		/// Its remote URL (default: the checkout's origin)
104		#[arg(long)]
105		remote: Option<String>,
106		#[arg(long)]
107		owner_home: Option<PathBuf>,
108		},
109		/// Every project with what it pins, what pins it, and its agents
110		List {
111		#[arg(long)]
112		json: bool,
113		},
114		}
115
116		#[derive(Subcommand)]
117		pub enum AgentCmd {
118		/// Make an agent's key in its own home and record it once you delegate to it
119		Add {
120		/// Lower-case letters, digits and dashes
121		name: String,
122		/// claude-code, antigravity, kimi-code, codex or other
123		#[arg(long)]
124		kind: String,
125		/// The project it works in
126		#[arg(long)]
127		project: String,
128		/// The agent's own OXY_HOME, where its key is made and kept
129		#[arg(long)]
130		home: PathBuf,
131		/// Bind the key to this Unix user: a request from another is refused
132		#[arg(long)]
133		uid: Option<u32>,
134		/// Bind the key to the Unix user of its first signed connection
135		#[arg(long, conflicts_with = "uid")]
136		learn_uid: bool,
137		/// How long to wait for your delegation, in seconds
138		#[arg(long, default_value_t = 600)]
139		wait: u64,
140		/// The owner's OXY_HOME
141		#[arg(long)]
142		owner_home: Option<PathBuf>,
143		},
144		/// Every agent with its owner, key, delegation and state
145		List {
146		#[arg(long)]
147		json: bool,
148		},
149		/// Refuse an agent's key from now on
150		Disable {
151		name: String,
152		#[arg(long)]
153		owner_home: Option<PathBuf>,
154		},
155		}
156
157		#[derive(Subcommand)]
158		pub enum Admin {
159		/// Recompute the hash chain and check every checkpoint and proof (exit 1 on any finding)
160		Verify {
161		/// Machine-readable output
162		#[arg(long)]
163		json: bool,
164		},
165		/// Whether the projections equal a rebuild from the ledger
166		Check,
167		/// Replay the ledger into every projection
168		Rebuild,
169		}
170
171		/// What every command needs: where the data lives.
172		pub struct Ctx {
173		pub data: PathBuf,
174		}
175
176		impl Ctx {
177		/// The ledger's database, which must exist.
178	82×	pub fn db(&self) -> Result<PathBuf> {
179	82×	let db = self.data.join("spectra.db");
180	82×	if !db.exists() {
181	1×	bail!("no Spectra in {} (run `spectra init`, or pass --data)", self.data.display());
182	81×	}
183	81×	Ok(db)
184	82×	}
185
186		/// The ledger, for writing: the instance key signs its checkpoints, and
187		/// the lock keeps any other writer out.
188	28×	pub async fn writer(&self) -> Result<spectra_core::ledger::Ledger> {
189	28×	let db = self.db()?;
190	28×	let instance = spectra_core::keys::KeyPair::instance(&self.data, "spectra")?;
191	28×	spectra_core::ledger::Ledger::open(&db, Some(instance)).await
192	28×	}
193
194		/// The daemon's Unix socket.
195	33×	pub fn socket(&self) -> PathBuf {
196	33×	self.data.join("spectra.sock")
197	33×	}
198
199		/// Somewhere to append the owner's signed events: straight to the
200		/// ledger, or through the daemon when it is serving (spec §8.5).
201	25×	pub async fn owner_writer(&self, owner_home: &std::path::Path) -> Result<Writer> {
202	25×	let db = self.db()?;
203	25×	if spectra_mcp::client::Client::alive(&self.socket()).await {
204	2×	let ledger = spectra_core::ledger::Ledger::open_read_only(&db).await?;
205	2×	let transport = identity::recorded_owner(&ledger, owner_home).await?;
206	2×	return Ok(Writer::Daemon { ledger, client: Box::new(spectra_mcp::client::Client::new(&self.socket(), Some(transport))) });
207	23×	}
208	23×	Ok(Writer::Direct(self.writer().await?))
209	25×	}
210
211		/// `[owner] home` from spectra.toml.
212	38×	pub fn config_owner_home(&self) -> Option<PathBuf> {
213	38×	let text = std::fs::read_to_string(self.data.join("spectra.toml")).ok()?;
214	26×	let t: toml::Table = text.parse().ok()?;
215	26×	t.get("owner")?.get("home")?.as_str().map(PathBuf::from)
216	38×	}
217		}
218
219		/// Where the owner's events go.
220		pub enum Writer {
221		Direct(spectra_core::ledger::Ledger),
222		Daemon { ledger: spectra_core::ledger::Ledger, client: Box<spectra_mcp::client::Client> },
223		}
224
225		impl Writer {
226		/// The ledger, for reading.
227	25×	pub fn ledger(&self) -> &spectra_core::ledger::Ledger {
228	25×	match self {
229	25×	Writer::Direct(l) \| Writer::Daemon { ledger: l, .. } => l,
230		}
231	25×	}
232
233		/// Append events signed over their payload, then checkpoint.
234	23×	pub async fn append(&self, events: Vec<spectra_core::event::NewEvent>) -> Result<()> {
235	23×	match self {
236	21×	Writer::Direct(l) => {
237	21×	l.append(events).await?;
238	21×	l.checkpoint().await?;
239		}
240	2×	Writer::Daemon { client, .. } => {
241	2×	let wire: Vec<_> = events.iter().map(spectra_core::daemon::WireEvent::from_new).collect();
242	2×	let r = client.send("POST", "/api/v1/ledger/events", &[], serde_json::to_vec(&wire)?).await?;
243	2×	if r.status != 200 {
244	0×	let why = r
245	0×	.json()
246	0×	.ok()
247	0×	.and_then(\|v\| v.get("title").and_then(\|t\| t.as_str()).map(String::from))
248	0×	.unwrap_or_else(\|\| String::from_utf8_lossy(&r.body).into());
249	0×	bail!("the daemon refused: {why}");
250	2×	}
251		}
252		}
253	23×	Ok(())
254	23×	}
255		}
256
257	6×	fn init_logging() {
258	6×	let filter = tracing_subscriber::EnvFilter::try_from_env("SPECTRA_LOG").unwrap_or_else(\|_\| tracing_subscriber::EnvFilter::new("warn"));
259	6×	tracing_subscriber::fmt().with_env_filter(filter).with_writer(std::io::stderr).init();
260	6×	}
261
262	0×	fn default_data() -> PathBuf {
263	0×	if let Ok(x) = std::env::var("XDG_DATA_HOME") {
264	0×	return PathBuf::from(x).join("spectra");
265	0×	}
266	0×	let home = std::env::var("HOME").unwrap_or_else(\|_\| ".".into());
267	0×	PathBuf::from(home).join(".local").join("share").join("spectra")
268	0×	}
269
270	69×	fn runtime() -> Result<tokio::runtime::Runtime> {
271	69×	Ok(tokio::runtime::Builder::new_multi_thread().enable_all().build()?)
272	69×	}
273
274	69×	pub fn run() -> Result<i32> {
275	69×	let cli = Cli::parse();
276	69×	ui::init(cli.plain);
277	69×	let ctx = Ctx { data: cli.data.unwrap_or_else(default_data) };
278	69×	match cli.command {
279	0×	Command::Version { json } => version(json),
280	13×	Command::Init { owner_home, name } => runtime()?.block_on(identity::init(&ctx, owner_home, name)),
281	0×	Command::Identity { command } => runtime()?.block_on(async {
282	0×	match command {
283	0×	IdentityCmd::Show { json } => identity::show(&ctx, json).await,
284	0×	IdentityCmd::Refresh { owner_home } => identity::refresh(&ctx, owner_home).await,
285		}
286	0×	}),
287	6×	Command::Serve { bind, insecure } => {
288	6×	init_logging();
289	6×	runtime()?.block_on(serve::serve(&ctx, &bind, insecure))
290		}
291	16×	Command::Project { command } => runtime()?.block_on(async {
292	16×	match command {
293	14×	ProjectCmd::Add { path, name, remote, owner_home } => project::add(&ctx, &path, name, remote, owner_home).await,
294	2×	ProjectCmd::List { json } => project::list(&ctx, json).await,
295		}
296	16×	}),
297	17×	Command::Agent { command } => runtime()?.block_on(async {
298	17×	match command {
299	11×	AgentCmd::Add { name, kind, project, home, uid, learn_uid, wait, owner_home } => {
300	11×	agent::add(&ctx, agent::Add { name, kind, project, home, uid, learn_uid, wait_secs: wait, owner_home }).await
301		}
302	4×	AgentCmd::List { json } => agent::list(&ctx, json).await,
303	2×	AgentCmd::Disable { name, owner_home } => agent::disable(&ctx, &name, owner_home).await,
304		}
305	17×	}),
306	17×	Command::Admin { command } => runtime()?.block_on(async {
307	17×	match command {
308	12×	Admin::Verify { json } => admin::verify(&ctx, json).await,
309	4×	Admin::Check => admin::check(&ctx).await,
310	1×	Admin::Rebuild => admin::rebuild(&ctx).await,
311		}
312	17×	}),
313		}
314	69×	}
315
316	0×	fn version(as_json: bool) -> Result<i32> {
317	0×	if as_json {
318	0×	println!(
319	0×	"{}",
320	0×	serde_json::json!({
321	0×	"version": env!("CARGO_PKG_VERSION"),
322	0×	"build": env!("SPECTRA_BUILD_ID"),
323	0×	"mcp_protocol_versions": spectra_mcp::PROTOCOL_VERSIONS,
324	0×	"ledger_format": spectra_core::LEDGER_FORMAT,
325	0×	})
326	0×	);
327	0×	} else {
328	0×	println!("spectra {}", env!("SPECTRA_VERSION_LONG"));
329	0×	}
330	0×	Ok(0)
331	0×	}

Coverage / src/cli/mod.rs 68.5%

Keyboard