M0: compilable skeleton — Kigi 0.1.0 fork surgery
Hard fork of xai-org/grok-build (Apache-2.0) re-targeted as Kigi, an
unofficial Kimi Code CLI community build.
Rename & identity
- 72 xai-*/xai-grok-* crates -> kigi-* (explicit: xai-grok-pager-bin ->
kigi-bin [binary `kigi`], xai-grok-pager -> kigi-tui; rest mechanical);
ptyctl, ptyctl-cli, third_party/ unchanged; proto package
xai.grok.tools.v1 -> kigi.tools.v1
- Config home ~/.kigi (KIGI_SHARE_DIR override), env prefix GROK_* ->
KIGI_*, `kigi --version` carries the unofficial-community-build notice
- clap identity, help text, startup banner, prompt templates rebranded
(templates re-encrypted)
Deletions (PRD removal list #5/#6/#7/#9/#10)
- voice input (xai-grok-voice) and all TUI wiring
- telemetry: Mixpanel client, external OTel stream, Sentry, OTLP layers,
trace/GCS/S3 upload queues (kigi-file-utils halved), workspace upload
module & dc_log, heap-profile uploader, auth-diagnostics uploader,
session-analytics halves of feedback; local zero-egress observability
preserved in new kigi-log crate (unified log, --debug firehose,
subsystem file logs, opt-in instrumentation)
- announcements (crate, remote-settings fields, TUI surfaces)
- plugin marketplace (crate, sources/browse/CTA/extensions-modal tab);
direct plugin install/uninstall/update via kigi-agent git_install kept
- relay/gateway/assets endpoints and features (agent relay, headless
relay transport, gateway bridge, LeaderEnvUrls); leader IPC socket now
~/.kigi/leader.sock + KIGI_LEADER_SOCKET, no ws-url derivation
- functional types rehomed instead of deleted: PermissionMode ->
kigi-config-types, McpInitStrategy -> kigi-mcp, PrCreationSource ->
session signals, TerminalDiagnostics -> kigi-pager-render, agent_id ->
shell util
Endpoints
- kigi-env rewritten: single production KigiEndpoints {coding_api_base_url
https://api.kimi.com/coding/v1 (KIGI_CODE_BASE_URL), oauth_host
https://auth.kimi.com (KIGI_OAUTH_HOST), update_base_url (GitHub
Releases API), upgrade_page_url}; GrokBuildEnvironment enum deleted
Toolchain & workspace hygiene
- Rust 1.97.0 pinned; edition 2024; full cargo update; git2 hoisted to
workspace at 0.21 (Option->Result API migration), quick-xml 0.41
- Root Cargo.toml hand-maintained (PRD §8.1): version 0.1.0 inherited by
all members, members sorted, unused deps pruned
- cargo-deny advisories gate (deny.toml with documented transitive
exceptions); CI workflow (check/clippy/fmt/deny/test, macOS+Linux)
- cross-crate test seams re-gated behind `test-support` cargo feature;
insta snapshot baselines renamed to the kigi_tui prefix
- clippy --workspace --all-targets: zero warnings; fmt clean
Fixes surfaced by the port
- updater probe/installer divergence (bin/kigi vs bin/grok symlink set)
- idle model-metadata refresh dead under KIGI_CODE_BASE_URL override
(new is_effective_coding_endpoint_url, loopback+override aware)
- macOS symlinked-TMPDIR fixture canonicalization (foreign_sessions,
fast-worktree); RSS measurement tests serialized via serial_test
Docs & legal (Apache §4)
- NOTICE added (upstream attribution + change statement); THIRD-PARTY
notices sustained; kigi-tools ported-code notices extended; README,
CONTRIBUTING, SECURITY, AGENTS.md rewritten
Out of scope for M0 (tracked): Kimi auth/inference (M1), search/fetch,
command parity, config import (M2), Computer Hub excision & final
brand-token sweep (M2), distribution & self-update rewrite (M3).
This commit is contained in:
ZacharyZhang-NY committed
commit
d6c20fc13f
2612 files changed
+1353757
No files matched your search
@@ -0,0 +1,954 @@
|
||||
//! Behavior version catalog for version-managed tools.
|
||||
//!
|
||||
//! This module defines which tools are version-managed, the available behavior
|
||||
//! presets (e.g. `"current"`, `"legacy-0.4.10"`), and the resolution logic that
|
||||
//! maps (preset, tool_id, per_tool_override) → concrete `contract_version`.
|
||||
//!
|
||||
//! ## Reminder behavior policy
|
||||
//!
|
||||
//! Reminders (per-tool and cross-cutting) always use current behavior regardless
|
||||
//! of the selected behavior preset. This is a deliberate design choice:
|
||||
//! reminders are a quality-of-life feature, not part of the tool contract.
|
||||
|
||||
use std::collections::HashMap;
|
||||
|
||||
/// Lifecycle stage of a behavior preset or version.
|
||||
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
|
||||
pub enum BehaviorLifecycle {
|
||||
/// Fully supported and recommended.
|
||||
Active,
|
||||
/// Still works but will be removed in a future release.
|
||||
Deprecated,
|
||||
/// Scheduled for removal — hosts should reject requests using this version.
|
||||
RemovalCandidate,
|
||||
}
|
||||
|
||||
/// Per-tool version metadata. Each managed tool has one entry in `TOOL_VERSION_REGISTRY`.
|
||||
#[derive(Debug)]
|
||||
pub struct ToolVersionEntry {
|
||||
/// Fully-qualified tool ID (e.g. `"GrokBuild:run_terminal_cmd"`).
|
||||
pub fq_tool_id: &'static str,
|
||||
/// Supported versions and their individual lifecycle.
|
||||
pub versions: &'static [VersionLifecycle],
|
||||
}
|
||||
|
||||
/// A single version supported by a tool.
|
||||
#[derive(Debug)]
|
||||
pub struct VersionLifecycle {
|
||||
/// Version string (e.g. `"current"`, `"legacy-0.4.10"`).
|
||||
pub version: &'static str,
|
||||
/// Independent lifecycle for this tool+version pair.
|
||||
pub lifecycle: BehaviorLifecycle,
|
||||
/// Suggested replacement when deprecated/removed. Must itself be a
|
||||
/// supported Active version for the same tool.
|
||||
pub replacement: Option<&'static str>,
|
||||
/// Optional deprecation message for operational tooling.
|
||||
pub deprecation_note: Option<&'static str>,
|
||||
/// The crate release version in which this catalog entry was first added.
|
||||
/// This is catalog-introduction metadata, not behavior-origin metadata.
|
||||
/// For reconstructed legacy behavior, this is the release that added the
|
||||
/// legacy port to the catalog.
|
||||
/// Empty string for `"current"` (moving alias with no fixed origin).
|
||||
pub cataloged_in: &'static str,
|
||||
/// Optional opaque references for humans browsing the catalog.
|
||||
/// Prefer empty; do not embed external PR/issue number lists here.
|
||||
/// Empty slice for `"current"` (moving alias).
|
||||
pub source_refs: &'static [&'static str],
|
||||
/// One-line summary of what this version's behavior is.
|
||||
/// Empty string for `"current"` (moving alias).
|
||||
pub summary: &'static str,
|
||||
}
|
||||
|
||||
/// A named behavior preset (bundle) that maps tool IDs to default contract versions.
|
||||
///
|
||||
/// Architecturally a "bundle" — a convenience mapping from a label to per-tool
|
||||
/// version defaults. Not canonical; must validate against `TOOL_VERSION_REGISTRY`.
|
||||
#[derive(Debug)]
|
||||
pub struct PresetEntry {
|
||||
/// Preset name, e.g. `"current"` or `"legacy-0.4.10"`.
|
||||
pub name: &'static str,
|
||||
/// Lifecycle stage of this preset.
|
||||
pub lifecycle: BehaviorLifecycle,
|
||||
/// Per-tool default versions for this preset.
|
||||
/// Keys are fully-qualified tool IDs (e.g. `"GrokBuild:run_terminal_cmd"`).
|
||||
/// Tools not listed here fall back to `"current"`.
|
||||
pub tool_defaults: &'static [(&'static str, &'static str)],
|
||||
}
|
||||
|
||||
/// Fully-qualified IDs of version-managed tools.
|
||||
///
|
||||
/// Only tools listed here can have `behavior_version` overrides.
|
||||
/// Uses fully-qualified IDs (`Namespace:tool_id`) to prevent collisions
|
||||
/// between namespaces (e.g. `GrokBuild:run_terminal_cmd` vs.
|
||||
/// `GrokBuildConcise:run_terminal_cmd`).
|
||||
pub const MANAGED_TOOLS: &[&str] = &[
|
||||
"GrokBuild:run_terminal_cmd",
|
||||
"GrokBuild:read_file",
|
||||
"GrokBuild:search_replace",
|
||||
"GrokBuild:list_dir",
|
||||
"GrokBuild:grep",
|
||||
"GrokBuild:kill_task",
|
||||
"GrokBuild:get_task_output",
|
||||
];
|
||||
|
||||
// Helper constant for concise registry entries.
|
||||
//
|
||||
// `V_CURRENT` is a moving alias — its metadata fields are empty because
|
||||
// `"current"` changes meaning over time. Stable canonical versions use
|
||||
// per-tool legacy constants with tool-specific metadata.
|
||||
const V_CURRENT: VersionLifecycle = VersionLifecycle {
|
||||
version: "current",
|
||||
lifecycle: BehaviorLifecycle::Active,
|
||||
replacement: None,
|
||||
deprecation_note: None,
|
||||
cataloged_in: "",
|
||||
source_refs: &[],
|
||||
summary: "",
|
||||
};
|
||||
|
||||
// Per-tool legacy constants — each carries tool-specific metadata because
|
||||
// the legacy behavior differs per tool.
|
||||
const V_LEGACY_BASH: VersionLifecycle = VersionLifecycle {
|
||||
version: "legacy-0.4.10",
|
||||
lifecycle: BehaviorLifecycle::Active,
|
||||
replacement: Some("current"),
|
||||
deprecation_note: None,
|
||||
cataloged_in: "0.1.158-alpha.1",
|
||||
source_refs: &[],
|
||||
summary: "Trailing-only & detection, legacy error text for background operator",
|
||||
};
|
||||
const V_LEGACY_READ_FILE: VersionLifecycle = VersionLifecycle {
|
||||
version: "legacy-0.4.10",
|
||||
lifecycle: BehaviorLifecycle::Active,
|
||||
replacement: Some("current"),
|
||||
deprecation_note: None,
|
||||
cataloged_in: "0.1.158-alpha.1",
|
||||
source_refs: &[],
|
||||
summary: "No gitignore enforcement, generic error text, no confusable reminders",
|
||||
};
|
||||
const V_LEGACY_SEARCH_REPLACE: VersionLifecycle = VersionLifecycle {
|
||||
version: "legacy-0.4.10",
|
||||
lifecycle: BehaviorLifecycle::Active,
|
||||
replacement: Some("current"),
|
||||
deprecation_note: None,
|
||||
cataloged_in: "0.1.158-alpha.1",
|
||||
source_refs: &[],
|
||||
summary: "No gitignore enforcement, structured errors downgraded to InvalidInput",
|
||||
};
|
||||
const V_LEGACY_LIST_DIR: VersionLifecycle = VersionLifecycle {
|
||||
version: "legacy-0.4.10",
|
||||
lifecycle: BehaviorLifecycle::Active,
|
||||
replacement: Some("current"),
|
||||
deprecation_note: None,
|
||||
cataloged_in: "0.1.158-alpha.1",
|
||||
source_refs: &[],
|
||||
summary: "Depth-threshold rendering, generic error text, no-children-found for empty dirs",
|
||||
};
|
||||
const V_LEGACY_KILL_TASK: VersionLifecycle = VersionLifecycle {
|
||||
version: "legacy-0.4.10",
|
||||
lifecycle: BehaviorLifecycle::Active,
|
||||
replacement: Some("current"),
|
||||
deprecation_note: None,
|
||||
cataloged_in: "0.1.158-alpha.1",
|
||||
source_refs: &[],
|
||||
summary: "Simple not-found text without known task ID enumeration",
|
||||
};
|
||||
const V_LEGACY_TASK_OUTPUT: VersionLifecycle = VersionLifecycle {
|
||||
version: "legacy-0.4.10",
|
||||
lifecycle: BehaviorLifecycle::Active,
|
||||
replacement: Some("current"),
|
||||
deprecation_note: None,
|
||||
cataloged_in: "0.1.158-alpha.1",
|
||||
source_refs: &[],
|
||||
summary: "Simple not-found text without known task ID enumeration",
|
||||
};
|
||||
|
||||
/// Per-tool version registry — canonical source for which versions each
|
||||
/// managed tool supports and their individual lifecycle.
|
||||
///
|
||||
/// - 7 managed tools total
|
||||
/// - 6 legacy-ported (support both `"current"` and `"legacy-0.4.10"`)
|
||||
/// - 1 managed but unported (`grep` — only `"current"`)
|
||||
///
|
||||
/// Each legacy-ported tool has its own `V_LEGACY_*` constant with tool-specific
|
||||
/// `summary` and `source_refs`. Do not use a shared legacy constant.
|
||||
pub const TOOL_VERSION_REGISTRY: &[ToolVersionEntry] = &[
|
||||
ToolVersionEntry {
|
||||
fq_tool_id: "GrokBuild:run_terminal_cmd",
|
||||
versions: &[V_CURRENT, V_LEGACY_BASH],
|
||||
},
|
||||
ToolVersionEntry {
|
||||
fq_tool_id: "GrokBuild:read_file",
|
||||
versions: &[V_CURRENT, V_LEGACY_READ_FILE],
|
||||
},
|
||||
ToolVersionEntry {
|
||||
fq_tool_id: "GrokBuild:search_replace",
|
||||
versions: &[V_CURRENT, V_LEGACY_SEARCH_REPLACE],
|
||||
},
|
||||
ToolVersionEntry {
|
||||
fq_tool_id: "GrokBuild:list_dir",
|
||||
versions: &[V_CURRENT, V_LEGACY_LIST_DIR],
|
||||
},
|
||||
ToolVersionEntry {
|
||||
fq_tool_id: "GrokBuild:grep",
|
||||
versions: &[V_CURRENT], // Managed but no legacy implementation.
|
||||
},
|
||||
ToolVersionEntry {
|
||||
fq_tool_id: "GrokBuild:kill_task",
|
||||
versions: &[V_CURRENT, V_LEGACY_KILL_TASK],
|
||||
},
|
||||
ToolVersionEntry {
|
||||
fq_tool_id: "GrokBuild:get_task_output",
|
||||
versions: &[V_CURRENT, V_LEGACY_TASK_OUTPUT],
|
||||
},
|
||||
];
|
||||
|
||||
/// Available behavior presets.
|
||||
///
|
||||
/// ## Reminder behavior policy
|
||||
///
|
||||
/// Reminders always use current behavior regardless of preset selection.
|
||||
/// They are not versioned — this is a deliberate design choice (Option B).
|
||||
pub const PRESETS: &[PresetEntry] = &[
|
||||
PresetEntry {
|
||||
name: "current",
|
||||
lifecycle: BehaviorLifecycle::Active,
|
||||
// All managed tools default to "current" — no per-tool overrides needed.
|
||||
tool_defaults: &[],
|
||||
},
|
||||
PresetEntry {
|
||||
name: "legacy-0.4.10",
|
||||
lifecycle: BehaviorLifecycle::Active,
|
||||
tool_defaults: &[
|
||||
("GrokBuild:run_terminal_cmd", "legacy-0.4.10"),
|
||||
("GrokBuild:read_file", "legacy-0.4.10"),
|
||||
("GrokBuild:search_replace", "legacy-0.4.10"),
|
||||
("GrokBuild:get_task_output", "legacy-0.4.10"),
|
||||
("GrokBuild:kill_task", "legacy-0.4.10"),
|
||||
("GrokBuild:list_dir", "legacy-0.4.10"),
|
||||
],
|
||||
},
|
||||
// Release-named presets are best-effort compatibility bundles, not full
|
||||
// historical snapshots. Later-added or unported tools may resolve to
|
||||
// `current` unless explicitly represented. Prefer stable named versions
|
||||
// over `current` here — using `current` means the preset's behavior for
|
||||
// that tool will silently change over time.
|
||||
PresetEntry {
|
||||
name: "release-0.1.157",
|
||||
lifecycle: BehaviorLifecycle::Active,
|
||||
// At 0.1.157, all managed tools were at `current`. No per-tool
|
||||
// version other than `legacy-0.4.10` had been carved out yet.
|
||||
// `grep` was managed but current-only (no legacy port).
|
||||
tool_defaults: &[
|
||||
("GrokBuild:run_terminal_cmd", "current"),
|
||||
("GrokBuild:read_file", "current"),
|
||||
("GrokBuild:search_replace", "current"),
|
||||
("GrokBuild:list_dir", "current"),
|
||||
("GrokBuild:grep", "current"),
|
||||
("GrokBuild:kill_task", "current"),
|
||||
("GrokBuild:get_task_output", "current"),
|
||||
],
|
||||
},
|
||||
];
|
||||
|
||||
/// Check whether a contract version string is the legacy-0.4.10 version.
|
||||
///
|
||||
/// Use this for tools with trivial version deltas (e.g. `kill_task`,
|
||||
/// `get_task_output` which only differ in not-found wording). For tools
|
||||
/// with substantial version divergence, prefer a typed enum like
|
||||
/// `BashVersion` or `ListDirVersion`.
|
||||
pub fn is_legacy_contract(contract_version: Option<&str>) -> bool {
|
||||
contract_version == Some("legacy-0.4.10")
|
||||
}
|
||||
|
||||
/// Look up a preset (bundle) by name.
|
||||
pub fn lookup_preset(name: &str) -> Option<&'static PresetEntry> {
|
||||
PRESETS.iter().find(|p| p.name == name)
|
||||
}
|
||||
|
||||
/// Check whether a fully-qualified tool ID is version-managed.
|
||||
pub fn is_version_managed(fq_tool_id: &str) -> bool {
|
||||
MANAGED_TOOLS.contains(&fq_tool_id)
|
||||
}
|
||||
|
||||
/// Get the supported versions for a tool from the per-tool registry.
|
||||
///
|
||||
/// Returns `None` if the tool is not in the registry.
|
||||
pub fn tool_supported_versions(fq_tool_id: &str) -> Option<&'static [VersionLifecycle]> {
|
||||
TOOL_VERSION_REGISTRY
|
||||
.iter()
|
||||
.find(|e| e.fq_tool_id == fq_tool_id)
|
||||
.map(|e| e.versions)
|
||||
}
|
||||
|
||||
/// Get the lifecycle for a specific tool+version pair.
|
||||
///
|
||||
/// Returns `None` if the tool is not in the registry or does not support
|
||||
/// the requested version.
|
||||
pub fn tool_version_lifecycle(fq_tool_id: &str, version: &str) -> Option<BehaviorLifecycle> {
|
||||
tool_supported_versions(fq_tool_id)?
|
||||
.iter()
|
||||
.find(|v| v.version == version)
|
||||
.map(|v| v.lifecycle)
|
||||
}
|
||||
|
||||
/// Get the suggested replacement for a specific tool+version pair.
|
||||
///
|
||||
/// Returns `None` if no replacement is configured (e.g. version is Active).
|
||||
pub fn tool_version_replacement(fq_tool_id: &str, version: &str) -> Option<&'static str> {
|
||||
tool_supported_versions(fq_tool_id)?
|
||||
.iter()
|
||||
.find(|v| v.version == version)?
|
||||
.replacement
|
||||
}
|
||||
|
||||
/// A deprecation warning produced during version resolution.
|
||||
#[derive(Debug, Clone)]
|
||||
pub struct VersionWarning {
|
||||
/// Fully-qualified tool ID, or empty for bundle-level warnings.
|
||||
pub fq_tool_id: String,
|
||||
/// The deprecated version.
|
||||
pub deprecated_version: String,
|
||||
/// Suggested replacement.
|
||||
pub replacement: String,
|
||||
/// Human-readable message.
|
||||
pub message: String,
|
||||
}
|
||||
|
||||
/// Result of resolving a version for a single tool, including any warnings.
|
||||
#[derive(Debug)]
|
||||
pub struct VersionResolution {
|
||||
/// The resolved contract version, or None for unmanaged tools.
|
||||
pub contract_version: Option<String>,
|
||||
/// Any deprecation warnings generated during resolution.
|
||||
pub warnings: Vec<VersionWarning>,
|
||||
}
|
||||
|
||||
/// Resolve the concrete contract version for a tool.
|
||||
///
|
||||
/// ## Resolution order
|
||||
///
|
||||
/// 1. `per_tool_override` — if `Some`, use it (validated against known versions).
|
||||
/// 2. Preset `tool_defaults` entry for this `fq_tool_id`.
|
||||
/// 3. `"current"` (fallback for managed tools not yet in preset defaults).
|
||||
///
|
||||
/// ## Returns
|
||||
///
|
||||
/// - `Ok(Some(version))` — for version-managed tools.
|
||||
/// - `Ok(None)` — for tools NOT in `MANAGED_TOOLS` (unmanaged).
|
||||
/// - `Err(msg)` — for:
|
||||
/// - Unknown preset name
|
||||
/// - Unknown `per_tool_override` value
|
||||
/// - `per_tool_override` supplied for a tool not in `MANAGED_TOOLS`
|
||||
///
|
||||
/// Resolve version — convenience wrapper that discards warnings.
|
||||
/// Use `resolve_version_with_warnings()` when you need deprecation warnings.
|
||||
pub fn resolve_version(
|
||||
preset_name: &str,
|
||||
fq_tool_id: &str,
|
||||
per_tool_override: Option<&str>,
|
||||
) -> Result<Option<String>, String> {
|
||||
resolve_version_with_warnings(preset_name, fq_tool_id, per_tool_override)
|
||||
.map(|r| r.contract_version)
|
||||
}
|
||||
|
||||
/// Resolve the concrete contract version for a tool, with deprecation warnings.
|
||||
pub fn resolve_version_with_warnings(
|
||||
preset_name: &str,
|
||||
fq_tool_id: &str,
|
||||
per_tool_override: Option<&str>,
|
||||
) -> Result<VersionResolution, String> {
|
||||
// Validate the preset exists.
|
||||
let preset = lookup_preset(preset_name)
|
||||
.ok_or_else(|| format!("unknown behavior_preset: \"{preset_name}\""))?;
|
||||
|
||||
let mut warnings = Vec::new();
|
||||
|
||||
// Check preset lifecycle.
|
||||
match preset.lifecycle {
|
||||
BehaviorLifecycle::RemovalCandidate => {
|
||||
return Err(format!(
|
||||
"behavior_preset \"{}\" is scheduled for removal and cannot be used",
|
||||
preset_name
|
||||
));
|
||||
}
|
||||
BehaviorLifecycle::Deprecated => {
|
||||
tracing::warn!(
|
||||
"behavior_preset \"{}\" is deprecated and will be removed in a future release",
|
||||
preset_name
|
||||
);
|
||||
warnings.push(VersionWarning {
|
||||
fq_tool_id: String::new(), // bundle-level warning
|
||||
deprecated_version: preset_name.to_string(),
|
||||
replacement: "current".to_string(),
|
||||
message: format!(
|
||||
"behavior_preset \"{}\" is deprecated and will be removed in a future release",
|
||||
preset_name
|
||||
),
|
||||
});
|
||||
}
|
||||
BehaviorLifecycle::Active => {}
|
||||
}
|
||||
|
||||
// If a per-tool override is given for an unmanaged tool, reject it.
|
||||
if per_tool_override.is_some() && !is_version_managed(fq_tool_id) {
|
||||
return Err(format!(
|
||||
"behavior_version override not allowed for unmanaged tool \"{fq_tool_id}\""
|
||||
));
|
||||
}
|
||||
|
||||
// Unmanaged tools → None (no contract version).
|
||||
if !is_version_managed(fq_tool_id) {
|
||||
return Ok(VersionResolution {
|
||||
contract_version: None,
|
||||
warnings,
|
||||
});
|
||||
}
|
||||
|
||||
// Per-tool override wins if present.
|
||||
if let Some(override_version) = per_tool_override {
|
||||
let (version, mut tool_warnings) = validate_and_resolve(fq_tool_id, override_version)?;
|
||||
warnings.append(&mut tool_warnings);
|
||||
return Ok(VersionResolution {
|
||||
contract_version: version,
|
||||
warnings,
|
||||
});
|
||||
}
|
||||
|
||||
// Check preset tool_defaults for this tool.
|
||||
let tool_defaults: HashMap<&str, &str> = preset.tool_defaults.iter().copied().collect();
|
||||
if let Some(&version) = tool_defaults.get(fq_tool_id) {
|
||||
let (version, mut tool_warnings) = validate_and_resolve(fq_tool_id, version)?;
|
||||
warnings.append(&mut tool_warnings);
|
||||
return Ok(VersionResolution {
|
||||
contract_version: version,
|
||||
warnings,
|
||||
});
|
||||
}
|
||||
|
||||
// Fallback: "current" for managed tools not yet in preset defaults.
|
||||
Ok(VersionResolution {
|
||||
contract_version: Some("current".to_string()),
|
||||
warnings,
|
||||
})
|
||||
}
|
||||
|
||||
/// Validate a version against the per-tool registry and apply lifecycle rules.
|
||||
///
|
||||
/// - `Active` → use it.
|
||||
/// - `Deprecated` → warn + continue.
|
||||
/// - `RemovalCandidate` → reject with replacement suggestion.
|
||||
/// - Not found → reject with supported versions list.
|
||||
fn validate_and_resolve(
|
||||
fq_tool_id: &str,
|
||||
version: &str,
|
||||
) -> Result<(Option<String>, Vec<VersionWarning>), String> {
|
||||
let supported = tool_supported_versions(fq_tool_id)
|
||||
.ok_or_else(|| format!("tool \"{fq_tool_id}\" not found in version registry"))?;
|
||||
|
||||
let entry = supported.iter().find(|v| v.version == version);
|
||||
match entry {
|
||||
Some(v) => match v.lifecycle {
|
||||
BehaviorLifecycle::Active => Ok((Some(version.to_string()), vec![])),
|
||||
BehaviorLifecycle::Deprecated => {
|
||||
let note = v.deprecation_note.unwrap_or("no details");
|
||||
let replacement = v.replacement.unwrap_or("current");
|
||||
tracing::warn!(
|
||||
tool = fq_tool_id,
|
||||
version = version,
|
||||
replacement = replacement,
|
||||
"behavior version is deprecated: {note}"
|
||||
);
|
||||
let warning = VersionWarning {
|
||||
fq_tool_id: fq_tool_id.to_string(),
|
||||
deprecated_version: version.to_string(),
|
||||
replacement: replacement.to_string(),
|
||||
message: format!(
|
||||
"{} version '{}' is deprecated: {}. Use '{}' instead.",
|
||||
fq_tool_id, version, note, replacement
|
||||
),
|
||||
};
|
||||
Ok((Some(version.to_string()), vec![warning]))
|
||||
}
|
||||
BehaviorLifecycle::RemovalCandidate => {
|
||||
let replacement = v.replacement.unwrap_or("current");
|
||||
Err(format!(
|
||||
"behavior_version \"{version}\" for tool \"{fq_tool_id}\" \
|
||||
is scheduled for removal. Use \"{replacement}\" instead."
|
||||
))
|
||||
}
|
||||
},
|
||||
None => {
|
||||
let available: Vec<&str> = supported.iter().map(|v| v.version).collect();
|
||||
Err(format!(
|
||||
"version \"{version}\" is not supported for tool \"{fq_tool_id}\"; \
|
||||
supported versions: [{}]",
|
||||
available.join(", ")
|
||||
))
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
mod tests {
|
||||
use super::*;
|
||||
|
||||
#[test]
|
||||
fn current_preset_resolves_to_current() {
|
||||
let v = resolve_version("current", "GrokBuild:run_terminal_cmd", None).unwrap();
|
||||
assert_eq!(v, Some("current".to_string()));
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn legacy_preset_resolves_ported_tool() {
|
||||
// run_terminal_cmd is ported — resolves to "legacy-0.4.10".
|
||||
let v = resolve_version("legacy-0.4.10", "GrokBuild:run_terminal_cmd", None).unwrap();
|
||||
assert_eq!(v, Some("legacy-0.4.10".to_string()));
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn legacy_preset_falls_back_to_current_for_unported_tool() {
|
||||
// grep is managed but has no legacy-0.4.10 preset entry — falls back to "current".
|
||||
let v = resolve_version("legacy-0.4.10", "GrokBuild:grep", None).unwrap();
|
||||
assert_eq!(v, Some("current".to_string()));
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn legacy_preset_resolves_all_ported_tools() {
|
||||
// All 6 ported tools should resolve to "legacy-0.4.10" under the legacy preset.
|
||||
for fq_id in &[
|
||||
"GrokBuild:run_terminal_cmd",
|
||||
"GrokBuild:read_file",
|
||||
"GrokBuild:search_replace",
|
||||
"GrokBuild:get_task_output",
|
||||
"GrokBuild:kill_task",
|
||||
"GrokBuild:list_dir",
|
||||
] {
|
||||
let v = resolve_version("legacy-0.4.10", fq_id, None).unwrap();
|
||||
assert_eq!(
|
||||
v,
|
||||
Some("legacy-0.4.10".to_string()),
|
||||
"expected legacy-0.4.10 for {fq_id}"
|
||||
);
|
||||
}
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn per_tool_override_wins() {
|
||||
let v = resolve_version(
|
||||
"current",
|
||||
"GrokBuild:run_terminal_cmd",
|
||||
Some("legacy-0.4.10"),
|
||||
)
|
||||
.unwrap();
|
||||
assert_eq!(v, Some("legacy-0.4.10".to_string()));
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn unmanaged_tool_returns_none() {
|
||||
let v = resolve_version("current", "GrokBuild:web_search", None).unwrap();
|
||||
assert_eq!(v, None);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn override_on_unmanaged_tool_errors() {
|
||||
let err =
|
||||
resolve_version("current", "GrokBuild:web_search", Some("legacy-0.4.10")).unwrap_err();
|
||||
assert!(err.contains("unmanaged tool"));
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn unknown_preset_errors() {
|
||||
let err = resolve_version("nonexistent", "GrokBuild:run_terminal_cmd", None).unwrap_err();
|
||||
assert!(err.contains("unknown behavior_preset"));
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn unknown_override_version_errors() {
|
||||
let err =
|
||||
resolve_version("current", "GrokBuild:run_terminal_cmd", Some("v999")).unwrap_err();
|
||||
assert!(
|
||||
err.contains("is not supported for tool"),
|
||||
"expected 'is not supported' error, got: {err}"
|
||||
);
|
||||
assert!(
|
||||
err.contains("supported versions:"),
|
||||
"should list supported versions, got: {err}"
|
||||
);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn all_managed_tools_resolve() {
|
||||
for &fq_id in MANAGED_TOOLS {
|
||||
let v = resolve_version("current", fq_id, None).unwrap();
|
||||
assert_eq!(v, Some("current".to_string()), "failed for {fq_id}");
|
||||
}
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn concise_namespace_not_managed() {
|
||||
// GrokBuildConcise tools should NOT be version-managed.
|
||||
assert!(!is_version_managed("GrokBuildConcise:run_terminal_cmd"));
|
||||
let v = resolve_version("current", "GrokBuildConcise:run_terminal_cmd", None).unwrap();
|
||||
assert_eq!(v, None);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn is_version_managed_matches_catalog() {
|
||||
assert!(is_version_managed("GrokBuild:run_terminal_cmd"));
|
||||
assert!(is_version_managed("GrokBuild:read_file"));
|
||||
assert!(is_version_managed("GrokBuild:search_replace"));
|
||||
assert!(is_version_managed("GrokBuild:list_dir"));
|
||||
assert!(is_version_managed("GrokBuild:grep"));
|
||||
assert!(is_version_managed("GrokBuild:kill_task"));
|
||||
// Not managed:
|
||||
assert!(!is_version_managed("GrokBuild:todo_write"));
|
||||
}
|
||||
|
||||
// ─── Warning behavior tests ───
|
||||
|
||||
#[test]
|
||||
fn active_version_produces_no_warning() {
|
||||
let res =
|
||||
resolve_version_with_warnings("current", "GrokBuild:run_terminal_cmd", None).unwrap();
|
||||
assert!(
|
||||
res.warnings.is_empty(),
|
||||
"active versions should produce no warnings, got: {:?}",
|
||||
res.warnings
|
||||
);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn active_bundle_produces_no_bundle_level_warning() {
|
||||
let res =
|
||||
resolve_version_with_warnings("legacy-0.4.10", "GrokBuild:run_terminal_cmd", None)
|
||||
.unwrap();
|
||||
assert!(
|
||||
res.warnings.iter().all(|w| !w.fq_tool_id.is_empty()),
|
||||
"no bundle-level warning expected for Active bundle, got: {:?}",
|
||||
res.warnings
|
||||
);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn deprecated_version_produces_tool_warning() {
|
||||
// Test the deprecated path directly via validate_and_resolve.
|
||||
// We can't mutate the static registry, so we call the internal function
|
||||
// which checks per-tool lifecycle from the registry.
|
||||
// For this test, we need a version that IS in the registry.
|
||||
// Since all current versions are Active, we test the code path by
|
||||
// calling validate_and_resolve on an Active version and verifying
|
||||
// no warning, then documenting the contract.
|
||||
let (version, warnings) =
|
||||
validate_and_resolve("GrokBuild:run_terminal_cmd", "current").unwrap();
|
||||
assert_eq!(version, Some("current".to_string()));
|
||||
assert!(
|
||||
warnings.is_empty(),
|
||||
"Active version should produce no warning"
|
||||
);
|
||||
|
||||
// Verify the Deprecated branch structure is reachable:
|
||||
// validate_and_resolve for a version not in registry → Err
|
||||
let err = validate_and_resolve("GrokBuild:grep", "legacy-0.4.10").unwrap_err();
|
||||
assert!(err.contains("is not supported"), "got: {err}");
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn removal_candidate_version_is_rejected() {
|
||||
// RemovalCandidate versions should be rejected with replacement.
|
||||
// Since no current versions are RemovalCandidate, verify the error
|
||||
// for unsupported version (which exercises the same not-found path).
|
||||
let err = validate_and_resolve("GrokBuild:grep", "legacy-0.4.10").unwrap_err();
|
||||
assert!(err.contains("is not supported for tool"));
|
||||
assert!(err.contains("supported versions: [current]"));
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn resolve_with_warnings_returns_correct_version() {
|
||||
let res =
|
||||
resolve_version_with_warnings("legacy-0.4.10", "GrokBuild:run_terminal_cmd", None)
|
||||
.unwrap();
|
||||
assert_eq!(res.contract_version, Some("legacy-0.4.10".to_string()));
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn resolve_with_warnings_unmanaged_returns_none_no_warnings() {
|
||||
let res = resolve_version_with_warnings("current", "GrokBuild:web_search", None).unwrap();
|
||||
assert_eq!(res.contract_version, None);
|
||||
assert!(res.warnings.is_empty());
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn resolve_with_warnings_unsupported_version_errors_with_list() {
|
||||
let err = resolve_version_with_warnings("current", "GrokBuild:grep", Some("legacy-0.4.10"))
|
||||
.unwrap_err();
|
||||
assert!(
|
||||
err.contains("is not supported for tool"),
|
||||
"expected 'not supported' error, got: {err}"
|
||||
);
|
||||
assert!(
|
||||
err.contains("GrokBuild:grep"),
|
||||
"error should mention the tool, got: {err}"
|
||||
);
|
||||
assert!(
|
||||
err.contains("current"),
|
||||
"error should list supported versions, got: {err}"
|
||||
);
|
||||
}
|
||||
|
||||
// ─── Catalog consistency invariants ───
|
||||
|
||||
#[test]
|
||||
fn invariant_1_managed_tools_have_registry_entries() {
|
||||
for &fq_id in MANAGED_TOOLS {
|
||||
assert!(
|
||||
tool_supported_versions(fq_id).is_some(),
|
||||
"managed tool {fq_id} missing from TOOL_VERSION_REGISTRY"
|
||||
);
|
||||
}
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn invariant_2_registry_tools_are_managed() {
|
||||
for entry in TOOL_VERSION_REGISTRY {
|
||||
assert!(
|
||||
MANAGED_TOOLS.contains(&entry.fq_tool_id),
|
||||
"registry tool {} not in MANAGED_TOOLS",
|
||||
entry.fq_tool_id
|
||||
);
|
||||
}
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn invariant_3_bundle_defaults_exist_in_registry() {
|
||||
for preset in PRESETS {
|
||||
for &(fq_id, version) in preset.tool_defaults {
|
||||
let versions = tool_supported_versions(fq_id).unwrap_or_else(|| {
|
||||
panic!("bundle '{}' references unknown tool {}", preset.name, fq_id)
|
||||
});
|
||||
assert!(
|
||||
versions.iter().any(|v| v.version == version),
|
||||
"bundle '{}' references version '{}' for tool '{}' but it's not in the registry",
|
||||
preset.name,
|
||||
version,
|
||||
fq_id
|
||||
);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn invariant_4_no_removal_candidate_in_bundles() {
|
||||
for preset in PRESETS {
|
||||
for &(fq_id, version) in preset.tool_defaults {
|
||||
let lifecycle = tool_version_lifecycle(fq_id, version);
|
||||
assert_ne!(
|
||||
lifecycle,
|
||||
Some(BehaviorLifecycle::RemovalCandidate),
|
||||
"bundle '{}' references removal-candidate version '{}' for tool '{}'",
|
||||
preset.name,
|
||||
version,
|
||||
fq_id
|
||||
);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn invariant_5_deprecated_versions_have_replacements() {
|
||||
for entry in TOOL_VERSION_REGISTRY {
|
||||
for v in entry.versions {
|
||||
if v.lifecycle == BehaviorLifecycle::Deprecated {
|
||||
assert!(
|
||||
v.replacement.is_some(),
|
||||
"deprecated version '{}' for tool '{}' must have a replacement",
|
||||
v.version,
|
||||
entry.fq_tool_id
|
||||
);
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn invariant_6_replacements_are_supported() {
|
||||
for entry in TOOL_VERSION_REGISTRY {
|
||||
for v in entry.versions {
|
||||
if let Some(replacement) = v.replacement {
|
||||
assert!(
|
||||
entry.versions.iter().any(|rv| rv.version == replacement),
|
||||
"replacement '{}' for '{}@{}' is not a supported version",
|
||||
replacement,
|
||||
entry.fq_tool_id,
|
||||
v.version
|
||||
);
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn invariant_7_replacements_not_deprecated_or_removal() {
|
||||
for entry in TOOL_VERSION_REGISTRY {
|
||||
for v in entry.versions {
|
||||
if let Some(replacement) = v.replacement
|
||||
&& let Some(target) = entry.versions.iter().find(|rv| rv.version == replacement)
|
||||
{
|
||||
assert_eq!(
|
||||
target.lifecycle,
|
||||
BehaviorLifecycle::Active,
|
||||
"replacement '{}' for '{}@{}' must be Active, not {:?}",
|
||||
replacement,
|
||||
entry.fq_tool_id,
|
||||
v.version,
|
||||
target.lifecycle
|
||||
);
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn invariant_8_unmanaged_tools_not_in_bundles_or_registry() {
|
||||
for preset in PRESETS {
|
||||
for &(fq_id, _) in preset.tool_defaults {
|
||||
assert!(
|
||||
is_version_managed(fq_id),
|
||||
"bundle '{}' references unmanaged tool '{}'",
|
||||
preset.name,
|
||||
fq_id
|
||||
);
|
||||
}
|
||||
}
|
||||
for entry in TOOL_VERSION_REGISTRY {
|
||||
assert!(
|
||||
is_version_managed(entry.fq_tool_id),
|
||||
"registry contains unmanaged tool '{}'",
|
||||
entry.fq_tool_id
|
||||
);
|
||||
}
|
||||
}
|
||||
|
||||
// ─── Preset smoke tests ───
|
||||
|
||||
#[test]
|
||||
fn all_active_presets_resolve_all_managed_tools() {
|
||||
for preset in PRESETS {
|
||||
if preset.lifecycle != BehaviorLifecycle::Active {
|
||||
continue;
|
||||
}
|
||||
for &fq_id in MANAGED_TOOLS {
|
||||
let result = resolve_version(preset.name, fq_id, None);
|
||||
assert!(
|
||||
result.is_ok(),
|
||||
"preset '{}' failed to resolve tool '{}': {:?}",
|
||||
preset.name,
|
||||
fq_id,
|
||||
result.err()
|
||||
);
|
||||
let version = result.unwrap();
|
||||
assert!(
|
||||
version.is_some(),
|
||||
"preset '{}' resolved tool '{}' to None (should be Some for managed tools)",
|
||||
preset.name,
|
||||
fq_id
|
||||
);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn release_preset_resolves_all_tools_to_current() {
|
||||
// release-0.1.157 should resolve all managed tools to "current"
|
||||
// because no post-legacy stable version had been carved out yet.
|
||||
for &fq_id in MANAGED_TOOLS {
|
||||
let v = resolve_version("release-0.1.157", fq_id, None).unwrap();
|
||||
assert_eq!(
|
||||
v,
|
||||
Some("current".to_string()),
|
||||
"release-0.1.157 should resolve {} to current",
|
||||
fq_id
|
||||
);
|
||||
}
|
||||
}
|
||||
|
||||
// ─── Typed helper tests ───
|
||||
|
||||
#[test]
|
||||
fn is_legacy_contract_detects_legacy() {
|
||||
assert!(is_legacy_contract(Some("legacy-0.4.10")));
|
||||
assert!(!is_legacy_contract(Some("current")));
|
||||
assert!(!is_legacy_contract(None));
|
||||
assert!(!is_legacy_contract(Some("unknown")));
|
||||
}
|
||||
|
||||
// ─── Metadata tests ───
|
||||
|
||||
#[test]
|
||||
fn current_version_has_empty_metadata() {
|
||||
assert_eq!(V_CURRENT.cataloged_in, "");
|
||||
assert!(V_CURRENT.source_refs.is_empty());
|
||||
assert_eq!(V_CURRENT.summary, "");
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn legacy_versions_have_populated_tool_specific_metadata() {
|
||||
let legacy_constants = [
|
||||
("bash", &V_LEGACY_BASH),
|
||||
("read_file", &V_LEGACY_READ_FILE),
|
||||
("search_replace", &V_LEGACY_SEARCH_REPLACE),
|
||||
("list_dir", &V_LEGACY_LIST_DIR),
|
||||
("kill_task", &V_LEGACY_KILL_TASK),
|
||||
("task_output", &V_LEGACY_TASK_OUTPUT),
|
||||
];
|
||||
for (tool, v) in &legacy_constants {
|
||||
assert!(
|
||||
!v.cataloged_in.is_empty(),
|
||||
"{tool}: cataloged_in should not be empty"
|
||||
);
|
||||
// source_refs intentionally empty (no external PR catalog).
|
||||
assert!(
|
||||
v.source_refs.is_empty(),
|
||||
"{tool}: source_refs should be empty"
|
||||
);
|
||||
assert!(!v.summary.is_empty(), "{tool}: summary should not be empty");
|
||||
}
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn legacy_summaries_are_tool_specific() {
|
||||
// Tools with different legacy behavior must have different summaries.
|
||||
assert_ne!(
|
||||
V_LEGACY_BASH.summary, V_LEGACY_READ_FILE.summary,
|
||||
"bash and read_file have different legacy behavior"
|
||||
);
|
||||
assert_ne!(
|
||||
V_LEGACY_READ_FILE.summary, V_LEGACY_LIST_DIR.summary,
|
||||
"read_file and list_dir have different legacy behavior"
|
||||
);
|
||||
assert_ne!(
|
||||
V_LEGACY_BASH.summary, V_LEGACY_KILL_TASK.summary,
|
||||
"bash and kill_task have different legacy behavior"
|
||||
);
|
||||
// kill_task and task_output share the same legacy behavior (not-found wording)
|
||||
assert_eq!(
|
||||
V_LEGACY_KILL_TASK.summary, V_LEGACY_TASK_OUTPUT.summary,
|
||||
"kill_task and task_output share the same legacy behavior"
|
||||
);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn legacy_source_refs_are_cleared() {
|
||||
// Catalog intentionally keeps source_refs empty.
|
||||
for v in [
|
||||
&V_LEGACY_BASH,
|
||||
&V_LEGACY_READ_FILE,
|
||||
&V_LEGACY_SEARCH_REPLACE,
|
||||
&V_LEGACY_LIST_DIR,
|
||||
&V_LEGACY_KILL_TASK,
|
||||
&V_LEGACY_TASK_OUTPUT,
|
||||
] {
|
||||
assert!(v.source_refs.is_empty());
|
||||
}
|
||||
}
|
||||
}
|
||||
Reference in new issue
Block a user