Project skeleton in Oxygen's shape: workspace, deps/oxygen pinned, make check, version, deps-check (#1) 258bb3824813

Author: Andy McCall @andymccall <[email protected]>
via: agent agent:claude@andymccall <[email protected]> · keyless, under your grant for changes,refs,seal · key 5b4beae3cba3
When: 2 days ago · 2026-11-02 21:38 UTC
Signature: ◈ sealed by agent:claude@andymccall
Hash: 258bb3824813c41f04088e68bc8c56d41fc18373f6b7a74f7567454ce0d0a1ee
Depends on: 8dc6df8c4d4e
Depended on by: 2d2dcb7a2778 1876f2ce71e4 862f0db224aa fe6b29c66cd4 87f601ccce6d 8d803d858c8c f4b3e9369e28 58e1ce30ae58 c7161ec1a607 b044d90930d9 f7986cb07b0e 8f87df88babf 98a0fb9f0948 813b6330f3ad aa72eb904932 01320eefd505 67bfa06a894f eca5af92279b 77df591d5a2f b576d05cf862 d17cbc7069ce 98a16830a3d3 da84e98f104e e071e91a14ef 8cfb9269bb14 39f5c913f617 eb675dfa5e18 037c45d8093c 571572f5fb2c 5eb57578f4ef 2fc88a7b3a5c 5d695d869fbf 09752034b5a8 36537112fcac 366e358ff5e7 ad258dc8cf5e
In bookmarks: main
In tags: v0.1.0
Edits: 27 atoms, 40 tree operations, 27 files

Browse the tree at this change

show whitespace changes

added .oxyattributes +2 −0

added .oxyignore +4 −0

added .oxymodules +3 −0

added CHANGELOG.md +5 −0

added Cargo.lock +1994 −0

added Cargo.toml +79 −0

added LICENSE +30 −0

added Makefile +38 −0

added build.rs +24 −0

added crates/radar/Cargo.toml +9 −0

added crates/radar/src/lib.rs +3 −0

added crates/spectra-api/Cargo.toml +10 −0

added crates/spectra-api/src/lib.rs +3 −0

added crates/spectra-core/Cargo.toml +13 −0

added crates/spectra-core/src/lib.rs +10 −0

added crates/spectra-mcp/Cargo.toml +10 −0

added crates/spectra-mcp/src/lib.rs +5 −0

added deps/oxygen +0 −0

No line changes.

added docs/plan.md +32 −0

added rustfmt.toml +2 −0

added scripts/changelog-check.sh +27 −0

added scripts/deps-check.sh +22 −0

added src/cli/format.rs +19 −0

added src/cli/json.rs +25 −0

added src/cli/mod.rs +55 −0

added src/cli/ui.rs +245 −0

added src/main.rs +28 −0

1	+	/target
2	+	*.tmp
3	+	/.claude
4	+	/data

1	+	[workspace]
2	+	members = ["crates/spectra-core", "crates/spectra-mcp", "crates/spectra-api", "crates/radar", "."]
3	+	# The pinned Oxygen (deps/oxygen) is a workspace of its own.
4	+	exclude = ["deps"]
5	+	resolver = "2"
6	+
7	+	[workspace.package]
8	+	version = "0.1.0"
9	+	edition = "2021"
10	+	license = "MIT OR Apache-2.0"
11	+
12	+	[workspace.dependencies]
13	+	# Identities, delegation, composite signatures, deterministic CBOR and
14	+	# hashing are Oxygen's: Spectra links them from the pinned subrepo and never
15	+	# reimplements them (spec §7.3, §9.5).
16	+	oxy-core = { path = "deps/oxygen/crates/oxy-core" }
17	+	spectra-core = { path = "crates/spectra-core" }
18	+	spectra-mcp = { path = "crates/spectra-mcp" }
19	+	spectra-api = { path = "crates/spectra-api" }
20	+	radar = { path = "crates/radar" }
21	+
22	+	# Versions as oxygenhub's workspace has them, so the vendored OxygenFlow
23	+	# image builds Spectra too (spectra#2; `make deps-check`).
24	+	anyhow = "1"
25	+	thiserror = "2"
26	+	serde = { version = "1", features = ["derive"] }
27	+	serde_json = "1"
28	+	tokio = { version = "1", features = ["rt-multi-thread", "macros", "net", "sync", "time", "signal", "fs", "process", "io-util"] }
29	+	axum = { version = "0.8", features = ["macros", "form", "query"] }
30	+	tower-http = { version = "0.6", features = ["trace", "set-header", "limit"] }
31	+	askama = "0.14"
32	+	sqlx = { version = "0.8", default-features = false, features = ["runtime-tokio", "sqlite", "migrate", "macros"] }
33	+	tracing = "0.1"
34	+	tracing-subscriber = { version = "0.3", features = ["env-filter"] }
35	+	clap = { version = "4", features = ["derive", "env"] }
36	+	toml = "0.8"
37	+	pulldown-cmark = { version = "0.13", default-features = false, features = ["html"] }
38	+	ammonia = "4"
39	+	hex = "0.4"
40	+	rand = "0.8"
41	+	subtle = "2"
42	+	blake3 = "1"
43	+	tempfile = "3"
44	+	schemars = "1"
45	+	futures = "0.3"
46	+	tokio-stream = { version = "0.1", features = ["sync"] }
47	+
48	+	[package]
49	+	name = "spectra"
50	+	version.workspace = true
51	+	edition.workspace = true
52	+	license.workspace = true
53	+	description = "Spectra: a control plane for AI coding agents"
54	+	default-run = "spectra"
55	+
56	+	[[bin]]
57	+	name = "spectra"
58	+	path = "src/main.rs"
59	+
60	+	[dependencies]
61	+	spectra-core.workspace = true
62	+	spectra-mcp.workspace = true
63	+	spectra-api.workspace = true
64	+	radar.workspace = true
65	+	oxy-core.workspace = true
66	+	anyhow.workspace = true
67	+	clap.workspace = true
68	+	serde_json.workspace = true
69	+	tokio.workspace = true
70	+	console = "0.15"
71	+	indicatif = "0.17"
72	+	libc = "0.2"
73	+	mimalloc = { version = "0.1", default-features = false }
74	+
75	+	[dev-dependencies]
76	+	tempfile.workspace = true
77	+
78	+	[profile.release]
79	+	debug = 1

1	+	Spectra (spectra, spectra-core, spectra-mcp, spectra-api and radar) is licensed under either of
2	+
3	+	* the MIT License (below), or
4	+	* the Apache License, Version 2.0 (https://www.apache.org/licenses/LICENSE-2.0)
5	+
6	+	at your option.
7	+
8	+	---
9	+
10	+	MIT License
11	+
12	+	Copyright (c) 2026 Andy McCall
13	+
14	+	Permission is hereby granted, free of charge, to any person obtaining a copy
15	+	of this software and associated documentation files (the "Software"), to deal
16	+	in the Software without restriction, including without limitation the rights
17	+	to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
18	+	copies of the Software, and to permit persons to whom the Software is
19	+	furnished to do so, subject to the following conditions:
20	+
21	+	The above copyright notice and this permission notice shall be included in all
22	+	copies or substantial portions of the Software.
23	+
24	+	THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
25	+	IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
26	+	FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
27	+	AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
28	+	LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
29	+	OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
30	+	SOFTWARE.

1	+	//! The build's identity, for `spectra --version`: `SPECTRA_BUILD` when a release or
2	+	//! an install sets it (from `oxy describe` in this checkout), else the heads a Flow job is
3	+	//! building, else "local build".
4	+	fn main() {
5	+	println!("cargo:rerun-if-env-changed=SPECTRA_BUILD");
6	+	// The heads name the build only when SPECTRA_BUILD does not: a CI job that
7	+	// sets it stays fresh from one state to the next (oxygenflow#52).
8	+	if !std::env::var("SPECTRA_BUILD").is_ok_and(\|b\| !b.trim().is_empty()) {
9	+	println!("cargo:rerun-if-env-changed=FLOW_HEADS");
10	+	}
11	+	let build = std::env::var("SPECTRA_BUILD")
12	+	.ok()
13	+	.map(\|b\| b.trim().to_string())
14	+	.filter(\|b\| !b.is_empty())
15	+	.or_else(\|\| {
16	+	std::env::var("FLOW_HEADS")
17	+	.ok()
18	+	.and_then(\|h\| h.split('+').next().map(\|x\| format!("flow #{}", &x[..12.min(x.len())])))
19	+	.filter(\|b\| b.len() > "flow #".len())
20	+	})
21	+	.unwrap_or_else(\|\| "local build".into());
22	+	println!("cargo:rustc-env=SPECTRA_BUILD_ID={build}");
23	+	println!("cargo:rustc-env=SPECTRA_VERSION_LONG={} ({build})", std::env::var("CARGO_PKG_VERSION").unwrap());
24	+	}

1	+	[package]
2	+	name = "radar"
3	+	version.workspace = true
4	+	edition.workspace = true
5	+	license.workspace = true
6	+	description = "Radar: Spectra's web interface for the human"
7	+
8	+	[dependencies]
9	+	spectra-core.workspace = true

	1	+	# oxygen#145: two changes adding changelog entries keep both.
	2	+	CHANGELOG.md merge=union

1	+	[deps/oxygen]
2	+	url = https://oxygenhub.io/andymccall/oxygen
3	+

1	+	# Changelog
2	+
3	+	## Unreleased
4	+
5	+	- Added: the project skeleton (#1). A Cargo workspace in Oxygen's shape (`spectra-core`, `spectra-mcp`, `spectra-api`, `radar` and the `spectra` binary), Oxygen pinned under `deps/oxygen` for identities and signatures, `make check`, the changelog check, `spectra version [--json]` with the build identity, and `scripts/deps-check.sh` to keep Spectra buildable by the vendored OxygenFlow image.

1	+	.PHONY: build check test fmt clippy changelog run ts install deps-check
2	+
3	+	build:
4	+	cargo build --release
5	+
6	+	check: changelog fmt clippy test
7	+
8	+	# A code change needs a CHANGELOG.md line (scripts/changelog-check.sh).
9	+	changelog:
10	+	scripts/changelog-check.sh
11	+
12	+	fmt:
13	+	cargo fmt -p spectra -p spectra-core -p spectra-mcp -p spectra-api -p radar -- --check
14	+
15	+	clippy:
16	+	cargo clippy --workspace --all-targets -- -D warnings
17	+
18	+	test:
19	+	cargo test --workspace
20	+
21	+	run:
22	+	cargo run -- --data data serve
23	+
24	+	# TypeScript declarations of the API types, for the VS Code extensions.
25	+	ts:
26	+	cargo run -q -p spectra-api --bin spectra-api-typescript > crates/spectra-api/ts/index.d.ts
27	+
28	+	# Build and install spectra with its build identity (oxy describe) in --version.
29	+	install:
30	+	SPECTRA_BUILD="$$(oxy --plain describe 2>/dev/null)" CARGO_INCREMENTAL=0 cargo build --release
31	+	ln -sf $${CARGO_TARGET_DIR:-$(CURDIR)/target}/release/spectra $(HOME)/.local/bin/spectra
32	+	$(HOME)/.local/bin/spectra --version
33	+
34	+	# Every crate in Cargo.lock must be one the OxygenFlow build image vendors
35	+	# (oxygenflow images/rust: the crates of oxygen, oxygenhub and oxygenflow), or
36	+	# CI cannot build offline (spectra#2).
37	+	deps-check:
38	+	scripts/deps-check.sh

1	+	//! Radar (spec §17): the human's pages, rendered with askama, live over the
2	+	//! event stream, working without JavaScript. Linked by `spectra` and, later,
3	+	//! mounted by SpectraHub.

1	+	[package]
2	+	name = "spectra-api"
3	+	version.workspace = true
4	+	edition.workspace = true
5	+	license.workspace = true
6	+	description = "Spectra's JSON API types, shared with SpectraHub and the extensions"
7	+
8	+	[dependencies]
9	+	serde.workspace = true
10	+	serde_json.workspace = true

1	+	//! The JSON API's types (spec §18), with serde and JSON Schema derives, as
2	+	//! `hub-api` is for OxygenHub. `make ts` writes `ts/index.d.ts` from them for
3	+	//! spectra-vscode and spectrahub-vscode.

1	+	[package]
2	+	name = "spectra-core"
3	+	version.workspace = true
4	+	edition.workspace = true
5	+	license.workspace = true
6	+	description = "Spectra's model: the ledger, projections, principals and the bus"
7	+
8	+	[dependencies]
9	+	oxy-core.workspace = true
10	+	anyhow.workspace = true
11	+	thiserror.workspace = true
12	+	serde.workspace = true
13	+	serde_json.workspace = true

1	+	//! Spectra's model (spec §7.3): the ledger and its projections, principals
2	+	//! and their identities, the bus, rules and search. No HTTP, no CLI: those
3	+	//! are `spectra-mcp`, `radar` and the `spectra` binary, all built on this.
4	+	//!
5	+	//! Identities, delegation, composite signatures, deterministic CBOR and
6	+	//! hashing come from `oxy-core`; nothing here reimplements them.
7	+
8	+	/// The ledger's format version: the frozen event envelope (spec §9.1). A
9	+	/// database written with a newer format is refused, never guessed at.
10	+	pub const LEDGER_FORMAT: u32 = 1;

1	+	[package]
2	+	name = "spectra-mcp"
3	+	version.workspace = true
4	+	edition.workspace = true
5	+	license.workspace = true
6	+	description = "Tuner: Spectra's MCP server over Streamable HTTP and the stdio shim"
7	+
8	+	[dependencies]
9	+	spectra-core.workspace = true
10	+	serde_json.workspace = true

1	+	# This file is automatically @generated by Cargo.
2	+	# It is not intended for manual editing.
3	+	version = 4
4	+
5	+	[[package]]
6	+	name = "adler2"
7	+	version = "2.0.1"
8	+	source = "registry+https://github.com/rust-lang/crates.io-index"
9	+	checksum = "320119579fcad9c21884f5c4861d16174d0e06250625266f50fe6898340abefa"
10	+
11	+	[[package]]
12	+	name = "aho-corasick"
13	+	version = "1.1.5"
14	+	source = "registry+https://github.com/rust-lang/crates.io-index"
15	+	checksum = "c982642fa9e8606056828ee9a8505737230110bb1099153c79efe865c59d12ba"
16	+	dependencies = [
17	+	"memchr",
18	+	]
19	+
20	+	[[package]]
21	+	name = "anstream"
22	+	version = "1.0.0"
23	+	source = "registry+https://github.com/rust-lang/crates.io-index"
24	+	checksum = "824a212faf96e9acacdbd09febd34438f8f711fb84e09a8916013cd7815ca28d"
25	+	dependencies = [
26	+	"anstyle",
27	+	"anstyle-parse",
28	+	"anstyle-query",
29	+	"anstyle-wincon",
30	+	"colorchoice",
31	+	"is_terminal_polyfill",
32	+	"utf8parse",
33	+	]
34	+
35	+	[[package]]
36	+	name = "anstyle"
37	+	version = "1.0.14"
38	+	source = "registry+https://github.com/rust-lang/crates.io-index"
39	+	checksum = "940b3a0ca603d1eade50a4846a2afffd5ef57a9feac2c0e2ec2e14f9ead76000"
40	+

1	+	//! Tuner (spec §15): the MCP endpoint, its tools, resources and prompts, and
2	+	//! the stdio shim that signs an agent's requests and forwards them.
3	+
4	+	/// The MCP revisions Tuner speaks, newest first (spec §15.1).
5	+	pub const PROTOCOL_VERSIONS: &[&str] = &["2026-07-28", "2025-11-25", "2025-06-18", "2025-03-26"];

1	+	# Sprint 1 plan: Spectra 0.1, Talk
2	+
3	+	Each loop iteration: pick the first unchecked item, implement it with tests, run the gated checks, commit with `oxy`, tick the box here with a one-line note, and commit again. Update `docs/spec.md` (and its changelog) whenever behaviour the spec describes changes. If an item cannot be finished in two iterations, note why under it and move on. The issues are on https://oxygenhub.io/projects/andymccall/7.
4	+
5	+	## Rules
6	+
7	+	- Never run `git init` in this directory or push this project anywhere but its `oxygenhub` remote. Commit with `OXY_HOME=~/.oxy-agents/claude oxy commit -m "..." PATHS..`, never with Andy's own key.
8	+	- Tests are hermetic: a temporary data directory, a temporary socket, port 0; never `~/.local/share/spectra`, `~/.config` or the network.
9	+	- Gate every commit on `make check` (changelog, fmt, clippy with warnings as errors, tests).
10	+	- Every code change adds a CHANGELOG.md line under `## Unreleased`, or sets `NO_CHANGELOG=1`.
11	+	- Never weaken a security goal of spec §5 to make a test pass.
12	+	- Never act as Andy: owner-only steps (delegating to an agent key, the acceptance run) wait for him.
13	+
14	+	## Items
15	+
16	+	- [ ] #1 Project skeleton in Oxygen's shape
17	+	- [ ] #2 CI on OxygenFlow
18	+	- [ ] #3 The ledger
19	+	- [ ] #4 Identities instead of tokens
20	+	- [ ] #5 Projects, presence and sessions
21	+	- [ ] #6 Channels, threads, messages, inbox and search
22	+	- [ ] #7 Tuner: MCP over Streamable HTTP
23	+	- [ ] #8 The 0.1 tools
24	+	- [ ] #9 The stdio shim
25	+	- [ ] #10 Radar
26	+	- [ ] #11 JSON API and spectra-api types
27	+	- [ ] #12 Human CLI
28	+	- [ ] #13 Acceptance (with Andy)
29	+
30	+	## Log
31	+
32	+	- 2026-11-02 plan created; sprint adjusted to spec Draft 0.3 (identities and the ledger).

	1	+	max_width = 140
	2	+	use_small_heuristics = "Max"

1	+	#!/bin/sh
2	+	# The changelog check (2026-10-19): a commit that changes what users get
3	+	# adds a line under "## Unreleased" in CHANGELOG.md, so a release's notes
4	+	# are written as the work is done and versions say what changed.
5	+	#
6	+	# scripts/changelog-check.sh [PATH...]
7	+	#
8	+	# PATHs are what the commit will take (as given to `oxy commit`); without
9	+	# any, the working copy's changes. Code is anything under src/, crates/,
10	+	# templates/, assets/, packaging/, images/ or scripts/, except tests.
11	+	# Docs, pipelines, pins (deps/) and lock files need no line. For a code
12	+	# change users won't notice (a refactor, a test helper), set NO_CHANGELOG=1.
13	+	set -eu
14	+	[ "${NO_CHANGELOG:-}" = 1 ] && exit 0
15	+	cd "$(dirname "$0")/.."
16	+	if [ "$#" -gt 0 ]; then
17	+	paths=$(printf '%s\n' "$@")
18	+	else
19	+	paths=$(oxy --plain status --json \| python3 -c 'import json,sys; print("\n".join(p["path"] for p in json.load(sys.stdin)["paths"]))')
20	+	fi
21	+	code=$(printf '%s\n' "$paths" \| grep -E '^(src\|crates\|templates\|assets\|packaging\|images\|scripts)/' \| grep -vE '(^\|/)tests?/\|_test\.rs$' \|\| true)
22	+	[ -z "$code" ] && exit 0
23	+	printf '%s\n' "$paths" \| grep -qx 'CHANGELOG.md' && exit 0
24	+	echo "changelog: these changes touch code but CHANGELOG.md has no new line under ## Unreleased:" >&2
25	+	printf '%s\n' "$code" \| sed 's/^/ /' >&2
26	+	echo "add one (Added / Changed / Fixed / Security, with the issue number), or set NO_CHANGELOG=1 if users won't notice" >&2
27	+	exit 1

1	+	#!/bin/sh
2	+	# Every package in Spectra's Cargo.lock must be in one of the lockfiles the
3	+	# OxygenFlow build image vendors (oxygen, oxygenhub, oxygenflow), at the same
4	+	# version, or Flow jobs, which have no network, fail with "no matching
5	+	# package" (spectra#2). The other projects are found beside this one, or
6	+	# under DEV (default: ..).
7	+	#
8	+	# scripts/deps-check.sh
9	+	set -eu
10	+	cd "$(dirname "$0")/.."
11	+	dev=${DEV:-..}
12	+	pkgs() { awk '/^\[\[package\]\]/{n="";v="";s=0} /^name = /{n=$3} /^version = /{v=$3} /^source = /{s=1; print n" "v}' "$@" \| tr -d '"' \| sort -u; }
13	+	have=$(pkgs "$dev/oxygen/Cargo.lock" "$dev/oxygenhub/Cargo.lock" "$dev/oxygenflow/Cargo.lock")
14	+	need=$(pkgs Cargo.lock)
15	+	missing=$(printf '%s\n' "$need" \| grep -vxF "$have" \|\| true)
16	+	if [ -n "$missing" ]; then
17	+	echo "deps-check: these crates are not in the OxygenFlow image's vendored set:" >&2
18	+	printf '%s\n' "$missing" \| sed 's/^/ /' >&2
19	+	echo "pin a version the image has (cargo update -p NAME --precise V), or rebuild the image with Spectra's workspace" >&2
20	+	exit 1
21	+	fi
22	+	echo "deps-check: all $(printf '%s\n' "$need" \| wc -l) crates are vendored in the image"

1	+	//! Times as `oxy` prints them: UTC, `YYYY-MM-DD HH:MM:SSZ`.
2	+
3	+	pub fn when(ms: u64) -> String {
4	+	let secs = (ms / 1000) as i64;
5	+	let days = secs.div_euclid(86_400);
6	+	let rem = secs.rem_euclid(86_400);
7	+	// Civil-from-days (Howard Hinnant), UTC.
8	+	let z = days + 719_468;
9	+	let era = z.div_euclid(146_097);
10	+	let doe = z - era * 146_097;
11	+	let yoe = (doe - doe / 1460 + doe / 36_524 - doe / 146_096) / 365;
12	+	let y = yoe + era * 400;
13	+	let doy = doe - (365 * yoe + yoe / 4 - yoe / 100);
14	+	let mp = (5 * doy + 2) / 153;
15	+	let d = doy - (153 * mp + 2) / 5 + 1;
16	+	let m = if mp < 10 { mp + 3 } else { mp - 9 };
17	+	let y = if m <= 2 { y + 1 } else { y };
18	+	format!("{y:04}-{m:02}-{d:02} {:02}:{:02}:{:02}Z", rem / 3600, (rem % 3600) / 60, rem % 60)
19	+	}

1	+	#![allow(dead_code)] // Shared with oxy: not every helper is used yet.
2	+	//! Tiny JSON building for `--json` outputs: one document on stdout,
3	+	//! nothing else, with string escaping shared with the hooks payloads.
4	+
5	+	pub use oxy_core::repo::{json_array as arr, json_str as s};
6	+
7	+	pub fn obj<I: IntoIterator<Item = (&'static str, String)>>(pairs: I) -> String {
8	+	let inner: Vec<String> = pairs.into_iter().map(\|(k, v)\| format!("{}:{v}", s(k))).collect();
9	+	format!("{{{}}}", inner.join(","))
10	+	}
11	+	pub fn b(v: bool) -> String {
12	+	v.to_string()
13	+	}
14	+	pub fn n<T: std::fmt::Display>(v: T) -> String {
15	+	v.to_string()
16	+	}
17	+	pub fn opt<T>(v: Option<T>, f: impl Fn(T) -> String) -> String {
18	+	match v {
19	+	Some(x) => f(x),
20	+	None => "null".into(),
21	+	}
22	+	}
23	+	pub fn hashes(v: &[oxy_core::hash::ChangeHash]) -> String {
24	+	arr(v.iter().map(\|h\| s(&h.to_hex())))
25	+	}

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 format;
6	+	pub mod json;
7	+	pub mod ui;
8	+
9	+	use anyhow::Result;
10	+	use clap::{Parser, Subcommand};
11	+
12	+	#[derive(Parser)]
13	+	#[command(name = "spectra", version = env!("SPECTRA_VERSION_LONG"), about = "A control plane for AI coding agents")]
14	+	pub struct Cli {
15	+	/// Plain output: no colour or glyphs (also NO_COLOR, or when not a terminal)
16	+	#[arg(long, global = true)]
17	+	pub plain: bool,
18	+	#[command(subcommand)]
19	+	pub command: Command,
20	+	}
21	+
22	+	#[derive(Subcommand)]
23	+	pub enum Command {
24	+	/// The version and build of this binary
25	+	Version {
26	+	/// Machine-readable output
27	+	#[arg(long)]
28	+	json: bool,
29	+	},
30	+	}
31	+
32	+	pub fn run() -> Result<i32> {
33	+	let cli = Cli::parse();
34	+	ui::init(cli.plain);
35	+	match cli.command {
36	+	Command::Version { json } => version(json),
37	+	}
38	+	}
39	+
40	+	fn version(as_json: bool) -> Result<i32> {
41	+	if as_json {
42	+	println!(
43	+	"{}",
44	+	serde_json::json!({
45	+	"version": env!("CARGO_PKG_VERSION"),
46	+	"build": env!("SPECTRA_BUILD_ID"),
47	+	"mcp_protocol_versions": spectra_mcp::PROTOCOL_VERSIONS,
48	+	"ledger_format": spectra_core::LEDGER_FORMAT,
49	+	})
50	+	);
51	+	} else {
52	+	println!("spectra {}", env!("SPECTRA_VERSION_LONG"));
53	+	}
54	+	Ok(0)
55	+	}

1	+	#![allow(dead_code)] // Shared with oxy: not every helper is used yet.
2	+	//! Terminal presentation: colour, emphasis, and a live spinner while a
3	+	//! command works. Everything degrades to plain text when stdout is not a
4	+	//! terminal, when `NO_COLOR` is set, or with `--plain`.
5	+
6	+	use console::{style, StyledObject, Term};
7	+	use indicatif::{ProgressBar, ProgressStyle};
8	+	use std::sync::atomic::{AtomicBool, Ordering};
9	+	use std::time::Duration;
10	+
11	+	static PLAIN: AtomicBool = AtomicBool::new(false);
12	+	static UNICODE: AtomicBool = AtomicBool::new(false);
13	+	static INIT: std::sync::Once = std::sync::Once::new();
14	+
15	+	/// Decide once whether to use colour, glyphs, and animation.
16	+	pub fn init(plain_flag: bool) {
17	+	INIT.call_once(\|\| {
18	+	let no_color = std::env::var_os("NO_COLOR").is_some();
19	+	let tty = Term::stdout().features().is_attended();
20	+	let plain = plain_flag \|\| no_color \|\| !tty;
21	+	PLAIN.store(plain, Ordering::Relaxed);
22	+	console::set_colors_enabled(!plain);
23	+	let utf8 = ["LC_ALL", "LC_CTYPE", "LANG"]
24	+	.iter()
25	+	.filter_map(\|k\| std::env::var(k).ok())
26	+	.find(\|v\| !v.is_empty())
27	+	.map(\|v\| v.to_ascii_uppercase().contains("UTF-8") \|\| v.to_ascii_uppercase().contains("UTF8"))
28	+	.unwrap_or(false);
29	+	UNICODE.store(!plain && utf8, Ordering::Relaxed);
30	+	});
31	+	}
32	+
33	+	pub fn plain() -> bool {
34	+	PLAIN.load(Ordering::Relaxed)
35	+	}
36	+
37	+	/// Whether the terminal takes Unicode glyphs (a UTF-8 locale, not `--plain`).
38	+	pub fn unicode() -> bool {
39	+	UNICODE.load(Ordering::Relaxed)
40	+	}
41	+
42	+	/// A glyph with an ASCII fallback for plain output and non-UTF-8 locales.
43	+	pub fn glyph<'a>(fancy: &'a str, ascii: &'a str) -> &'a str {
44	+	if unicode() {
45	+	fancy
46	+	} else {
47	+	ascii
48	+	}
49	+	}
50	+
51	+	/// A finished action: a tick and the verb in green.
52	+	pub fn done<T: std::fmt::Display>(v: T) -> String {
53	+	format!("{} {}", ok(glyph("✔", "*")), ok(v))
54	+	}
55	+
56	+	/// A warning line prefix.
57	+	pub fn caution() -> String {
58	+	warn(glyph("⚠", "!"))
59	+	}
60	+
61	+	/// An informational note prefix.
62	+	pub fn note() -> String {
63	+	dim(glyph("›", ">"))
64	+	}
65	+
66	+	/// A section title.
67	+	pub fn section<T: std::fmt::Display>(v: T) -> String {
68	+	format!("{} {}", s(glyph("▍", "#")).cyan(), s(v).bold())
69	+	}
70	+
71	+	/// ` key value`, with the key dimmed and padded.
72	+	pub fn kv<T: std::fmt::Display>(key: &str, value: T) -> String {
73	+	format!(" {} {value}", dim(format!("{key:<8}")))
74	+	}
75	+
76	+	/// An author name.
77	+	pub fn author<T: std::fmt::Display>(v: T) -> String {
78	+	s(v).magenta().to_string()
79	+	}
80	+
81	+	/// A bookmark or reference name.
82	+	pub fn bookmark<T: std::fmt::Display>(v: T) -> String {
83	+	s(v).green().bold().to_string()
84	+	}
85	+
86	+	/// The subject line of a message.
87	+	pub fn subject<T: std::fmt::Display>(v: T) -> String {
88	+	s(v).bold().to_string()
89	+	}
90	+
91	+	/// A dimmed separator between the parts of a metadata line.
92	+	pub fn sep() -> String {
93	+	dim(format!(" {} ", glyph("·", "-")))
94	+	}
95	+
96	+	/// Milliseconds since the epoch as a relative time ("3 minutes ago"), or the
97	+	/// date when older than a month.
98	+	pub fn ago(ms: u64) -> String {
99	+	let now = std::time::SystemTime::now().duration_since(std::time::UNIX_EPOCH).map(\|d\| d.as_millis() as u64).unwrap_or(0);
100	+	let secs = now.saturating_sub(ms) / 1000;
101	+	let unit = \|n: u64, w: &str\| format!("{n} {w}{} ago", if n == 1 { "" } else { "s" });
102	+	match secs {
103	+	0..=44 => "just now".into(),
104	+	45..=89 => "a minute ago".into(),
105	+	90..=2_699 => unit(secs.div_ceil(60), "minute"),
106	+	2_700..=5_399 => "an hour ago".into(),
107	+	5_400..=79_199 => unit(secs.div_ceil(3_600), "hour"),
108	+	79_200..=129_599 => "yesterday".into(),
109	+	129_600..=2_591_999 => unit(secs.div_ceil(86_400), "day"),
110	+	_ => super::format::when(ms).split(' ').next().unwrap_or("").to_string(),
111	+	}
112	+	}
113	+
114	+	/// The bullet for a log entry: the working copy, a head, or an ordinary change.
115	+	pub fn log_bullet(working_copy: bool, head: bool, conflicted: bool) -> String {
116	+	if working_copy {
117	+	s(glyph("◉", "@")).cyan().bold().to_string()
118	+	} else if conflicted {
119	+	err(glyph("✱", "!"))
120	+	} else if head {
121	+	ok(glyph("●", "*"))
122	+	} else {
123	+	dim(glyph("○", "o"))
124	+	}
125	+	}
126	+
127	+	/// A status glyph and word for a working-copy change.
128	+	pub fn status_mark(tag: &str) -> String {
129	+	let (g, a, word) = match tag {
130	+	"A" => ("✚", "+", "added"),
131	+	"M" => ("✎", "~", "modified"),
132	+	"D" => ("✖", "-", "removed"),
133	+	"X" => ("⚙", "x", "mode"),
134	+	"C!" => ("‼", "!", "markers"),
135	+	"R" => ("➜", ">", "renamed"),
136	+	"V" => ("✔", "r", "resolved"),
137	+	_ => ("?", "?", "unknown"),
138	+	};
139	+	let text = format!("{} {word:<9}", glyph(g, a));
140	+	self::tag_style(tag, &text)
141	+	}
142	+
143	+	fn tag_style(t: &str, text: &str) -> String {
144	+	match t {
145	+	"A" \| "V" => s(text).green().to_string(),
146	+	"R" => s(text).cyan().to_string(),
147	+	"M" \| "X" => s(text).yellow().to_string(),
148	+	"D" \| "C!" => s(text).red().to_string(),
149	+	_ => text.to_string(),
150	+	}
151	+	}
152	+
153	+	fn s<T: std::fmt::Display>(v: T) -> StyledObject<T> {
154	+	style(v)
155	+	}
156	+
157	+	/// A ChangeId prefix.
158	+	pub fn id<T: std::fmt::Display>(v: T) -> String {
159	+	s(v).cyan().bold().to_string()
160	+	}
161	+	/// A hash prefix.
162	+	pub fn hash<T: std::fmt::Display>(v: T) -> String {
163	+	s(v).dim().to_string()
164	+	}
165	+	pub fn path<T: std::fmt::Display>(v: T) -> String {
166	+	s(v).bold().to_string()
167	+	}
168	+	pub fn ok<T: std::fmt::Display>(v: T) -> String {
169	+	s(v).green().to_string()
170	+	}
171	+	pub fn warn<T: std::fmt::Display>(v: T) -> String {
172	+	s(v).yellow().to_string()
173	+	}
174	+	pub fn err<T: std::fmt::Display>(v: T) -> String {
175	+	s(v).red().bold().to_string()
176	+	}
177	+	pub fn dim<T: std::fmt::Display>(v: T) -> String {
178	+	s(v).dim().to_string()
179	+	}
180	+	pub fn heading<T: std::fmt::Display>(v: T) -> String {
181	+	s(v).bold().underlined().to_string()
182	+	}
183	+	/// A live spinner with a message, shown only on a terminal. Drop or call
184	+	/// `done` to clear it; `done` prints the final line in its place.
185	+	pub struct Spinner {
186	+	bar: Option<ProgressBar>,
187	+	}
188	+
189	+	pub fn spinner(msg: &str) -> Spinner {
190	+	if plain() {
191	+	return Spinner { bar: None };
192	+	}
193	+	let bar = ProgressBar::new_spinner();
194	+	bar.set_style(
195	+	ProgressStyle::with_template("{spinner:.cyan} {msg}")
196	+	.unwrap()
197	+	.tick_strings(&["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏", " "]),
198	+	);
199	+	bar.set_message(msg.to_string());
200	+	bar.enable_steady_tick(Duration::from_millis(80));
201	+	Spinner { bar: Some(bar) }
202	+	}
203	+
204	+	impl Spinner {
205	+	/// Replace the spinner with a final line (or print it plainly). The
206	+	/// line is printed as given: callers start it with their own mark.
207	+	pub fn done(self, msg: &str) {
208	+	if let Some(b) = &self.bar {
209	+	b.finish_and_clear();
210	+	}
211	+	println!("{msg}");
212	+	}
213	+	/// Say what is happening now: the spinner's message, or, with no
214	+	/// terminal, a line on stderr, so a long command is never silent.
215	+	pub fn set(&self, msg: &str) {
216	+	match &self.bar {
217	+	Some(b) => b.set_message(msg.to_string()),
218	+	None => eprintln!("{} {msg}", dim(glyph("›", ">"))),
219	+	}
220	+	}
221	+	/// Clear the spinner without printing.
222	+	pub fn clear(self) {
223	+	if let Some(b) = &self.bar {
224	+	b.finish_and_clear();
225	+	}
226	+	}
227	+	}
228	+
229	+	#[cfg(test)]
230	+	mod tests {
231	+	use super::*;
232	+
233	+	#[test]
234	+	fn relative_times() {
235	+	let now = std::time::SystemTime::now().duration_since(std::time::UNIX_EPOCH).unwrap().as_millis() as u64;
236	+	assert_eq!(ago(now), "just now");
237	+	assert_eq!(ago(now - 60_000), "a minute ago");
238	+	assert_eq!(ago(now - 5 * 60_000), "5 minutes ago");
239	+	assert_eq!(ago(now - 3 * 3_600_000), "3 hours ago");
240	+	assert_eq!(ago(now - 25 * 3_600_000), "yesterday");
241	+	assert_eq!(ago(now - 4 * 86_400_000), "4 days ago");
242	+	assert_eq!(ago(0), "1970-01-01");
243	+	assert_eq!(glyph("✔", ""), if unicode() { "✔" } else { "" });
244	+	}
245	+	}

1	+	//! `spectra`: the control plane for AI coding agents.
2	+	//!
3	+	//! Command definitions and dispatch live in `cli`; each command group has
4	+	//! its own module there, as in `oxy`.
5	+
6	+	mod cli;
7	+
8	+	// Many small allocations from every thread (events, JSON, templates): mimalloc
9	+	// serves them from per-thread pages without the arena locks of glibc's.
10	+	#[global_allocator]
11	+	static ALLOC: mimalloc::MiMalloc = mimalloc::MiMalloc;
12	+
13	+	fn main() {
14	+	// Behave like other CLI tools when output is piped into `head`: die
15	+	// quietly on SIGPIPE instead of panicking on a failed write.
16	+	#[cfg(unix)]
17	+	unsafe {
18	+	libc::signal(libc::SIGPIPE, libc::SIG_DFL);
19	+	}
20	+	match cli::run() {
21	+	Ok(code) => std::process::exit(code),
22	+	Err(e) => {
23	+	cli::ui::init(false);
24	+	eprintln!("{} {e:#}", cli::ui::err("error:"));
25	+	std::process::exit(1);
26	+	}
27	+	}
28	+	}

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

Project skeleton in Oxygen's shape: workspace, deps/oxygen pinned, make check, version, deps-check (#1) 258bb3824813

Keyboard