tea-coding-tools 0.1.0

Workspace-scoped native coding tool adapters for tea-rs
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
use std::fs;
use std::io::ErrorKind;
use std::path::{Path, PathBuf};

use crate::path::ValidatedRelativePath;
use crate::{WorkspacePathError, WorkspacePathErrorCode};

/// Validated authority to resolve tool paths beneath one canonical directory.
///
/// Construction resolves symlinks in the supplied host path and requires an
/// existing directory. Model-supplied paths are never interpreted relative to
/// the process current directory.
///
/// # TOCTOU limits
///
/// Path-based host APIs cannot make resolution and a later open or rename one
/// atomic operation. Callers performing mutations must invoke
/// [`Self::revalidate_mutation`] immediately before commit. Executors should
/// additionally prefer descriptor-relative operations where a safe portable
/// implementation is available. Unix identity checks use device/inode. The
/// portable stable Windows metadata APIs used here provide a best-effort
/// fingerprint instead of a file index. This capability fails closed on
/// detected replacement, but it does not claim to eliminate every filesystem
/// race.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct WorkspaceRoot {
    host_path: PathBuf,
    identity: ObjectIdentity,
}

impl WorkspaceRoot {
    /// Constructs a capability from an existing host directory.
    ///
    /// # Errors
    ///
    /// Returns a stable bounded error if the path is absent, is not a
    /// directory, or cannot be resolved safely.
    pub fn new(path: impl AsRef<Path>) -> Result<Self, WorkspacePathError> {
        let host_path = fs::canonicalize(path.as_ref()).map_err(|error| {
            if error.kind() == ErrorKind::NotFound {
                WorkspacePathError::new(WorkspacePathErrorCode::WorkspaceNotFound)
            } else {
                WorkspacePathError::new(WorkspacePathErrorCode::FilesystemFailure)
            }
        })?;
        let metadata = fs::metadata(&host_path)
            .map_err(|_| WorkspacePathError::new(WorkspacePathErrorCode::FilesystemFailure))?;
        if !metadata.is_dir() {
            return Err(WorkspacePathError::new(
                WorkspacePathErrorCode::WorkspaceNotDirectory,
            ));
        }
        Ok(Self {
            host_path,
            identity: ObjectIdentity::from_metadata(&metadata),
        })
    }

    /// Returns the canonical host directory represented by this capability.
    #[must_use]
    pub fn host_path(&self) -> &Path {
        &self.host_path
    }

    /// Resolves a model path that must already exist.
    ///
    /// The returned display path is normalized and workspace-relative. The
    /// host path is canonical and has passed a component-wise containment
    /// check against this capability.
    ///
    /// # Errors
    ///
    /// Rejects malformed, absolute, traversing, missing, unresolvable, or
    /// workspace-escaping paths.
    pub fn resolve_existing(&self, path: &str) -> Result<ResolvedExistingPath, WorkspacePathError> {
        self.verify_root()?;
        let relative = ValidatedRelativePath::parse(path)?;
        let candidate = relative.join_to(&self.host_path);
        let host_path = fs::canonicalize(&candidate).map_err(|error| {
            if error.kind() == ErrorKind::NotFound {
                WorkspacePathError::new(WorkspacePathErrorCode::TargetNotFound)
            } else {
                WorkspacePathError::new(WorkspacePathErrorCode::UnresolvableTarget)
            }
        })?;
        self.require_contained(&host_path)?;
        let metadata = fs::metadata(&host_path)
            .map_err(|_| WorkspacePathError::new(WorkspacePathErrorCode::UnresolvableTarget))?;
        Ok(ResolvedExistingPath {
            display_path: relative.display().to_owned(),
            host_path,
            workspace_root: self.host_path.clone(),
            identity: ObjectIdentity::from_metadata(&metadata),
        })
    }

    /// Revalidates an existing target immediately before opening it.
    ///
    /// # Errors
    ///
    /// Returns `CapabilityMismatch` for a value from another workspace and
    /// `PathChanged` if resolution or filesystem identity changed.
    pub fn revalidate_existing(
        &self,
        target: &ResolvedExistingPath,
    ) -> Result<(), WorkspacePathError> {
        if target.workspace_root != self.host_path {
            return Err(WorkspacePathError::new(
                WorkspacePathErrorCode::CapabilityMismatch,
            ));
        }
        let current = self
            .resolve_existing(target.display_path())
            .map_err(|error| match error.code() {
                WorkspacePathErrorCode::TargetNotFound
                | WorkspacePathErrorCode::UnresolvableTarget => {
                    WorkspacePathError::new(WorkspacePathErrorCode::PathChanged)
                }
                _ => error,
            })?;
        if current.host_path != target.host_path || current.identity != target.identity {
            return Err(WorkspacePathError::new(WorkspacePathErrorCode::PathChanged));
        }
        Ok(())
    }

    /// Verifies that an opened file handle identifies the resolved target.
    ///
    /// Call this with metadata obtained from the opened file handle, not by
    /// looking up its path again. It closes the validation-to-open race for the
    /// object identity on platforms that expose stable file identifiers.
    ///
    /// # Errors
    ///
    /// Returns `PathChanged` if the opened object differs from the resolved
    /// target, or `CapabilityMismatch` for a token from another workspace.
    pub fn verify_opened_existing(
        &self,
        target: &ResolvedExistingPath,
        metadata: &fs::Metadata,
    ) -> Result<(), WorkspacePathError> {
        if target.workspace_root != self.host_path {
            return Err(WorkspacePathError::new(
                WorkspacePathErrorCode::CapabilityMismatch,
            ));
        }
        self.verify_root()?;
        if ObjectIdentity::from_metadata(metadata) != target.identity {
            return Err(WorkspacePathError::new(WorkspacePathErrorCode::PathChanged));
        }
        Ok(())
    }

    /// Resolves an existing or prospective mutation target.
    ///
    /// The workspace root itself is not a valid mutation target. Existing
    /// targets are canonicalized. For a prospective target, the nearest
    /// existing ancestor is canonicalized, checked as a directory, and checked
    /// for workspace containment before unresolved components are appended.
    ///
    /// # Errors
    ///
    /// Rejects malformed, absolute, traversing, unresolvable, root-targeting,
    /// non-directory-parent, or workspace-escaping paths.
    pub fn resolve_mutation(&self, path: &str) -> Result<ResolvedMutationPath, WorkspacePathError> {
        self.verify_root()?;
        let relative = ValidatedRelativePath::parse(path)?;
        if relative.display() == "." {
            return Err(WorkspacePathError::new(
                WorkspacePathErrorCode::WorkspaceRootMutation,
            ));
        }
        let candidate = relative.join_to(&self.host_path);

        if let Ok(host_path) = fs::canonicalize(&candidate) {
            self.require_contained(&host_path)?;
            let metadata = fs::metadata(&host_path)
                .map_err(|_| WorkspacePathError::new(WorkspacePathErrorCode::UnresolvableTarget))?;
            Ok(ResolvedMutationPath {
                display_path: relative.display().to_owned(),
                host_path: host_path.clone(),
                workspace_root: self.host_path.clone(),
                target_existed: true,
                anchor_path: host_path,
                anchor_identity: ObjectIdentity::from_metadata(&metadata),
            })
        } else {
            if fs::symlink_metadata(&candidate).is_ok() {
                return Err(WorkspacePathError::new(
                    WorkspacePathErrorCode::UnresolvableTarget,
                ));
            }
            self.resolve_prospective(&relative, &candidate)
        }
    }

    /// Revalidates a mutation target immediately before its commit operation.
    ///
    /// This detects containment changes, target appearance/disappearance, and
    /// nearest-existing-ancestor replacement on supported platforms. A caller
    /// must discard the old value and resolve again after any failure.
    ///
    /// # Errors
    ///
    /// Returns `CapabilityMismatch` for a value from another workspace and a
    /// stable path error when the target no longer has the same resolution.
    pub fn revalidate_mutation(
        &self,
        target: &ResolvedMutationPath,
    ) -> Result<(), WorkspacePathError> {
        if target.workspace_root != self.host_path {
            return Err(WorkspacePathError::new(
                WorkspacePathErrorCode::CapabilityMismatch,
            ));
        }
        let current = self.resolve_mutation(target.display_path())?;
        if current.host_path != target.host_path
            || current.target_existed != target.target_existed
            || current.anchor_path != target.anchor_path
            || current.anchor_identity != target.anchor_identity
        {
            return Err(WorkspacePathError::new(WorkspacePathErrorCode::PathChanged));
        }
        Ok(())
    }

    fn resolve_prospective(
        &self,
        relative: &ValidatedRelativePath,
        candidate: &Path,
    ) -> Result<ResolvedMutationPath, WorkspacePathError> {
        let mut ancestor = candidate
            .parent()
            .ok_or_else(|| WorkspacePathError::new(WorkspacePathErrorCode::InvalidPath))?;
        loop {
            match fs::symlink_metadata(ancestor) {
                Ok(metadata) => {
                    let anchor_path = fs::canonicalize(ancestor).map_err(|_| {
                        WorkspacePathError::new(WorkspacePathErrorCode::UnresolvableTarget)
                    })?;
                    self.require_contained(&anchor_path)?;
                    let followed_metadata = fs::metadata(&anchor_path).map_err(|_| {
                        WorkspacePathError::new(WorkspacePathErrorCode::UnresolvableTarget)
                    })?;
                    if !followed_metadata.is_dir() {
                        return Err(WorkspacePathError::new(
                            WorkspacePathErrorCode::ParentNotDirectory,
                        ));
                    }
                    let suffix = candidate.strip_prefix(ancestor).map_err(|_| {
                        WorkspacePathError::new(WorkspacePathErrorCode::UnresolvableTarget)
                    })?;
                    return Ok(ResolvedMutationPath {
                        display_path: relative.display().to_owned(),
                        host_path: anchor_path.join(suffix),
                        workspace_root: self.host_path.clone(),
                        target_existed: false,
                        anchor_path,
                        anchor_identity: ObjectIdentity::from_metadata(&metadata),
                    });
                }
                Err(error) if error.kind() == ErrorKind::NotFound => {
                    ancestor = ancestor.parent().ok_or_else(|| {
                        WorkspacePathError::new(WorkspacePathErrorCode::UnresolvableTarget)
                    })?;
                }
                Err(_) => {
                    return Err(WorkspacePathError::new(
                        WorkspacePathErrorCode::FilesystemFailure,
                    ));
                }
            }
        }
    }

    fn verify_root(&self) -> Result<(), WorkspacePathError> {
        let current = fs::canonicalize(&self.host_path)
            .map_err(|_| WorkspacePathError::new(WorkspacePathErrorCode::FilesystemFailure))?;
        let metadata = fs::metadata(&current)
            .map_err(|_| WorkspacePathError::new(WorkspacePathErrorCode::FilesystemFailure))?;
        if current != self.host_path
            || !metadata.is_dir()
            || ObjectIdentity::from_metadata(&metadata) != self.identity
        {
            return Err(WorkspacePathError::new(WorkspacePathErrorCode::PathChanged));
        }
        Ok(())
    }

    fn require_contained(&self, path: &Path) -> Result<(), WorkspacePathError> {
        if path.starts_with(&self.host_path) {
            Ok(())
        } else {
            Err(WorkspacePathError::new(
                WorkspacePathErrorCode::OutsideWorkspace,
            ))
        }
    }
}

/// Verified existing workspace target.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ResolvedExistingPath {
    display_path: String,
    host_path: PathBuf,
    workspace_root: PathBuf,
    identity: ObjectIdentity,
}

impl ResolvedExistingPath {
    /// Returns the normalized workspace-relative path safe for model/UI output.
    #[must_use]
    pub fn display_path(&self) -> &str {
        &self.display_path
    }

    /// Returns the canonical contained host path.
    #[must_use]
    pub fn host_path(&self) -> &Path {
        &self.host_path
    }
}

/// Verified existing or prospective workspace mutation target.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ResolvedMutationPath {
    display_path: String,
    host_path: PathBuf,
    workspace_root: PathBuf,
    target_existed: bool,
    anchor_path: PathBuf,
    anchor_identity: ObjectIdentity,
}

impl ResolvedMutationPath {
    /// Returns the normalized workspace-relative path safe for model/UI output.
    #[must_use]
    pub fn display_path(&self) -> &str {
        &self.display_path
    }

    /// Returns the verified contained host path.
    ///
    /// For prospective targets this path is formed by appending unresolved
    /// components to the canonical nearest existing parent.
    #[must_use]
    pub fn host_path(&self) -> &Path {
        &self.host_path
    }

    /// Reports whether the final target existed when this value was resolved.
    #[must_use]
    pub const fn target_existed_at_resolution(&self) -> bool {
        self.target_existed
    }
}

#[derive(Debug, Clone, PartialEq, Eq)]
struct ObjectIdentity {
    #[cfg(unix)]
    device: u64,
    #[cfg(unix)]
    inode: u64,
    #[cfg(windows)]
    file_attributes: u32,
    #[cfg(windows)]
    creation_time: u64,
    #[cfg(windows)]
    last_write_time: u64,
    #[cfg(windows)]
    file_size: u64,
    #[cfg(not(any(unix, windows)))]
    length: u64,
    #[cfg(not(any(unix, windows)))]
    modified: Option<std::time::SystemTime>,
}

impl ObjectIdentity {
    fn from_metadata(metadata: &fs::Metadata) -> Self {
        #[cfg(unix)]
        {
            use std::os::unix::fs::MetadataExt;
            Self {
                device: metadata.dev(),
                inode: metadata.ino(),
            }
        }
        #[cfg(windows)]
        {
            use std::os::windows::fs::MetadataExt;
            Self {
                file_attributes: metadata.file_attributes(),
                creation_time: metadata.creation_time(),
                last_write_time: metadata.last_write_time(),
                file_size: metadata.file_size(),
            }
        }
        #[cfg(not(any(unix, windows)))]
        {
            Self {
                length: metadata.len(),
                modified: metadata.modified().ok(),
            }
        }
    }
}