feat(sys): add offline Portage install/remove/search commands
Some checks are pending
ci / test (push) Waiting to run

sys install <name>, sys remove <name> and sys search <query> are
deterministic and model-free: Portage resolves a bare name or a full atom.
Adds the remove_package and search_packages typed actions (remove is High risk
and gets the protective snapshot; search is read-only). This is the
old-fashioned fallback so the system stays fully administrable with no LLM.
This commit is contained in:
Phoebus 2026-09-20 14:28:35 -07:00
parent ab7408cdcf
commit 15cc9ec58c
4 changed files with 180 additions and 26 deletions

View file

@ -8,6 +8,11 @@ Format: Keep a Changelog. Dates are UTC.
## Unreleased ## Unreleased
### Added ### Added
- `sys` offline package commands: `sys install <name>`, `sys remove <name>`,
`sys search <query>` (plus the `remove_package`/`search_packages` typed
actions). They are deterministic Portage operations with no model involved —
`emerge` resolves a bare name or a full atom — so the system stays fully
administrable offline and without the assistant.
- **Debian-Live installer appliance** (`installer/live/build.sh`, no root): a - **Debian-Live installer appliance** (`installer/live/build.sh`, no root): a
bootable Phoebus installer ISO built by overlaying the static installer, the bootable Phoebus installer ISO built by overlaying the static installer, the
OpenCode manifest and the Debian tools the live image lacks onto a Debian-Live OpenCode manifest and the Debian tools the live image lacks onto a Debian-Live

View file

@ -28,6 +28,9 @@ sys enable sshd # deterministic phrase -> typed action
sys disable bluetooth sys disable bluetooth
sys history # snapshot/transaction history sys history # snapshot/transaction history
sys what are you compiling # background update status sys what are you compiling # background update status
sys install vim # Portage (bare name or category/name)
sys search firefox
sys remove vim
sys --action '{"action":"inspect_service","name":"ssh"}' sys --action '{"action":"inspect_service","name":"ssh"}'
sys --action-file proposal.json # the AI path: same typed schema sys --action-file proposal.json # the AI path: same typed schema
``` ```

View file

@ -31,6 +31,8 @@ pub enum SystemAction {
DisableService { name: String }, DisableService { name: String },
InspectPackage { atom: String }, InspectPackage { atom: String },
InstallPackage { atom: String }, InstallPackage { atom: String },
RemovePackage { atom: String },
SearchPackages { query: String },
CreateSnapshot { operation: String }, CreateSnapshot { operation: String },
History, History,
UpdateSystem, UpdateSystem,
@ -48,6 +50,10 @@ impl SystemAction {
} }
SystemAction::InspectPackage { atom } => format!("inspect package {atom}"), SystemAction::InspectPackage { atom } => format!("inspect package {atom}"),
SystemAction::InstallPackage { atom } => format!("install package {atom}"), SystemAction::InstallPackage { atom } => format!("install package {atom}"),
SystemAction::RemovePackage { atom } => format!("remove package {atom}"),
SystemAction::SearchPackages { query } => {
format!("search packages for `{query}`")
}
SystemAction::CreateSnapshot { operation } => { SystemAction::CreateSnapshot { operation } => {
format!("create a Btrfs snapshot before: {operation}") format!("create a Btrfs snapshot before: {operation}")
} }
@ -65,14 +71,18 @@ impl SystemAction {
/// snapshot and/or stronger confirmation is required. /// snapshot and/or stronger confirmation is required.
pub fn risk(&self) -> Risk { pub fn risk(&self) -> Risk {
match self { match self {
SystemAction::InspectService { .. } | SystemAction::InspectPackage { .. } => Risk::Low, SystemAction::InspectService { .. }
| SystemAction::InspectPackage { .. }
| SystemAction::SearchPackages { .. } => Risk::Low,
SystemAction::History => Risk::Low, SystemAction::History => Risk::Low,
SystemAction::InspectUpdates => Risk::Low, SystemAction::InspectUpdates => Risk::Low,
SystemAction::PrepareUpdates => Risk::Medium, SystemAction::PrepareUpdates => Risk::Medium,
SystemAction::EnableService { .. } SystemAction::EnableService { .. }
| SystemAction::DisableService { .. } | SystemAction::DisableService { .. }
| SystemAction::CreateSnapshot { .. } => Risk::Medium, | SystemAction::CreateSnapshot { .. } => Risk::Medium,
SystemAction::InstallPackage { .. } | SystemAction::UpdateSystem => Risk::High, SystemAction::InstallPackage { .. }
| SystemAction::RemovePackage { .. }
| SystemAction::UpdateSystem => Risk::High,
} }
} }
@ -83,6 +93,7 @@ impl SystemAction {
self, self,
SystemAction::InspectService { .. } SystemAction::InspectService { .. }
| SystemAction::InspectPackage { .. } | SystemAction::InspectPackage { .. }
| SystemAction::SearchPackages { .. }
| SystemAction::History | SystemAction::History
| SystemAction::InspectUpdates | SystemAction::InspectUpdates
) )
@ -105,15 +116,20 @@ impl SystemAction {
Err(format!("invalid service name: {name}")) Err(format!("invalid service name: {name}"))
} }
} }
SystemAction::InspectPackage { atom } | SystemAction::InstallPackage { atom } => { SystemAction::InspectPackage { atom }
let ok = atom.split('/').count() == 2 | SystemAction::InstallPackage { atom }
&& atom | SystemAction::RemovePackage { atom } => {
.chars() if valid_package_spec(atom) {
.all(|c| c.is_ascii_alphanumeric() || "/*._+-".contains(c));
if ok {
Ok(()) Ok(())
} else { } else {
Err(format!("invalid package atom: {atom}")) Err(format!("invalid package name: {atom}"))
}
}
SystemAction::SearchPackages { query } => {
if valid_search_query(query) {
Ok(())
} else {
Err(format!("invalid search query: {query}"))
} }
} }
SystemAction::CreateSnapshot { operation } => { SystemAction::CreateSnapshot { operation } => {
@ -131,6 +147,40 @@ impl SystemAction {
} }
} }
fn is_atom_char(c: char) -> bool {
c.is_ascii_alphanumeric() || "+._@-".contains(c)
}
/// A package may be a bare name (`vim`) so `emerge vim` resolves it, or a full
/// atom (`app-editors/vim`). Both are accepted; anything else is refused.
pub fn valid_package_spec(spec: &str) -> bool {
if spec.is_empty() || spec.len() > 128 {
return false;
}
let mut parts = spec.split('/');
let Some(first) = parts.next() else {
return false;
};
if first.is_empty() || !first.chars().all(is_atom_char) {
return false;
}
match parts.next() {
None => true,
Some(second) => {
!second.is_empty() && second.chars().all(is_atom_char) && parts.next().is_none()
}
}
}
/// A bounded search query (letters, digits and a few punctuation characters).
pub fn valid_search_query(query: &str) -> bool {
!query.is_empty()
&& query.len() <= 128
&& query
.chars()
.all(|c| c.is_ascii_alphanumeric() || " ._+@/-".contains(c))
}
/// A small deterministic parser for common `sys` phrases. /// A small deterministic parser for common `sys` phrases.
/// ///
/// Free-form requests that do not match are left to the AI path /// Free-form requests that do not match are left to the AI path
@ -138,18 +188,9 @@ impl SystemAction {
pub fn parse_natural(text: &str) -> Option<SystemAction> { pub fn parse_natural(text: &str) -> Option<SystemAction> {
let t = text.trim().to_lowercase(); let t = text.trim().to_lowercase();
let rest = |prefix: &str| t.strip_prefix(prefix).map(|r| r.trim().to_string()); let rest = |prefix: &str| t.strip_prefix(prefix).map(|r| r.trim().to_string());
if t == "history" || t.contains("history") {
return Some(SystemAction::History); // Explicit commands first, so a search/install query cannot be mistaken for
} // one of the heuristic phrases below.
if t == "update" || t == "update system" || t == "sys update" {
return Some(SystemAction::UpdateSystem);
}
if t.contains("prepare") && t.contains("update") {
return Some(SystemAction::PrepareUpdates);
}
if t.contains("what are you compiling") || t.contains("update status") {
return Some(SystemAction::InspectUpdates);
}
if let Some(name) = rest("enable ") { if let Some(name) = rest("enable ") {
if !name.is_empty() { if !name.is_empty() {
return Some(SystemAction::EnableService { name }); return Some(SystemAction::EnableService { name });
@ -160,16 +201,42 @@ pub fn parse_natural(text: &str) -> Option<SystemAction> {
return Some(SystemAction::DisableService { name }); return Some(SystemAction::DisableService { name });
} }
} }
if let Some(atom) = rest("install ") { if let Some(atom) = rest("install ").or_else(|| rest("add ")) {
if atom.contains('/') { if !atom.is_empty() {
return Some(SystemAction::InstallPackage { atom }); return Some(SystemAction::InstallPackage { atom });
} }
} }
if let Some(atom) = rest("remove ")
.or_else(|| rest("uninstall "))
.or_else(|| rest("delete "))
{
if !atom.is_empty() {
return Some(SystemAction::RemovePackage { atom });
}
}
if let Some(query) = rest("search ").or_else(|| rest("find ")) {
if !query.is_empty() {
return Some(SystemAction::SearchPackages { query });
}
}
if let Some(name) = rest("inspect ") { if let Some(name) = rest("inspect ") {
if !name.is_empty() { if !name.is_empty() {
return Some(SystemAction::InspectService { name }); return Some(SystemAction::InspectService { name });
} }
} }
if t == "history" || t.starts_with("history ") {
return Some(SystemAction::History);
}
if t == "update" || t == "update system" || t == "sys update" {
return Some(SystemAction::UpdateSystem);
}
if t.contains("prepare") && t.contains("update") {
return Some(SystemAction::PrepareUpdates);
}
if t.contains("what are you compiling") || t.contains("update status") {
return Some(SystemAction::InspectUpdates);
}
None None
} }
@ -204,9 +271,26 @@ mod tests {
#[test] #[test]
fn rejects_unknown_fields_and_bad_values() { fn rejects_unknown_fields_and_bad_values() {
assert!(parse_action(r#"{"action":"install_package","atom":"steam","extra":1}"#).is_err()); assert!(parse_action(r#"{"action":"install_package","atom":"vim","extra":1}"#).is_err());
assert!(parse_action(r#"{"action":"install_package","atom":"notanatom"}"#).is_err()); assert!(parse_action(r#"{"action":"install_package","atom":"bad atom"}"#).is_err());
assert!(parse_action(r#"{"action":"install_package","atom":"a/b/c"}"#).is_err());
assert!(parse_action(r#"{"action":"enable_service","name":"bad name"}"#).is_err()); assert!(parse_action(r#"{"action":"enable_service","name":"bad name"}"#).is_err());
assert!(parse_action(r#"{"action":"search_packages","query":""}"#).is_err());
}
#[test]
fn accepts_bare_package_names() {
assert_eq!(
parse_action(r#"{"action":"install_package","atom":"vim"}"#).unwrap(),
SystemAction::InstallPackage { atom: "vim".into() }
);
let remove =
parse_action(r#"{"action":"remove_package","atom":"app-editors/vim"}"#).unwrap();
assert_eq!(remove.risk(), Risk::High);
assert!(remove.is_mutating());
let search = parse_action(r#"{"action":"search_packages","query":"firefox"}"#).unwrap();
assert!(!search.is_mutating());
assert_eq!(search.risk(), Risk::Low);
} }
#[test] #[test]
@ -224,6 +308,25 @@ mod tests {
atom: "app-editors/vim".into() atom: "app-editors/vim".into()
}) })
); );
// The friendly, apt-like forms resolve to Portage operations.
assert_eq!(
parse_natural("install vim"),
Some(SystemAction::InstallPackage { atom: "vim".into() })
);
assert_eq!(
parse_natural("remove vim"),
Some(SystemAction::RemovePackage { atom: "vim".into() })
);
assert_eq!(
parse_natural("uninstall vim"),
Some(SystemAction::RemovePackage { atom: "vim".into() })
);
assert_eq!(
parse_natural("search firefox"),
Some(SystemAction::SearchPackages {
query: "firefox".into()
})
);
assert_eq!(parse_natural("why is my audio broken"), None); assert_eq!(parse_natural("why is my audio broken"), None);
} }

View file

@ -93,8 +93,24 @@ pub fn execute(
format!("{}\n{}", out.stdout_lossy(), out.stderr_lossy()) format!("{}\n{}", out.stdout_lossy(), out.stderr_lossy())
} }
SystemAction::InstallPackage { atom } => { SystemAction::InstallPackage { atom } => {
// Portage resolves a bare name (`vim`) or a full atom.
exec.run(CommandSpec::new("sys", "install package", "emerge").args(["--ask=n", atom]))?; exec.run(CommandSpec::new("sys", "install package", "emerge").args(["--ask=n", atom]))?;
format!("installed {atom}") format!("installed {atom} (Portage)")
}
SystemAction::RemovePackage { atom } => {
exec.run(CommandSpec::new("sys", "remove package", "emerge").args([
"--unmerge",
"--ask=n",
atom,
]))?;
format!("removed {atom} (Portage)")
}
SystemAction::SearchPackages { query } => {
let out = exec.runner.execute(
&CommandSpec::new("sys", "search packages", "emerge")
.args(["--search", "--quiet", query]),
)?;
format!("{}\n{}", out.stdout_lossy(), out.stderr_lossy())
} }
SystemAction::UpdateSystem => { SystemAction::UpdateSystem => {
exec.run( exec.run(
@ -235,6 +251,33 @@ mod tests {
assert!(matches!(err, ExecError::Core(_)), "got {err}"); assert!(matches!(err, ExecError::Core(_)), "got {err}");
} }
#[test]
fn remove_package_builds_unmerge() {
let runner = RecordingRunner::new();
let exec = make_exec(runner.clone());
let auth = crate::auth::authorize(&crate::auth::AutoConfirm, "p", "f").unwrap();
let action = SystemAction::RemovePackage { atom: "vim".into() };
execute(&exec, &action, Some(&auth), Path::new(&exec.root)).unwrap();
let spec = &runner.recorded()[0];
assert_eq!(spec.program, "emerge");
assert!(spec.args.contains(&"--unmerge".to_string()));
assert!(spec.args.contains(&"vim".to_string()));
}
#[test]
fn search_packages_builds_emerge_search() {
let runner = RecordingRunner::new();
let exec = make_exec(runner.clone());
let action = SystemAction::SearchPackages {
query: "firefox".into(),
};
execute(&exec, &action, None, Path::new(&exec.root)).unwrap();
let spec = &runner.recorded()[0];
assert_eq!(spec.program, "emerge");
assert!(spec.args.contains(&"--search".to_string()));
assert!(spec.args.contains(&"firefox".to_string()));
}
#[test] #[test]
fn enable_builds_separate_arguments() { fn enable_builds_separate_arguments() {
let runner = RecordingRunner::new(); let runner = RecordingRunner::new();