mirror of
https://github.com/ModernRelay/omnigraph.git
synced 2026-06-12 01:45:14 +02:00
feat(cli): the operator config surface — identity and output defaults (RFC-007 PR 1)
~/.omnigraph/config.yaml joins the resolution chains as the operator surface: operator.actor becomes the last hop of THE actor chain (--as > legacy cli.actor during the RFC-008 window > operator.actor > none, one implementation for direct-engine and cluster commands alike) and defaults.output joins the read-format cascade below every more-specific source. Discovery honors $OMNIGRAPH_HOME (tilde-expanded, #139 finding 9); an absent file is an empty layer; unknown keys WARN and load (a file written for later slices must not break this CLI); malformed YAML is a loud error. The module is CLI-only — the server never reads operator config (invariant 11 by construction). $OMNIGRAPH_CONFIG becomes a first-class stand-in for --config in load_config (flag > env > ./omnigraph.yaml), one meaning in both binaries. The test harness pins hermeticity: spawned binaries get a nonexistent OMNIGRAPH_HOME by default so no test ever reads the developer's real operator config. New coverage: loader unit tests, the env-precedence matrix on load_config_in, and spawned-binary e2es for the actor chain (operator wins with no flag/legacy key; legacy outranks it; --as wins) and the format cascade. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
aaltshuler
parent
08ce8dc34d
commit
be4bd46212
7 changed files with 445 additions and 36 deletions
|
|
@ -3,6 +3,7 @@
|
|||
//! main.rs in the modularization).
|
||||
|
||||
use super::*;
|
||||
use crate::operator;
|
||||
|
||||
pub(crate) fn ensure_local_graph_parent(uri: &str) -> Result<()> {
|
||||
if !uri.contains("://") {
|
||||
|
|
@ -167,18 +168,40 @@ pub(crate) async fn open_local_db_with_policy(graph: &ResolvedCliGraph) -> Resul
|
|||
}
|
||||
}
|
||||
|
||||
/// THE actor chain (RFC-007 §D3) — every command that needs an identity
|
||||
/// resolves through this one function (one path per concern):
|
||||
/// `--as` > legacy `cli.actor` in omnigraph.yaml (RFC-008 window) >
|
||||
/// `operator.actor` in ~/.omnigraph/config.yaml > none.
|
||||
pub(crate) fn resolve_actor(
|
||||
cli_as: Option<&str>,
|
||||
legacy_config_actor: Option<&str>,
|
||||
) -> Result<Option<String>> {
|
||||
if let Some(actor) = cli_as {
|
||||
return Ok(Some(actor.to_string()));
|
||||
}
|
||||
if let Some(actor) = legacy_config_actor {
|
||||
return Ok(Some(actor.to_string()));
|
||||
}
|
||||
Ok(operator::load_operator_config()?
|
||||
.actor()
|
||||
.map(str::to_string))
|
||||
}
|
||||
|
||||
pub(crate) fn resolve_cluster_actor(cli_as: Option<&str>) -> Result<Option<String>> {
|
||||
if let Some(actor) = cli_as {
|
||||
return Ok(Some(actor.to_string()));
|
||||
}
|
||||
let config = load_config(None).wrap_err(
|
||||
"resolving the default actor from the per-operator omnigraph.yaml (pass --as <ACTOR> to skip this lookup)",
|
||||
"resolving the default actor from omnigraph.yaml (pass --as <ACTOR> to skip this lookup)",
|
||||
)?;
|
||||
Ok(config.cli.actor.clone())
|
||||
resolve_actor(None, config.cli.actor.as_deref())
|
||||
}
|
||||
|
||||
pub(crate) fn resolve_cli_actor<'a>(cli_as: Option<&'a str>, config: &'a OmnigraphConfig) -> Option<&'a str> {
|
||||
cli_as.or(config.cli.actor.as_deref())
|
||||
pub(crate) fn resolve_cli_actor(
|
||||
cli_as: Option<&str>,
|
||||
config: &OmnigraphConfig,
|
||||
) -> Result<Option<String>> {
|
||||
resolve_actor(cli_as, config.cli.actor.as_deref())
|
||||
}
|
||||
|
||||
pub(crate) fn resolve_policy_tests_path(context: &ResolvedPolicyContext) -> PathBuf {
|
||||
|
|
@ -460,6 +483,9 @@ pub(crate) fn merged_params_json(
|
|||
}
|
||||
}
|
||||
|
||||
/// The format cascade (RFC-007 §D3): `--json` > `--format` > alias format >
|
||||
/// legacy `cli.output_format` (RFC-008 window) > operator `defaults.output`
|
||||
/// > table.
|
||||
pub(crate) fn resolve_read_format(
|
||||
config: &OmnigraphConfig,
|
||||
cli_format: Option<ReadOutputFormat>,
|
||||
|
|
@ -467,12 +493,17 @@ pub(crate) fn resolve_read_format(
|
|||
alias_format: Option<ReadOutputFormat>,
|
||||
) -> ReadOutputFormat {
|
||||
if json {
|
||||
ReadOutputFormat::Json
|
||||
} else {
|
||||
cli_format
|
||||
.or(alias_format)
|
||||
.unwrap_or_else(|| config.cli_output_format())
|
||||
return ReadOutputFormat::Json;
|
||||
}
|
||||
cli_format
|
||||
.or(alias_format)
|
||||
.or(config.cli.output_format)
|
||||
.or_else(|| {
|
||||
operator::load_operator_config()
|
||||
.ok()
|
||||
.and_then(|operator| operator.output())
|
||||
})
|
||||
.unwrap_or_default()
|
||||
}
|
||||
|
||||
pub(crate) fn resolve_alias<'a>(
|
||||
|
|
@ -935,7 +966,8 @@ pub(crate) async fn execute_change(
|
|||
let (selected_name, query_params) = select_named_query(query_source, query_name)?;
|
||||
let params = query_params_from_json(&query_params, params_json)?;
|
||||
let db = open_local_db_with_policy(graph).await?;
|
||||
let actor = resolve_cli_actor(cli_as_actor, config);
|
||||
let actor = resolve_cli_actor(cli_as_actor, config)?;
|
||||
let actor = actor.as_deref();
|
||||
let result = db
|
||||
.mutate_as(branch, query_source, &selected_name, ¶ms, actor)
|
||||
.await?;
|
||||
|
|
|
|||
|
|
@ -42,6 +42,7 @@ use serde::de::DeserializeOwned;
|
|||
use serde_json::Value;
|
||||
|
||||
mod embed;
|
||||
mod operator;
|
||||
mod read_format;
|
||||
|
||||
use embed::{EmbedArgs, EmbedOutput, execute_embed};
|
||||
|
|
@ -129,7 +130,8 @@ async fn main() -> Result<()> {
|
|||
load_output_from_tables(&uri, &branch, mode, &output)
|
||||
} else {
|
||||
let db = open_local_db_with_policy(&graph).await?;
|
||||
let actor = resolve_cli_actor(cli.as_actor.as_deref(), &config);
|
||||
let actor = resolve_cli_actor(cli.as_actor.as_deref(), &config)?;
|
||||
let actor = actor.as_deref();
|
||||
let result = db
|
||||
.load_file_as(
|
||||
&branch,
|
||||
|
|
@ -196,7 +198,8 @@ async fn main() -> Result<()> {
|
|||
.await?
|
||||
} else {
|
||||
let db = open_local_db_with_policy(&graph).await?;
|
||||
let actor = resolve_cli_actor(cli.as_actor.as_deref(), &config);
|
||||
let actor = resolve_cli_actor(cli.as_actor.as_deref(), &config)?;
|
||||
let actor = actor.as_deref();
|
||||
let result = db
|
||||
.load_file_as(
|
||||
&branch,
|
||||
|
|
@ -243,7 +246,8 @@ async fn main() -> Result<()> {
|
|||
.await?
|
||||
} else {
|
||||
let db = open_local_db_with_policy(&graph).await?;
|
||||
let actor = resolve_cli_actor(cli.as_actor.as_deref(), &config);
|
||||
let actor = resolve_cli_actor(cli.as_actor.as_deref(), &config)?;
|
||||
let actor = actor.as_deref();
|
||||
db.branch_create_from_as(ReadTarget::branch(&from), &name, actor)
|
||||
.await?;
|
||||
BranchCreateOutput {
|
||||
|
|
@ -316,7 +320,8 @@ async fn main() -> Result<()> {
|
|||
.await?
|
||||
} else {
|
||||
let db = open_local_db_with_policy(&graph).await?;
|
||||
let actor = resolve_cli_actor(cli.as_actor.as_deref(), &config);
|
||||
let actor = resolve_cli_actor(cli.as_actor.as_deref(), &config)?;
|
||||
let actor = actor.as_deref();
|
||||
db.branch_delete_as(&name, actor).await?;
|
||||
BranchDeleteOutput {
|
||||
uri: uri.clone(),
|
||||
|
|
@ -358,7 +363,8 @@ async fn main() -> Result<()> {
|
|||
.await?
|
||||
} else {
|
||||
let db = open_local_db_with_policy(&graph).await?;
|
||||
let actor = resolve_cli_actor(cli.as_actor.as_deref(), &config);
|
||||
let actor = resolve_cli_actor(cli.as_actor.as_deref(), &config)?;
|
||||
let actor = actor.as_deref();
|
||||
let outcome = db.branch_merge_as(&source, &into, actor).await?;
|
||||
BranchMergeOutput {
|
||||
source: source.clone(),
|
||||
|
|
@ -514,7 +520,8 @@ async fn main() -> Result<()> {
|
|||
.await?
|
||||
} else {
|
||||
let db = open_local_db_with_policy(&graph).await?;
|
||||
let actor = resolve_cli_actor(cli.as_actor.as_deref(), &config);
|
||||
let actor = resolve_cli_actor(cli.as_actor.as_deref(), &config)?;
|
||||
let actor = actor.as_deref();
|
||||
let registry = load_registry_or_report(&config, graph.selected())?;
|
||||
let registry = (!registry.is_empty()).then_some(registry);
|
||||
let label = graph.selected().unwrap_or(&uri).to_string();
|
||||
|
|
|
|||
212
crates/omnigraph-cli/src/operator.rs
Normal file
212
crates/omnigraph-cli/src/operator.rs
Normal file
|
|
@ -0,0 +1,212 @@
|
|||
//! The operator config surface (RFC-007): `~/.omnigraph/config.yaml` — who
|
||||
//! the operator IS (identity, ergonomics), never what the system is (that's
|
||||
//! cluster config) and never a project file (nothing here arrives with a
|
||||
//! repo checkout).
|
||||
//!
|
||||
//! PR-1 scope: `operator.actor` + `defaults.output`. Unknown keys WARN and
|
||||
//! are preserved-by-ignoring — a file written for a newer CLI (servers,
|
||||
//! aliases, credentials keys from later slices) must load cleanly on this
|
||||
//! one. Contrast with `cluster.yaml`, where unknown keys are fatal because
|
||||
//! they change what a plan means.
|
||||
//!
|
||||
//! This module is CLI-only by design: the server never reads operator
|
||||
//! config (server-side identity comes from bearer auth — invariant 11
|
||||
//! holds by construction).
|
||||
|
||||
use std::env;
|
||||
use std::path::{Path, PathBuf};
|
||||
|
||||
use color_eyre::Result;
|
||||
use color_eyre::eyre::eyre;
|
||||
use serde::Deserialize;
|
||||
|
||||
use omnigraph_server::config::ReadOutputFormat;
|
||||
|
||||
pub(crate) const OPERATOR_HOME_ENV: &str = "OMNIGRAPH_HOME";
|
||||
pub(crate) const OPERATOR_DIR: &str = ".omnigraph";
|
||||
pub(crate) const OPERATOR_CONFIG_FILE: &str = "config.yaml";
|
||||
|
||||
#[derive(Debug, Default, Deserialize)]
|
||||
pub(crate) struct OperatorConfig {
|
||||
#[serde(default)]
|
||||
pub(crate) operator: OperatorIdentity,
|
||||
#[serde(default)]
|
||||
pub(crate) defaults: OperatorDefaults,
|
||||
/// Everything this CLI version doesn't know. Warned once at load,
|
||||
/// otherwise ignored (forward compatibility within the operator layer).
|
||||
#[serde(flatten)]
|
||||
unknown: serde_yaml::Mapping,
|
||||
}
|
||||
|
||||
#[derive(Debug, Default, Deserialize)]
|
||||
pub(crate) struct OperatorIdentity {
|
||||
/// Default actor for every `--as` cascade (CLI direct-engine writes and
|
||||
/// cluster commands alike): `--as` > legacy config actor (RFC-008
|
||||
/// window) > this > none.
|
||||
pub(crate) actor: Option<String>,
|
||||
#[serde(flatten)]
|
||||
unknown: serde_yaml::Mapping,
|
||||
}
|
||||
|
||||
#[derive(Debug, Default, Deserialize)]
|
||||
pub(crate) struct OperatorDefaults {
|
||||
/// Default read output format, below every more-specific source.
|
||||
pub(crate) output: Option<ReadOutputFormat>,
|
||||
#[serde(flatten)]
|
||||
unknown: serde_yaml::Mapping,
|
||||
}
|
||||
|
||||
impl OperatorConfig {
|
||||
pub(crate) fn actor(&self) -> Option<&str> {
|
||||
self.operator.actor.as_deref()
|
||||
}
|
||||
|
||||
pub(crate) fn output(&self) -> Option<ReadOutputFormat> {
|
||||
self.defaults.output
|
||||
}
|
||||
}
|
||||
|
||||
/// The operator dir: `$OMNIGRAPH_HOME` if set (tilde-expanded), else
|
||||
/// `~/.omnigraph`. Returns None when no home directory is resolvable
|
||||
/// (degenerate environments — the layer is simply absent).
|
||||
pub(crate) fn operator_dir() -> Option<PathBuf> {
|
||||
if let Some(home_override) = env::var_os(OPERATOR_HOME_ENV) {
|
||||
let raw = home_override.to_string_lossy().into_owned();
|
||||
return Some(expand_tilde(&raw));
|
||||
}
|
||||
env::home_dir().map(|home| home.join(OPERATOR_DIR))
|
||||
}
|
||||
|
||||
/// Load the operator layer. Absent file (or unresolvable home) is an empty
|
||||
/// layer, never an error; a present-but-malformed file is a loud error (the
|
||||
/// operator owns it and can fix it); unknown keys warn to stderr once.
|
||||
pub(crate) fn load_operator_config() -> Result<OperatorConfig> {
|
||||
let Some(dir) = operator_dir() else {
|
||||
return Ok(OperatorConfig::default());
|
||||
};
|
||||
load_operator_config_at(&dir.join(OPERATOR_CONFIG_FILE))
|
||||
}
|
||||
|
||||
pub(crate) fn load_operator_config_at(path: &Path) -> Result<OperatorConfig> {
|
||||
let text = match std::fs::read_to_string(path) {
|
||||
Ok(text) => text,
|
||||
Err(err) if err.kind() == std::io::ErrorKind::NotFound => {
|
||||
return Ok(OperatorConfig::default());
|
||||
}
|
||||
Err(err) => {
|
||||
return Err(eyre!(
|
||||
"could not read operator config '{}': {err}",
|
||||
path.display()
|
||||
));
|
||||
}
|
||||
};
|
||||
let config: OperatorConfig = serde_yaml::from_str(&text).map_err(|err| {
|
||||
eyre!(
|
||||
"could not parse operator config '{}': {err}",
|
||||
path.display()
|
||||
)
|
||||
})?;
|
||||
for warning in config.unknown_key_warnings() {
|
||||
eprintln!("warning: {warning} in operator config '{}'", path.display());
|
||||
}
|
||||
Ok(config)
|
||||
}
|
||||
|
||||
impl OperatorConfig {
|
||||
fn unknown_key_warnings(&self) -> Vec<String> {
|
||||
let mut warnings = Vec::new();
|
||||
let mut collect = |mapping: &serde_yaml::Mapping, prefix: &str| {
|
||||
for key in mapping.keys() {
|
||||
if let Some(name) = key.as_str() {
|
||||
warnings.push(format!(
|
||||
"unknown key `{prefix}{name}` (newer CLI feature or typo); ignored"
|
||||
));
|
||||
}
|
||||
}
|
||||
};
|
||||
collect(&self.unknown, "");
|
||||
collect(&self.operator.unknown, "operator.");
|
||||
collect(&self.defaults.unknown, "defaults.");
|
||||
warnings
|
||||
}
|
||||
}
|
||||
|
||||
/// Expand a leading `~` / `~/` to the home directory (PR #139 finding 9:
|
||||
/// a literal `./~/…` path silently created a directory named `~`).
|
||||
pub(crate) fn expand_tilde(raw: &str) -> PathBuf {
|
||||
if raw == "~" {
|
||||
return env::home_dir().unwrap_or_else(|| PathBuf::from(raw));
|
||||
}
|
||||
if let Some(rest) = raw.strip_prefix("~/") {
|
||||
if let Some(home) = env::home_dir() {
|
||||
return home.join(rest);
|
||||
}
|
||||
}
|
||||
PathBuf::from(raw)
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
mod tests {
|
||||
use super::*;
|
||||
use std::fs;
|
||||
|
||||
#[test]
|
||||
fn absent_file_is_an_empty_layer() {
|
||||
let dir = tempfile::tempdir().unwrap();
|
||||
let config = load_operator_config_at(&dir.path().join("config.yaml")).unwrap();
|
||||
assert!(config.actor().is_none());
|
||||
assert!(config.output().is_none());
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn parses_identity_and_defaults() {
|
||||
let dir = tempfile::tempdir().unwrap();
|
||||
let path = dir.path().join("config.yaml");
|
||||
fs::write(
|
||||
&path,
|
||||
"operator:\n actor: act-andrew\ndefaults:\n output: json\n",
|
||||
)
|
||||
.unwrap();
|
||||
let config = load_operator_config_at(&path).unwrap();
|
||||
assert_eq!(config.actor(), Some("act-andrew"));
|
||||
assert_eq!(config.output(), Some(ReadOutputFormat::Json));
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn unknown_keys_warn_but_load() {
|
||||
// A file written for a later slice (servers/aliases) must load
|
||||
// cleanly today — warn-only forward compatibility.
|
||||
let dir = tempfile::tempdir().unwrap();
|
||||
let path = dir.path().join("config.yaml");
|
||||
fs::write(
|
||||
&path,
|
||||
"operator:\n actor: act-a\n color: green\nservers:\n prod:\n url: https://example.com\naliases: {}\n",
|
||||
)
|
||||
.unwrap();
|
||||
let config = load_operator_config_at(&path).unwrap();
|
||||
assert_eq!(config.actor(), Some("act-a"));
|
||||
let warnings = config.unknown_key_warnings();
|
||||
assert_eq!(warnings.len(), 3, "{warnings:?}");
|
||||
assert!(warnings.iter().any(|w| w.contains("`servers`")));
|
||||
assert!(warnings.iter().any(|w| w.contains("`aliases`")));
|
||||
assert!(warnings.iter().any(|w| w.contains("`operator.color`")));
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn malformed_yaml_is_a_loud_error() {
|
||||
let dir = tempfile::tempdir().unwrap();
|
||||
let path = dir.path().join("config.yaml");
|
||||
fs::write(&path, "operator: [not, a, mapping\n").unwrap();
|
||||
let err = load_operator_config_at(&path).unwrap_err();
|
||||
assert!(err.to_string().contains("could not parse operator config"));
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn expand_tilde_resolves_home_prefix() {
|
||||
let home = env::home_dir().unwrap();
|
||||
assert_eq!(expand_tilde("~"), home);
|
||||
assert_eq!(expand_tilde("~/x/y"), home.join("x/y"));
|
||||
assert_eq!(expand_tilde("/abs/path"), PathBuf::from("/abs/path"));
|
||||
assert_eq!(expand_tilde("rel/path"), PathBuf::from("rel/path"));
|
||||
}
|
||||
}
|
||||
Loading…
Add table
Add a link
Reference in a new issue