25 MB lightweight cross-platform database client for 100+ databases, including MySQL, PostgreSQL, SQLite, Redis, MongoDB, DuckDB, SQL Server, and Dameng. Built-in AI, MCP Server, CLI, desktop and Docker. | 轻量级跨平台数据库管理工具,支持 MySQL、PostgreSQL、SQLite、Redis、MongoDB、达梦等 100+ 数据库,提供桌面端、Docker、CLI、内置 AI 助手和 MCP。
TypeScript aicliclickhousedatabasedatabase-clientdatabase-managementdockerguimcpmongodbmysqlpostgresqlredisrustsql-serversqlitetaurivue
//! Read-only discovery and reading of user-level SKILL.md skills.
//!
//! Two roots are scanned: the default user-level root (HOME/.agents/skills) and
//! an optional user-configured custom root (Settings > AI). The service is
//! strictly read-only: there is no create/write/delete API. Skills are
//! identified by deterministic opaque ids derived from the root source and the
//! canonical relative skill directory name, so ids survive Refresh (prd.md:34).
//! Absolute paths never leave this module (prd.md:33).
//!
//! Lives in `dbx-core` rather than beside the Tauri commands because the AI
//! agent loop needs the same discovery and path-boundary logic
//! (prd 09-30-skill-listing-use-skill). `src-tauri/src/commands/user_skills.rs`
//! is a thin adapter over [`list_skills`] / [`read_skills`]; there must be
//! exactly one implementation of the containment rules, since a second copy is
//! a second place for a symlink escape to be missed.
use std::collections::HashSet;
use std::io::Read;
use std::path::{Path, PathBuf};
use serde::{Deserialize, Serialize};
use sha2::{Digest, Sha256};
pub const SKILL_FILE_NAME: &str = "SKILL.md";
/// Hard per-file safety limit: a larger SKILL.md is invalid and omitted from
/// discovery, and blocks the send when selected (prd.md:26/:37).
pub const MAX_SKILL_FILE_BYTES: u64 = 1_048_576;
/// Send-time reads take at most 1 MiB + 1 byte so a file that grows after the
/// metadata check is rejected instead of loaded unboundedly (prd.md:38).
const READ_LIMIT_BYTES: u64 = MAX_SKILL_FILE_BYTES + 1;
/// The opening frontmatter block must close within the first 64 KiB.
const FRONTMATTER_SCAN_BYTES: usize = 64 * 1024;
const DEFAULT_ROOT_PREFIX: &str = "d";
const CUSTOM_ROOT_PREFIX: &str = "c";
const ROOT_STATUS_OK: &str = "ok";
const ROOT_STATUS_MISSING: &str = "missing";
const ROOT_STATUS_INVALID: &str = "invalid";
/// Bounded failure vocabulary. Underlying I/O detail (which can contain
/// absolute paths or OS-specific text) is deliberately discarded rather than
/// forwarded, so nothing path-shaped reaches the frontend (prd.md:33).
const REASON_NOT_FOUND: &str = "not_found";
const REASON_ROOT_UNAVAILABLE: &str = "root_unavailable";
const REASON_OVERSIZED: &str = "oversized";
const REASON_NOT_UTF8: &str = "not_utf8";
const REASON_INVALID_FRONTMATTER: &str = "invalid_frontmatter";
const REASON_UNREADABLE: &str = "unreadable";
#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
#[serde(rename_all = "camelCase")]
pub struct UserSkillMeta {
pub id: String,
pub name: String,
pub description: String,
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
#[serde(rename_all = "camelCase")]
pub struct UserSkillRootListing {
/// One of "ok" | "missing" | "invalid".
pub status: String,
pub skills: Vec<UserSkillMeta>,
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
#[serde(rename_all = "camelCase")]
pub struct UserSkillsListResult {
pub default_root: UserSkillRootListing,
pub custom_root: Option<UserSkillRootListing>,
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
#[serde(rename_all = "camelCase")]
pub struct ReadUserSkill {
pub id: String,
pub name: String,
pub description: String,
pub content: String,
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
#[serde(rename_all = "camelCase")]
pub struct ReadUserSkillFailure {
pub id: String,
/// One of "not_found" | "root_unavailable" | "oversized" | "not_utf8" | "invalid_frontmatter" | "unreadable".
pub reason: String,
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
#[serde(rename_all = "camelCase")]
pub struct UserSkillsReadResult {
pub skills: Vec<ReadUserSkill>,
pub failures: Vec<ReadUserSkillFailure>,
}
/// Lists skill metadata for both roots. The default root is always scanned;
/// the custom root only when it is enabled in Settings (prd.md:27). An absent
/// root yields an empty listing rather than an error (prd.md:35).
///
/// Blocking filesystem work: callers offload it to a blocking pool.
pub fn list_skills(custom_root_enabled: bool, custom_root: Option<&str>) -> UserSkillsListResult {
let default_root = match default_skills_root() {
Some(path) => root_listing(&path, DEFAULT_ROOT_PREFIX),
None => empty_listing(ROOT_STATUS_MISSING),
};
let custom_root = if custom_root_enabled {
enabled_custom_root(custom_root).map(|path| root_listing(&path, CUSTOM_ROOT_PREFIX))
} else {
None
};
UserSkillsListResult { default_root, custom_root }
}
/// Reads the currently selected skills by id. Every id is resolved only
/// through re-derivation over a fresh scan of the owning root, so a deleted,
/// moved, or root-escaping skill fails instead of silently resolving to a
/// stale path (prd.md:37).
///
/// Blocking filesystem work: callers offload it to a blocking pool.
pub fn read_skills(ids: &[String], custom_root_enabled: bool, custom_root: Option<&str>) -> UserSkillsReadResult {
let roots = SkillRoots::resolve(custom_root_enabled, custom_root);
read_user_skills_from(ids, roots.default.as_deref(), roots.custom.as_deref())
}
/// Root resolution is injected so tests can exercise both roots without
/// depending on the developer home directory.
fn read_user_skills_from(
ids: &[String],
default_root: Option<&Path>,
custom_root: Option<&Path>,
) -> UserSkillsReadResult {
let mut skills = Vec::new();
let mut failures = Vec::new();
let mut seen_ids: HashSet<&str> = HashSet::new();
for id in ids {
// A repeated id must not inject the same skill text twice.
if !seen_ids.insert(id.as_str()) {
continue;
}
let prefix = match id.split_once('-') {
Some((prefix, _)) if prefix == DEFAULT_ROOT_PREFIX || prefix == CUSTOM_ROOT_PREFIX => prefix,
_ => {
failures.push(ReadUserSkillFailure { id: id.clone(), reason: REASON_NOT_FOUND.to_string() });
continue;
}
};
let root = match prefix {
DEFAULT_ROOT_PREFIX => default_root,
_ => custom_root,
};
let Some(root) = root else {
failures.push(ReadUserSkillFailure { id: id.clone(), reason: REASON_ROOT_UNAVAILABLE.to_string() });
continue;
};
match read_skill_from_root(root, prefix, id) {
Ok(skill) => skills.push(skill),
Err(reason) => failures.push(ReadUserSkillFailure { id: id.clone(), reason }),
}
}
UserSkillsReadResult { skills, failures }
}
fn enabled_custom_root(custom_root: Option<&str>) -> Option<PathBuf> {
let trimmed = custom_root.map(str::trim).filter(|value| !value.is_empty())?;
let canonical = std::fs::canonicalize(trimmed).ok()?;
canonical.is_dir().then_some(canonical)
}
fn default_skills_root() -> Option<PathBuf> {
Some(home_dir()?.join(".agents").join("skills"))
}
fn home_dir() -> Option<PathBuf> {
std::env::var("HOME").or_else(|_| std::env::var("USERPROFILE")).ok().map(PathBuf::from)
}
fn empty_listing(status: &str) -> UserSkillRootListing {
UserSkillRootListing { status: status.to_string(), skills: Vec::new() }
}
fn root_listing(path: &Path, prefix: &str) -> UserSkillRootListing {
match std::fs::canonicalize(path) {
Ok(canonical) if canonical.is_dir() => {
UserSkillRootListing { status: ROOT_STATUS_OK.to_string(), skills: scan_root(&canonical, prefix) }
}
Ok(_) => empty_listing(ROOT_STATUS_INVALID),
Err(_) => empty_listing(ROOT_STATUS_MISSING),
}
}
/// Scans the direct children of a canonical root. Symlink policy (prd.md:40):
/// an entry is only discoverable when its canonical target stays inside the
/// root, so a symlink that escapes the root is invisible to discovery.
///
/// The containment rules themselves live in [`scan_root_entries`]; this is only
/// the id-projection plus the listing order.
fn scan_root(canonical_root: &Path, prefix: &str) -> Vec<UserSkillMeta> {
let mut skills: Vec<UserSkillMeta> = scan_root_entries(canonical_root)
.into_iter()
.map(|entry| UserSkillMeta {
id: skill_id(prefix, &entry.dir_name),
name: entry.name,
description: entry.description,
})
.collect();
skills.sort_by(|a, b| a.name.to_lowercase().cmp(&b.name.to_lowercase()).then_with(|| a.id.cmp(&b.id)));
skills
}
/// Listing reads only the head of the file: the size gate plus a bounded
/// prefix read are enough to parse the opening frontmatter block
/// (prd.md:26 - "parse their frontmatter according to the public convention").
/// The body is never read here (prd.md:56).
fn discover_skill_metadata(path: &Path) -> Option<(String, String)> {
let stat = std::fs::metadata(path).ok()?;
if !stat.is_file() || stat.len() > MAX_SKILL_FILE_BYTES {
return None;
}
let file = std::fs::File::open(path).ok()?;
let mut bytes = Vec::new();
file.take(FRONTMATTER_SCAN_BYTES as u64).read_to_end(&mut bytes).ok()?;
parse_frontmatter(decode_prefix(&bytes, stat.len())?)
}
/// Decodes the bounded listing prefix strictly, so an unreadable file is not
/// offered as a choice (it would always fail at send time). A multi-byte
/// character cut by the prefix read is not an encoding error: when the file
/// continues past the prefix, the trailing partial character is trimmed. The
/// bytes beyond the prefix stay unvalidated here and are checked at send time.
fn decode_prefix(bytes: &[u8], file_len: u64) -> Option<&str> {
match std::str::from_utf8(bytes) {
Ok(text) => Some(text),
Err(error) if error.error_len().is_none() && file_len > bytes.len() as u64 => {
std::str::from_utf8(&bytes[..error.valid_up_to()]).ok()
}
Err(_) => None,
}
}
/// Reads and fully validates one selected skill file. The metadata size check
/// is followed by a 1 MiB + 1 byte bounded read, so a file that grows between
/// the two is rejected as oversized instead of loaded unboundedly (prd.md:38).
fn read_skill_from_root(canonical_root: &Path, prefix: &str, id: &str) -> Result<ReadUserSkill, String> {
for entry in contained_skill_dirs(canonical_root) {
if skill_id(prefix, &entry.dir_name) != id {
continue;
}
let resolved = read_contained_skill(canonical_root, prefix, &entry.dir_name, &entry.dir)?;
return Ok(ReadUserSkill {
id: resolved.id,
name: resolved.name,
description: resolved.description,
content: resolved.content,
});
}
Err(REASON_NOT_FOUND.to_string())
}
fn read_skill_file(path: &Path, id: &str) -> Result<ReadUserSkill, String> {
let stat = std::fs::metadata(path).map_err(|_| REASON_NOT_FOUND.to_string())?;
if !stat.is_file() {
return Err(REASON_NOT_FOUND.to_string());
}
if stat.len() > MAX_SKILL_FILE_BYTES {
return Err(REASON_OVERSIZED.to_string());
}
let file = std::fs::File::open(path).map_err(|_| REASON_UNREADABLE.to_string())?;
let mut bytes = Vec::new();
file.take(READ_LIMIT_BYTES).read_to_end(&mut bytes).map_err(|_| REASON_UNREADABLE.to_string())?;
if bytes.len() as u64 > MAX_SKILL_FILE_BYTES {
return Err(REASON_OVERSIZED.to_string());
}
let text = String::from_utf8(bytes).map_err(|_| REASON_NOT_UTF8.to_string())?;
let (name, description) = parse_frontmatter(&text).ok_or_else(|| REASON_INVALID_FRONTMATTER.to_string())?;
Ok(ReadUserSkill { id: id.to_string(), name, description, content: text })
}
/// Deterministic opaque id: root source prefix plus a truncated SHA-256 of the
/// canonical relative skill directory name. Stable across Refresh and restarts
/// of the registry (prd.md:34). The id carries no path material to the client.
fn skill_id(prefix: &str, dir_name: &str) -> String {
let digest = Sha256::digest(dir_name.as_bytes());
let mut id = String::from(prefix);
id.push('-');
for byte in &digest[..8] {
id.push_str(&format!("{:02x}", byte));
}
id
}
/// Parses the opening YAML frontmatter block per the public SKILL.md
/// convention: required non-empty name and description, unknown keys ignored.
/// Returns None when the block is missing, unclosed, oversized, or lacks a
/// required field (prd.md:26/:52).
fn parse_frontmatter(text: &str) -> Option<(String, String)> {
let text = text.strip_prefix("\u{feff}").unwrap_or(text);
let mut lines = text.lines();
if lines.next()?.trim_end() != "---" {
return None;
}
let mut block = String::new();
let mut closed = false;
for line in lines {
if line.trim_end() == "---" {
closed = true;
break;
}
block.push_str(line);
block.push('\n');
if block.len() > FRONTMATTER_SCAN_BYTES {
return None;
}
}
if !closed {
return None;
}
let frontmatter: SkillFrontmatter = serde_yaml_ng::from_str(&block).ok()?;
let name = frontmatter.name?.trim().to_string();
let description = frontmatter.description?.trim().to_string();
if name.is_empty() || description.is_empty() {
return None;
}
Some((name, description))
}
#[derive(Debug, Deserialize)]
struct SkillFrontmatter {
#[serde(default)]
name: Option<String>,
#[serde(default)]
description: Option<String>,
}
// ── Roots, name resolution and referencing files ──────────────────────────
//
// Added for the AI agent's `use_skill` / `read_skill_file` tools
// (prd 09-30-skill-listing-use-skill, Requirements 8-11b). Two rules hold for
// everything below:
// * the boundary is the CANONICALIZED SKILL DIRECTORY, not the root prefix,
// and it is re-validated on every read — a check done only at scan time
// leaks the first time a path is swapped underneath us;
// * no absolute path may leave this module. The agent sees relative paths.
/// Source label used in the listing and the tool arguments. Deliberately the
/// words the prompt shows (`[default]` / `[custom]`), so the model can pass back
/// exactly what it read.
const SOURCE_DEFAULT: &str = "default";
const SOURCE_CUSTOM: &str = "custom";
/// The referencing-file listing is bounded in both directions: a skill may ship
/// hundreds of files (measured: up to 60+ on this machine), and an unbounded
/// listing would spend the tool result on paths.
pub const SKILL_LISTING_MAX_ENTRIES: usize = 50;
pub const SKILL_LISTING_MAX_DEPTH: usize = 4;
/// Binary classification sniffs a prefix rather than reading the file twice.
const BINARY_SNIFF_BYTES: usize = 8 * 1024;
/// Directories that only ever hold build output or vendored dependencies.
const SKIPPED_DIR_NAMES: &[&str] = &["node_modules", "target", "dist", "build", "__pycache__", "venv"];
const REASON_NOT_TEXT: &str = "not_text";
fn source_label(prefix: &str) -> &'static str {
if prefix == CUSTOM_ROOT_PREFIX {
SOURCE_CUSTOM
} else {
SOURCE_DEFAULT
}
}
/// Canonicalized skill roots. The agent tools resolve roots here instead of
/// accepting a path from the caller, so every containment check below has one
/// trusted origin.
pub struct SkillRoots {
pub default: Option<PathBuf>,
pub custom: Option<PathBuf>,
}
impl SkillRoots {
pub fn resolve(custom_root_enabled: bool, custom_root: Option<&str>) -> Self {
let default =
default_skills_root().and_then(|path| std::fs::canonicalize(&path).ok()).filter(|path| path.is_dir());
let custom = if custom_root_enabled { enabled_custom_root(custom_root) } else { None };
Self { default, custom }
}
fn iter(&self) -> impl Iterator<Item = (&'static str, &Path)> {
[(DEFAULT_ROOT_PREFIX, self.default.as_deref()), (CUSTOM_ROOT_PREFIX, self.custom.as_deref())]
.into_iter()
.filter_map(|(prefix, root)| root.map(|root| (prefix, root)))
}
}
/// One discoverable skill, with the directory the tools need. Kept private: the
/// directory must not escape, so callers get [`ResolvedSkill`] instead.
struct ScannedSkill {
dir_name: String,
name: String,
description: String,
dir: PathBuf,
}
/// A skill the model asked for by name, already read in full.
pub struct ResolvedSkill {
pub id: String,
pub name: String,
pub description: String,
pub content: String,
pub source: &'static str,
/// Canonical skill directory. Stays inside this module (Requirement 11).
pub dir: PathBuf,
}
/// One candidate of an ambiguous name, shown back to the model so it can retry
/// with a `source` instead of the tool guessing between two real skills.
pub struct SkillCandidate {
pub name: String,
pub source: &'static str,
pub description: String,
}
pub enum SkillLookup {
Found(Box<ResolvedSkill>),
Ambiguous(Vec<SkillCandidate>),
NotFound,
}
/// One directory under a canonical root that obeys the symlink policy. This is
/// the *only* implementation of the containment rules — the discovery scan, the
/// id read and the name read all start here, so a policy fix cannot land in one
/// path and miss another.
struct ContainedSkillDir {
dir_name: String,
dir: PathBuf,
}
fn contained_skill_dirs(canonical_root: &Path) -> Vec<ContainedSkillDir> {
let mut found = Vec::new();
let Ok(entries) = std::fs::read_dir(canonical_root) else { return found };
for entry in entries.flatten() {
let dir_name = entry.file_name().to_string_lossy().to_string();
if dir_name.starts_with('.') {
continue;
}
let Ok(canonical_dir) = entry.path().canonicalize() else { continue };
if !canonical_dir.starts_with(canonical_root) || !canonical_dir.is_dir() {
continue;
}
let skill_file = canonical_dir.join(SKILL_FILE_NAME);
let Ok(canonical_skill_file) = skill_file.canonicalize() else { continue };
// A skill directory may be linked within the allowed root, but its
// entry file must obey the same containment rule. Otherwise a normal
// directory could hide a SKILL.md symlink to an arbitrary local file.
if !canonical_skill_file.starts_with(canonical_root) {
continue;
}
found.push(ContainedSkillDir { dir_name, dir: canonical_dir });
}
found
}
/// The *discoverable* skills: contained directories whose SKILL.md yields usable
/// frontmatter metadata. Discovery is deliberately NOT part of the read path —
/// see [`read_contained_skill`] — so a file that fails discovery still reports
/// its own reason (`not_utf8`, `oversized`) when read by id, which is what the
/// frozen reason vocabulary and its user-facing copy promise.
fn scan_root_entries(canonical_root: &Path) -> Vec<ScannedSkill> {
let mut found = Vec::new();
for ContainedSkillDir { dir_name, dir } in contained_skill_dirs(canonical_root) {
let Some((name, description)) = discover_skill_metadata(&dir.join(SKILL_FILE_NAME)) else { continue };
found.push(ScannedSkill { dir_name, name, description, dir });
}
found
}
/// Reads one contained skill directory, re-validating its entry file against the
/// root at read time. The scan-time verdict can be stale by the time a send or a
/// tool call arrives (another process may have swapped SKILL.md for an escaping
/// symlink), and the boundary is the canonical skill directory — not the root
/// prefix — so the check is against the root the entry actually came from.
///
/// Takes the directory rather than a discovered entry on purpose: the read path
/// must not inherit discovery's gate, or a file that failed discovery would be
/// reported as `not_found` instead of its real reason.
fn read_contained_skill(
canonical_root: &Path,
prefix: &str,
dir_name: &str,
dir: &Path,
) -> Result<ResolvedSkill, String> {
let id = skill_id(prefix, dir_name);
let canonical_skill_file = dir.join(SKILL_FILE_NAME).canonicalize().map_err(|_| REASON_NOT_FOUND.to_string())?;
if !canonical_skill_file.starts_with(canonical_root) {
return Err(REASON_NOT_FOUND.to_string());
}
let skill = read_skill_file(&canonical_skill_file, &id)?;
Ok(ResolvedSkill {
id,
name: skill.name,
description: skill.description,
content: skill.content,
source: source_label(prefix),
dir: dir.to_path_buf(),
})
}
/// Resolves a skill by the name the listing showed the model.
///
/// Matching is exact on purpose: the listing prints the frontmatter name
/// verbatim, and a fuzzy matcher would turn "did you mean" into a silent wrong
/// skill. `source` disambiguates the genuinely common case of one name living in
/// both roots; when the name is still ambiguous the caller gets the candidates
/// rather than a coin flip (Requirement 8).
pub fn read_skill_by_name(name: &str, source: Option<&str>, roots: &SkillRoots) -> SkillLookup {
let wanted = name.trim();
if wanted.is_empty() {
return SkillLookup::NotFound;
}
let mut matches: Vec<(&'static str, PathBuf, ScannedSkill)> = Vec::new();
for (prefix, root) in roots.iter() {
if source.is_some_and(|source| source != source_label(prefix)) {
continue;
}
for entry in scan_root_entries(root) {
if entry.name == wanted {
matches.push((prefix, root.to_path_buf(), entry));
}
}
}
match matches.len() {
0 => SkillLookup::NotFound,
1 => {
let (prefix, root, entry) = matches.remove(0);
// A skill that passed discovery can still fail the read-time gate
// (oversized after growth, encoding, vanished). Reported as
// not-found so no absolute path reaches the model.
match read_contained_skill(&root, prefix, &entry.dir_name, &entry.dir) {
Ok(skill) => SkillLookup::Found(Box::new(skill)),
Err(_) => SkillLookup::NotFound,
}
}
_ => SkillLookup::Ambiguous(
matches
.into_iter()
.map(|(prefix, _root, entry)| SkillCandidate {
name: entry.name,
source: source_label(prefix),
description: entry.description,
})
.collect(),
),
}
}
/// Every discoverable skill as name + source + description, in root order
/// (default, then custom) and name order inside a root. The recovery answer of a
/// failed name lookup prints the names and sources from here, and nothing else:
/// the agent must never see a path.
pub fn list_skill_candidates(roots: &SkillRoots) -> Vec<SkillCandidate> {
let mut candidates = Vec::new();
for (prefix, root) in roots.iter() {
candidates.extend(scan_root_entries(root).into_iter().map(|entry| SkillCandidate {
name: entry.name,
source: source_label(prefix),
description: entry.description,
}));
}
candidates
}
/// One entry of a skill's referencing-file listing. `bytes` and `text` are what
/// let the model decide whether reading the file is worth a second tool call.
pub struct SkillFileEntry {
pub relative_path: String,
pub bytes: u64,
pub text: bool,
}
pub struct SkillFileListing {
pub entries: Vec<SkillFileEntry>,
pub truncated: bool,
}
/// A bounded, character-addressed slice of a skill file.
pub struct SkillFileChunk {
pub content: String,
pub total_chars: usize,
pub next_offset: Option<usize>,
}
fn is_binary_prefix(bytes: &[u8]) -> bool {
bytes.contains(&0)
}
fn sniff_is_text(path: &Path) -> bool {
let Ok(file) = std::fs::File::open(path) else { return true };
let mut prefix = Vec::new();
if file.take(BINARY_SNIFF_BYTES as u64).read_to_end(&mut prefix).is_err() {
return true;
}
!is_binary_prefix(&prefix)
}
/// Lists the files a skill ships beside its SKILL.md, relative to the skill
/// directory, skipping hidden entries and build/vendor directories. Both the
/// depth and the entry count are capped; `truncated` tells the caller to say so
/// rather than present a partial listing as complete.
pub fn list_skill_files(canonical_dir: &Path) -> SkillFileListing {
let mut entries = Vec::new();
let mut truncated = false;
let mut stack = vec![(canonical_dir.to_path_buf(), 0usize)];
'outer: while let Some((current, depth)) = stack.pop() {
if depth > SKILL_LISTING_MAX_DEPTH {
continue;
}
let Ok(read) = std::fs::read_dir(¤t) else { continue };
let mut children: Vec<_> = read.flatten().collect();
children.sort_by_key(|entry| entry.file_name());
for entry in children {
let name = entry.file_name().to_string_lossy().to_string();
if name.starts_with('.') || SKIPPED_DIR_NAMES.contains(&name.as_str()) {
continue;
}
let Ok(canonical) = entry.path().canonicalize() else { continue };
// Same boundary as the scan: a link that leaves the skill directory
// is invisible, so the listing cannot advertise an outside path.
if !canonical.starts_with(canonical_dir) {
continue;
}
let Ok(metadata) = std::fs::metadata(&canonical) else { continue };
if metadata.is_dir() {
stack.push((canonical, depth + 1));
continue;
}
if !metadata.is_file() {
continue;
}
if entries.len() >= SKILL_LISTING_MAX_ENTRIES {
truncated = true;
break 'outer;
}
let Ok(relative) = canonical.strip_prefix(canonical_dir) else { continue };
entries.push(SkillFileEntry {
relative_path: relative.to_string_lossy().replace('\\', "/"),
bytes: metadata.len(),
text: sniff_is_text(&canonical),
});
}
}
entries.sort_by(|a, b| a.relative_path.cmp(&b.relative_path));
SkillFileListing { entries, truncated }
}
/// Reads one referencing file inside a skill directory.
///
/// Every rejection is a bounded reason, never an OS error string: those carry
/// absolute paths. `..` and absolute inputs are refused outright rather than
/// left to the containment check, so the intent is explicit and the reason
/// stable. A file containing a NUL byte is classified as binary and refused as
/// `not_text` (Requirement 11a) — reading a file is not permission to run it,
/// and the tool description says so.
pub fn read_skill_file_relative(canonical_dir: &Path, relative: &str) -> Result<String, String> {
let trimmed = relative.trim();
if trimmed.is_empty() {
return Err(REASON_NOT_FOUND.to_string());
}
let requested = Path::new(trimmed);
if requested.is_absolute() || trimmed.split(['/', '\\']).any(|segment| segment == "..") {
return Err(REASON_NOT_FOUND.to_string());
}
let canonical = canonical_dir.join(requested).canonicalize().map_err(|_| REASON_NOT_FOUND.to_string())?;
if !canonical.starts_with(canonical_dir) {
return Err(REASON_NOT_FOUND.to_string());
}
let stat = std::fs::metadata(&canonical).map_err(|_| REASON_NOT_FOUND.to_string())?;
if !stat.is_file() {
return Err(REASON_NOT_FOUND.to_string());
}
if stat.len() > MAX_SKILL_FILE_BYTES {
return Err(REASON_OVERSIZED.to_string());
}
let file = std::fs::File::open(&canonical).map_err(|_| REASON_UNREADABLE.to_string())?;
let mut bytes = Vec::new();
file.take(READ_LIMIT_BYTES).read_to_end(&mut bytes).map_err(|_| REASON_UNREADABLE.to_string())?;
if bytes.len() as u64 > MAX_SKILL_FILE_BYTES {
return Err(REASON_OVERSIZED.to_string());
}
// NUL is valid UTF-8, so this must run before the decode to be reachable.
if is_binary_prefix(&bytes) {
return Err(REASON_NOT_TEXT.to_string());
}
String::from_utf8(bytes).map_err(|_| REASON_NOT_UTF8.to_string())
}
/// Reads a bounded slice after applying all normal containment and file checks.
pub fn read_skill_file_relative_chunk(
canonical_dir: &Path,
relative: &str,
offset: usize,
limit: usize,
) -> Result<SkillFileChunk, String> {
// A zero limit would yield an empty chunk whose cursor never advances, so a
// caller following `next_offset` would loop forever. Treat it as one instead of
// answering `not_found`, which would blame the file for an argument. The tool
// layer rejects 0 outright with a message the model can act on, so this only
// covers direct callers.
let limit = limit.max(1);
let content = read_skill_file_relative(canonical_dir, relative)?;
let total_chars = content.chars().count();
let chunk: String = content.chars().skip(offset).take(limit).collect();
let consumed = offset.saturating_add(chunk.chars().count());
let next_offset = (consumed < total_chars).then_some(consumed);
Ok(SkillFileChunk { content: chunk, total_chars, next_offset })
}
#[cfg(test)]
mod tests {
use super::*;
const VALID_BODY: &str = "---\nname: sql-review\ndescription: Team SQL review rules\n---\n\nFollow the rules.\n";
fn temp_skills_root(tag: &str) -> PathBuf {
let root = std::env::temp_dir().join(format!("dbx-user-skills-{tag}-{}", uuid::Uuid::new_v4()));
std::fs::create_dir_all(&root).unwrap();
root
}
fn write_skill(root: &Path, dir: &str, body: &str) -> PathBuf {
let dir = root.join(dir);
std::fs::create_dir_all(&dir).unwrap();
std::fs::write(dir.join(SKILL_FILE_NAME), body).unwrap();
dir
}
fn set_file_len(skill_dir: &Path, len: u64) {
let file = std::fs::OpenOptions::new().write(true).open(skill_dir.join(SKILL_FILE_NAME)).unwrap();
file.set_len(len).unwrap();
}
#[test]
fn parses_frontmatter_and_ignores_extra_keys() {
let (name, description) =
parse_frontmatter("---\nname: \"sql-review\"\ndescription: Team rules\nmetadata:\n short: x\nallowed-tools: [read]\n---\n\nBody.\n").unwrap();
assert_eq!(name, "sql-review");
assert_eq!(description, "Team rules");
}
#[test]
fn frontmatter_must_open_and_close_at_the_top() {
assert!(parse_frontmatter("name: x\ndescription: y\n").is_none());
assert!(parse_frontmatter("---\nname: x\ndescription: y\n").is_none());
assert!(parse_frontmatter("body first\n---\nname: x\ndescription: y\n---\n").is_none());
}
#[test]
fn frontmatter_requires_name_and_description() {
assert!(parse_frontmatter("---\ndescription: only desc\n---\n").is_none());
assert!(parse_frontmatter("---\nname: only name\n---\n").is_none());
assert!(parse_frontmatter("---\nname:\ndescription: y\n---\n").is_none());
assert!(parse_frontmatter("---\nname: x\ndescription: \n---\n").is_none());
}
#[test]
fn skill_ids_are_deterministic_and_root_scoped() {
assert_eq!(skill_id("d", "alpha"), skill_id("d", "alpha"));
assert_ne!(skill_id("d", "alpha"), skill_id("c", "alpha"));
assert_ne!(skill_id("d", "alpha"), skill_id("d", "beta"));
assert!(skill_id("d", "alpha").starts_with("d-"));
assert_eq!(skill_id("d", "alpha").len(), 18);
}
#[test]
fn scan_lists_valid_skills_and_omits_others() {
let root = temp_skills_root("scan");
write_skill(&root, "alpha", VALID_BODY);
write_skill(&root, "zulu", VALID_BODY);
write_skill(&root, "nodesc", "---\nname: nodesc\n---\nbody\n");
write_skill(&root, ".hidden", VALID_BODY);
let nested = root.join("nested");
std::fs::create_dir_all(nested.join("deep")).unwrap();
std::fs::write(nested.join("deep").join(SKILL_FILE_NAME), VALID_BODY).unwrap();
let oversized = write_skill(&root, "oversized", VALID_BODY);
set_file_len(&oversized, MAX_SKILL_FILE_BYTES + 1);
let canonical = std::fs::canonicalize(&root).unwrap();
let skills = scan_root(&canonical, "d");
let names: Vec<String> = skills.iter().map(|skill| skill.name.clone()).collect();
assert_eq!(names, vec!["sql-review", "sql-review"]);
assert_ne!(skills[0].id, skills[1].id);
assert!(skills.iter().all(|skill| skill.id.starts_with("d-")));
}
#[test]
fn root_listing_reports_missing_and_invalid() {
let root = temp_skills_root("listing");
write_skill(&root, "alpha", VALID_BODY);
let missing = root_listing(&root.join("does-not-exist"), "d");
assert_eq!(missing.status, "missing");
assert!(missing.skills.is_empty());
let file_marker = root.join("plain-file.txt");
std::fs::write(&file_marker, "x").unwrap();
assert_eq!(root_listing(&file_marker, "d").status, "invalid");
assert_eq!(root_listing(&root, "d").status, "ok");
}
#[test]
fn read_returns_full_content_and_enforces_the_one_mib_boundary() {
let root = temp_skills_root("read");
let exact = write_skill(&root, "exact", VALID_BODY);
set_file_len(&exact, MAX_SKILL_FILE_BYTES);
let toobig = write_skill(&root, "toobig", VALID_BODY);
set_file_len(&toobig, MAX_SKILL_FILE_BYTES + 1);
let canonical = std::fs::canonicalize(&root).unwrap();
let exact_skill = read_skill_from_root(&canonical, "d", &skill_id("d", "exact")).unwrap();
assert_eq!(exact_skill.name, "sql-review");
assert_eq!(exact_skill.content.len(), MAX_SKILL_FILE_BYTES as usize);
assert_eq!(read_skill_from_root(&canonical, "d", &skill_id("d", "toobig")).unwrap_err(), "oversized");
}
#[test]
fn read_reports_not_found_for_missing_and_root_unavailable_for_disabled_roots() {
let root = temp_skills_root("missing");
let skill_dir = write_skill(&root, "gone", VALID_BODY);
let canonical = std::fs::canonicalize(&root).unwrap();
let id = skill_id("d", "gone");
assert!(read_skill_from_root(&canonical, "d", &id).is_ok());
std::fs::remove_dir_all(skill_dir).unwrap();
assert_eq!(read_skill_from_root(&canonical, "d", &id).unwrap_err(), "not_found");
let custom = temp_skills_root("custom");
write_skill(&custom, "team", VALID_BODY);
let custom_id = skill_id("c", "team");
let disabled = read_skills(std::slice::from_ref(&custom_id), false, Some(custom.to_str().unwrap()));
assert_eq!(disabled.failures.len(), 1);
assert_eq!(disabled.failures[0].reason, "root_unavailable");
let vanished = read_skills(&[custom_id], true, Some(custom.join("nope").to_str().unwrap()));
assert_eq!(vanished.failures[0].reason, "root_unavailable");
}
#[test]
fn read_preserves_request_order_and_collects_failures() {
// Both roots are injected: a `d-` id resolved through the real home
// directory would make this test depend on the machine it runs on.
let root = temp_skills_root("order");
write_skill(&root, "keep", VALID_BODY);
std::fs::write(root.join("plain.txt"), "x").unwrap();
let canonical = std::fs::canonicalize(&root).unwrap();
let result = read_user_skills_from(
&["d-bogus".to_string(), skill_id("d", "keep"), skill_id("d", "never-existed")],
Some(&canonical),
None,
);
assert_eq!(result.skills.len(), 1);
assert_eq!(result.skills[0].id, skill_id("d", "keep"));
assert_eq!(result.failures.len(), 2);
assert_eq!(result.failures[0].id, "d-bogus");
assert_eq!(result.failures[0].reason, "not_found");
assert_eq!(result.failures[1].reason, "not_found");
}
#[test]
fn read_skips_duplicate_ids() {
let root = temp_skills_root("dedupe");
write_skill(&root, "once", VALID_BODY);
let canonical = std::fs::canonicalize(&root).unwrap();
let id = skill_id("d", "once");
let result = read_user_skills_from(&[id.clone(), id.clone(), id], Some(&canonical), None);
assert_eq!(result.skills.len(), 1);
assert!(result.failures.is_empty());
// Deduplication must not swallow a failure: a repeated bad id is
// still reported exactly once.
let duplicated_bad = ["d-bogus".to_string(), "d-bogus".to_string()];
let failed = read_user_skills_from(&duplicated_bad, Some(&canonical), None);
assert!(failed.skills.is_empty());
assert_eq!(failed.failures.len(), 1);
assert_eq!(failed.failures[0].id, "d-bogus");
}
#[test]
fn listing_omits_a_file_that_is_not_valid_utf8() {
let root = temp_skills_root("invalid-utf8");
let dir = root.join("broken");
std::fs::create_dir_all(&dir).unwrap();
let mut bytes = b"---\nname: br".to_vec();
bytes.push(0xFF);
bytes.extend_from_slice(b"oken\ndescription: desc\n---\n\nBody.\n");
std::fs::write(dir.join(SKILL_FILE_NAME), &bytes).unwrap();
let canonical = std::fs::canonicalize(&root).unwrap();
assert!(scan_root(&canonical, "d").is_empty());
assert_eq!(read_skill_from_root(&canonical, "d", &skill_id("d", "broken")).unwrap_err(), "not_utf8");
}
#[test]
fn listing_tolerates_a_multibyte_character_cut_by_the_prefix_read() {
let root = temp_skills_root("prefix-cut");
let frontmatter = "---\nname: cut\ndescription: boundary\n---\n";
let mut body = String::from(frontmatter);
body.push_str(&"a".repeat(FRONTMATTER_SCAN_BYTES - frontmatter.len() - 1));
body.push('\u{e9}');
body.push_str(&"b".repeat(64));
write_skill(&root, "cut", &body);
let canonical = std::fs::canonicalize(&root).unwrap();
let skills = scan_root(&canonical, "d");
assert_eq!(skills.len(), 1);
assert_eq!(skills[0].name, "cut");
}
#[cfg(unix)]
#[test]
fn symlink_policy_allows_inside_root_only() {
use std::os::unix::fs::symlink;
let root = temp_skills_root("links");
write_skill(&root, "real", VALID_BODY);
symlink(root.join("real"), root.join("inside")).unwrap();
let outside = temp_skills_root("outside");
write_skill(&outside, "escapee", VALID_BODY);
symlink(outside.join("escapee"), root.join("escape")).unwrap();
let canonical = std::fs::canonicalize(&root).unwrap();
let skills = scan_root(&canonical, "d");
let ids: Vec<String> = skills.iter().map(|skill| skill.id.clone()).collect();
assert!(ids.contains(&skill_id("d", "inside")));
assert!(!ids.contains(&skill_id("d", "escape")));
}
#[cfg(unix)]
#[test]
fn skill_file_symlink_cannot_escape_the_root() {
use std::os::unix::fs::symlink;
let root = temp_skills_root("file-link");
let escape_dir = write_skill(&root, "file-escape", VALID_BODY);
let outside = temp_skills_root("file-link-outside");
let outside_file = outside.join("SKILL.md");
std::fs::write(&outside_file, VALID_BODY).unwrap();
std::fs::remove_file(escape_dir.join(SKILL_FILE_NAME)).unwrap();
symlink(&outside_file, escape_dir.join(SKILL_FILE_NAME)).unwrap();
let canonical = std::fs::canonicalize(&root).unwrap();
let id = skill_id("d", "file-escape");
assert!(!scan_root(&canonical, "d").iter().any(|skill| skill.id == id));
assert_eq!(read_skill_from_root(&canonical, "d", &id).unwrap_err(), REASON_NOT_FOUND);
}
// ── name resolution and referencing files (agent tools) ────────────────
fn write_named_skill(root: &Path, dir: &str, name: &str, description: &str) -> PathBuf {
write_skill(root, dir, &format!("---\nname: {name}\ndescription: {description}\n---\n\nBody of {name}.\n"))
}
fn roots_of(default: &Path, custom: Option<&Path>) -> SkillRoots {
SkillRoots {
default: Some(std::fs::canonicalize(default).unwrap()),
custom: custom.map(|path| std::fs::canonicalize(path).unwrap()),
}
}
#[test]
fn read_skill_by_name_resolves_a_unique_name_and_reports_its_source() {
let root = temp_skills_root("byname");
write_named_skill(&root, "alpha", "sql-review", "review rules");
let roots = roots_of(&root, None);
let SkillLookup::Found(skill) = read_skill_by_name("sql-review", None, &roots) else {
panic!("a unique name must resolve");
};
assert_eq!(skill.source, "default");
assert_eq!(skill.name, "sql-review");
assert!(skill.content.contains("Body of sql-review."));
assert_eq!(skill.dir, roots.default.clone().unwrap().join("alpha"));
assert!(skill.id.starts_with("d-"));
}
#[test]
fn read_skill_by_name_never_guesses_between_real_skills() {
let root = temp_skills_root("ambiguous");
write_named_skill(&root, "one", "shared", "first");
write_named_skill(&root, "two", "shared", "second");
let custom = temp_skills_root("ambiguous-custom");
write_named_skill(&custom, "three", "shared", "third");
let roots = roots_of(&root, Some(&custom));
let SkillLookup::Ambiguous(candidates) = read_skill_by_name("shared", None, &roots) else {
panic!("three skills share the name; the tool must list them, not pick one");
};
assert_eq!(candidates.len(), 3);
assert!(candidates.iter().any(|candidate| candidate.source == "custom"));
// `source` narrows it, but two entries in the same root stay ambiguous:
// guessing between them would be a silent wrong answer.
let SkillLookup::Ambiguous(candidates) = read_skill_by_name("shared", Some("default"), &roots) else {
panic!("two entries in one root remain ambiguous");
};
assert_eq!(candidates.len(), 2);
let SkillLookup::Found(skill) = read_skill_by_name("shared", Some("custom"), &roots) else {
panic!("source must disambiguate");
};
assert_eq!(skill.source, "custom");
assert_eq!(skill.description, "third");
}
#[test]
fn read_skill_by_name_matches_exactly_and_refuses_an_empty_name() {
let root = temp_skills_root("exact-name");
write_named_skill(&root, "alpha", "sql-review", "rules");
let roots = roots_of(&root, None);
assert!(matches!(read_skill_by_name("", None, &roots), SkillLookup::NotFound));
assert!(matches!(read_skill_by_name(" ", None, &roots), SkillLookup::NotFound));
// Exact matching is deliberate: the listing prints the name verbatim, so
// a fuzzy matcher would turn "did you mean" into a silent wrong skill.
assert!(matches!(read_skill_by_name("SQL-Review", None, &roots), SkillLookup::NotFound));
assert!(matches!(read_skill_by_name("d-abc", None, &roots), SkillLookup::NotFound));
}
#[test]
fn list_skill_candidates_reports_names_and_sources_only() {
let root = temp_skills_root("candidates");
write_named_skill(&root, "alpha", "sql-review", "rules");
let custom = temp_skills_root("candidates-custom");
write_named_skill(&custom, "beta", "team-rules", "team");
let roots = roots_of(&root, Some(&custom));
let candidates = list_skill_candidates(&roots);
let listed: Vec<(&str, &str)> =
candidates.iter().map(|candidate| (candidate.name.as_str(), candidate.source)).collect();
// Root order is fixed (default first) so the recovery answer is stable.
assert_eq!(listed, [("sql-review", "default"), ("team-rules", "custom")]);
for candidate in &candidates {
assert!(!candidate.description.is_empty());
}
}
#[test]
fn list_skill_files_uses_relative_paths_and_skips_hidden_and_vendor_dirs() {
let root = temp_skills_root("listing-files");
let dir = write_named_skill(&root, "alpha", "alpha", "d");
std::fs::create_dir_all(dir.join("references").join("deep")).unwrap();
std::fs::write(dir.join("references").join("one.md"), "one").unwrap();
std::fs::write(dir.join("references").join("deep").join("two.md"), "two").unwrap();
std::fs::write(dir.join("script.py"), "print(1)").unwrap();
std::fs::create_dir_all(dir.join("node_modules")).unwrap();
std::fs::write(dir.join("node_modules").join("dep.js"), "x").unwrap();
std::fs::create_dir_all(dir.join(".hidden")).unwrap();
std::fs::write(dir.join(".hidden").join("secret.md"), "x").unwrap();
let binary = vec![0x89u8, b'P', b'N', b'G', 0, 1, 2, 3];
std::fs::write(dir.join("logo.png"), &binary).unwrap();
let canonical = std::fs::canonicalize(&dir).unwrap();
let listing = list_skill_files(&canonical);
let paths: Vec<&str> = listing.entries.iter().map(|entry| entry.relative_path.as_str()).collect();
assert_eq!(paths, vec!["SKILL.md", "logo.png", "references/deep/two.md", "references/one.md", "script.py"]);
// The model must be able to paste the path straight back into
// read_skill_file, so separators are normalized regardless of platform.
assert!(listing.entries.iter().all(|entry| !entry.relative_path.contains('\\')));
assert!(!listing.truncated);
let png = listing.entries.iter().find(|entry| entry.relative_path == "logo.png").unwrap();
assert!(!png.text, "a NUL byte marks the file as binary");
assert_eq!(png.bytes, binary.len() as u64);
assert!(listing.entries.iter().find(|entry| entry.relative_path == "script.py").unwrap().text);
}
#[test]
fn list_skill_files_reports_truncation_instead_of_a_partial_list() {
let root = temp_skills_root("listing-cap");
let dir = write_named_skill(&root, "many", "many", "d");
for index in 0..SKILL_LISTING_MAX_ENTRIES + 5 {
std::fs::write(dir.join(format!("file-{index:03}.md")), "x").unwrap();
}
let canonical = std::fs::canonicalize(&dir).unwrap();
let listing = list_skill_files(&canonical);
assert_eq!(listing.entries.len(), SKILL_LISTING_MAX_ENTRIES);
assert!(listing.truncated, "a capped listing must say so rather than look complete");
}
#[test]
fn read_skill_file_chunk_returns_cursor_without_splitting_utf8() {
let root = temp_skills_root("chunk");
let dir = write_skill(&root, "alpha", VALID_BODY);
std::fs::write(dir.join("reference.md"), "甲乙丙丁戊己").unwrap();
let canonical = std::fs::canonicalize(&root).unwrap();
let first = read_skill_file_relative_chunk(&canonical.join("alpha"), "reference.md", 0, 2).unwrap();
assert_eq!(first.content, "甲乙");
assert_eq!(first.total_chars, 6);
assert_eq!(first.next_offset, Some(2));
let last = read_skill_file_relative_chunk(&canonical.join("alpha"), "reference.md", 2, 10).unwrap();
assert_eq!(last.content, "丙丁戊己");
assert_eq!(last.next_offset, None);
}
#[test]
fn read_skill_file_relative_reads_inside_the_skill_directory_only() {
let root = temp_skills_root("read-rel");
let dir = write_named_skill(&root, "alpha", "alpha", "d");
std::fs::create_dir_all(dir.join("references")).unwrap();
std::fs::write(dir.join("references").join("one.md"), "reference body").unwrap();
std::fs::write(root.join("outside.md"), "outside body").unwrap();
let canonical = std::fs::canonicalize(&dir).unwrap();
assert_eq!(read_skill_file_relative(&canonical, "references/one.md").unwrap(), "reference body");
assert!(read_skill_file_relative(&canonical, "SKILL.md").unwrap().contains("name: alpha"));
// Escapes and absolutes are refused outright rather than left to the
// containment check, so the reason stays stable across platforms.
// The Windows-shaped absolute path matters: `is_absolute` is false for
// "/etc/hosts" there, and the containment check is what catches it.
for escape in [
"../outside.md",
"references/../../outside.md",
"..\\outside.md",
"/etc/hosts",
"C:\\Windows\\win.ini",
" ",
] {
assert_eq!(
read_skill_file_relative(&canonical, escape).unwrap_err(),
REASON_NOT_FOUND,
"must reject {escape:?}"
);
}
// A directory and a missing name are both not-found, never a read.
assert_eq!(read_skill_file_relative(&canonical, "references").unwrap_err(), REASON_NOT_FOUND);
assert_eq!(read_skill_file_relative(&canonical, "nope.md").unwrap_err(), REASON_NOT_FOUND);
}
#[test]
fn read_skill_file_relative_refuses_binary_oversized_and_non_utf8_files() {
let root = temp_skills_root("read-reject");
let dir = write_named_skill(&root, "alpha", "alpha", "d");
let canonical = std::fs::canonicalize(&dir).unwrap();
std::fs::write(dir.join("with-nul.md"), b"text\0more").unwrap();
assert_eq!(read_skill_file_relative(&canonical, "with-nul.md").unwrap_err(), REASON_NOT_TEXT);
// No NUL here, so this must fall through to the encoding check rather
// than being mistaken for binary.
std::fs::write(dir.join("broken.md"), [0xFFu8, 0xFE]).unwrap();
assert_eq!(read_skill_file_relative(&canonical, "broken.md").unwrap_err(), REASON_NOT_UTF8);
let big = dir.join("big.md");
std::fs::write(&big, "x").unwrap();
std::fs::OpenOptions::new().write(true).open(&big).unwrap().set_len(MAX_SKILL_FILE_BYTES + 1).unwrap();
assert_eq!(read_skill_file_relative(&canonical, "big.md").unwrap_err(), REASON_OVERSIZED);
}
#[cfg(unix)]
#[test]
fn read_skill_file_relative_cannot_follow_a_link_out_of_the_skill_directory() {
use std::os::unix::fs::symlink;
let root = temp_skills_root("rel-link");
let dir = write_named_skill(&root, "alpha", "alpha", "d");
let outside = temp_skills_root("rel-link-outside");
let outside_file = outside.join("secret.md");
std::fs::write(&outside_file, "secret").unwrap();
symlink(&outside_file, dir.join("link.md")).unwrap();
symlink(&outside, dir.join("linkdir")).unwrap();
let canonical = std::fs::canonicalize(&dir).unwrap();
assert_eq!(read_skill_file_relative(&canonical, "link.md").unwrap_err(), REASON_NOT_FOUND);
assert_eq!(read_skill_file_relative(&canonical, "linkdir/secret.md").unwrap_err(), REASON_NOT_FOUND);
let listing = list_skill_files(&canonical);
assert!(!listing.entries.iter().any(|entry| entry.relative_path.starts_with("link")));
}
// ── Windows reparse-point equivalents ──────────────────────────────────
//
// The `#[cfg(unix)]` tests above are COMPILED OUT on Windows rather than
// skipped at runtime (`0 ignored` in a Windows run proves it), which would
// leave the containment rule untested on the platform DBX ships — and that
// rule is what stops `read_skill_file` (model-controlled input) from reading
// an arbitrary local file. A directory junction is a reparse point that
// `std::fs::canonicalize` (`GetFinalPathNameByHandleW`) resolves exactly
// like a symlink, and creating one needs no
// SeCreateSymbolicLinkPrivilege, so the directory cases run unconditionally
// here instead of behind a privilege check.
//
// Still uncovered on Windows, deliberately: a FILE-level link. `symlink_file`
// needs Developer Mode or that privilege, and a junction cannot stand in for
// it, so a test that creates one either fails on every machine without the
// privilege or passes while asserting nothing. The containment check runs on
// the canonicalized path and is indifferent to which reparse point produced
// it, so what the junction tests leave unverified is narrow — that Windows
// resolves file symlinks exactly as it resolves junctions in `canonicalize`.
// Hard links stay uncovered on every platform: `canonicalize` does not reveal
// their target at all.
#[cfg(windows)]
fn create_junction(link: &Path, target: &Path) {
// `mklink` is a cmd builtin and refuses to overwrite, so callers only
// pass paths that cannot exist yet. A failing junction creation is a loud
// failure, never a silent skip: a green test that asserts nothing is
// worse than a red one.
let output = std::process::Command::new("cmd")
.args(["/C", "mklink", "/J"])
.arg(link)
.arg(target)
.output()
.expect("cmd must be runnable to create a junction");
assert!(
output.status.success(),
"junction creation failed: {}{}",
String::from_utf8_lossy(&output.stdout),
String::from_utf8_lossy(&output.stderr)
);
}
#[cfg(windows)]
#[test]
fn junction_policy_allows_inside_root_only() {
let root = temp_skills_root("junction-links");
let real = write_skill(&root, "real", VALID_BODY);
create_junction(&root.join("inside"), &real);
let outside = temp_skills_root("junction-outside");
let escapee = write_skill(&outside, "escapee", VALID_BODY);
create_junction(&root.join("escape"), &escapee);
let canonical = std::fs::canonicalize(&root).unwrap();
let ids: Vec<String> = scan_root(&canonical, "d").into_iter().map(|skill| skill.id).collect();
assert!(ids.contains(&skill_id("d", "inside")));
assert!(!ids.contains(&skill_id("d", "escape")), "a junction out of the root must stay invisible");
}
#[cfg(windows)]
#[test]
fn junction_inside_a_skill_directory_cannot_be_read_or_listed() {
let root = temp_skills_root("junction-rel");
let dir = write_named_skill(&root, "alpha", "alpha", "d");
let outside = temp_skills_root("junction-rel-outside");
std::fs::write(outside.join("secret.md"), "secret").unwrap();
create_junction(&dir.join("linkdir"), &outside);
let canonical = std::fs::canonicalize(&dir).unwrap();
assert_eq!(read_skill_file_relative(&canonical, "linkdir/secret.md").unwrap_err(), REASON_NOT_FOUND);
let listing = list_skill_files(&canonical);
assert!(!listing.entries.iter().any(|entry| entry.relative_path.starts_with("linkdir")));
}
}