knotra 0.30.0

knotra: multi-project VCS dashboard and bulk-operation tool.
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
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
//! Workspace definition and operation history persistence.

use knotra_vcs::model::{operation::OperationLog, workspace::Workspace};
use serde::{Deserialize, Serialize};

use crate::config::AppPaths;

/// Whether `dir`, after some directory operation has already failed to
/// reach it with `NotFound`, should still be treated as though it genuinely
/// does not exist. Windows's `read_dir` queries a compound path
/// (`dir.join("*")`, `library/std/src/sys/fs/windows.rs:1185-1196`), so a
/// directory blocked by a plain file can report the same `NotFound` kind a
/// directory that was never created reports — the same ambiguity Task 081
/// removed from `delete_workspace_file`. Resolved here the same way: by
/// asking the filesystem about `dir` itself rather than trusting the error
/// kind the failed operation happened to return. `pub(crate)` rather than
/// private: Task 083 reuses this from `config.rs::load_config`, the same
/// ambiguity one directory up again — one implementation, not two.
pub(crate) fn treat_missing_directory_as_absent(dir: &std::path::Path) -> bool {
    match std::fs::metadata(dir) {
        Ok(meta) => meta.is_dir(),
        Err(e) => e.kind() == std::io::ErrorKind::NotFound,
    }
}

// ---------------------------------------------------------------------------
// Workspace persistence
// ---------------------------------------------------------------------------

/// On-disk representation of a workspace (TOML).
#[derive(Debug, Serialize, Deserialize)]
struct WorkspaceFile {
    workspace: Workspace,
}

/// Load all workspaces from the workspaces directory.
/// Returns an empty list (not an error) when the directory does not exist.
/// A directory that exists but is blocked by something other than a
/// directory (see `treat_missing_directory_as_absent`) is an error, same as
/// any other unreadable directory.
pub fn load_workspaces(paths: &AppPaths) -> (Vec<Workspace>, Vec<String>) {
    let dir = &paths.workspaces_dir;
    let mut workspaces = Vec::new();
    let mut errors = Vec::new();

    let entries = match std::fs::read_dir(dir) {
        Ok(e) => e,
        Err(e)
            if e.kind() == std::io::ErrorKind::NotFound
                && treat_missing_directory_as_absent(dir) =>
        {
            return (workspaces, errors);
        }
        Err(e) => {
            errors.push(format!("cannot read workspaces dir: {e}"));
            return (workspaces, errors);
        }
    };

    for entry in entries.flatten() {
        let path = entry.path();
        if path.extension().and_then(|e| e.to_str()) != Some("toml") {
            continue;
        }
        match std::fs::read_to_string(&path) {
            Ok(text) => match toml::from_str::<WorkspaceFile>(&text) {
                Ok(wf) => workspaces.push(wf.workspace),
                Err(e) => errors.push(format!("{}: parse error: {e}", path.display())),
            },
            Err(e) => errors.push(format!("{}: read error: {e}", path.display())),
        }
    }

    (workspaces, errors)
}

/// Persist a workspace to disk, atomically (Handoff 033 Task A) — overwrites
/// the same `<uuid>.toml` on every edit.
pub fn save_workspace(workspace: &Workspace, paths: &AppPaths) -> Result<(), String> {
    std::fs::create_dir_all(&paths.workspaces_dir)
        .map_err(|e| format!("cannot create workspaces dir: {e}"))?;

    let file_name = format!("{}.toml", workspace.id);
    let path = paths.workspaces_dir.join(file_name);

    let wf = WorkspaceFile {
        workspace: workspace.clone(),
    };
    let text = toml::to_string_pretty(&wf).map_err(|e| format!("serialization error: {e}"))?;
    crate::atomic_write::write(&path, text).map_err(|e| format!("write error: {e}"))
}

/// Remove a persisted workspace file.
///
/// Missing files are treated as already removed so in-memory cleanup can
/// proceed for workspaces loaded before the file disappeared. `NotFound`
/// alone cannot carry that distinction on every platform: Windows maps both
/// "file not found" and "path not found" (a parent component that is not a
/// directory) to the same `NotFound` kind, where Unix reports the latter
/// distinctly. So a `NotFound` from `remove_file` is only accepted as
/// "already removed" once the workspaces directory itself is confirmed to
/// really be a directory; a workspaces directory that does not exist at all
/// is still treated as already removed, matching `load_workspaces`'s own
/// contract for that case.
pub fn delete_workspace_file(workspace: &Workspace, paths: &AppPaths) -> Result<(), String> {
    let file_name = format!("{}.toml", workspace.id);
    let path = paths.workspaces_dir.join(file_name);
    match std::fs::remove_file(&path) {
        Ok(()) => Ok(()),
        Err(e) if e.kind() == std::io::ErrorKind::NotFound => {
            match std::fs::metadata(&paths.workspaces_dir) {
                Ok(meta) if meta.is_dir() => Ok(()),
                Ok(_) => Err(format!(
                    "delete error: {} is not a directory",
                    paths.workspaces_dir.display()
                )),
                Err(e) if e.kind() == std::io::ErrorKind::NotFound => Ok(()),
                Err(e) => Err(format!("delete error: {e}")),
            }
        }
        Err(e) => Err(format!("delete error: {e}")),
    }
}

// ---------------------------------------------------------------------------
// Operation history persistence
// ---------------------------------------------------------------------------

/// Persist one operation log entry as a JSON file, atomically (Handoff 033
/// Task A) — lower severity than the config/workspace sites since each call
/// targets a fresh timestamped filename rather than overwriting one, but
/// fixed for uniformity: a torn write would otherwise leave a partial file
/// `load_recent_logs` has to skip on parse failure instead of never
/// producing one.
pub fn save_operation_log(log: &OperationLog, paths: &AppPaths) -> Result<(), String> {
    std::fs::create_dir_all(&paths.history_dir)
        .map_err(|e| format!("cannot create history dir: {e}"))?;

    let ts = log.result.started_at.format("%Y%m%dT%H%M%SZ");
    let file_name = format!("{}_{}.json", ts, log.result.operation_id);
    let path = paths.history_dir.join(file_name);

    let text =
        serde_json::to_string_pretty(log).map_err(|e| format!("serialization error: {e}"))?;
    crate::atomic_write::write(&path, text).map_err(|e| format!("write error: {e}"))
}

/// `load_recent_logs`'s result (RFC-047 D2/D3): the logs themselves plus
/// what could not be produced, so a caller can state the loss instead of
/// rendering it as silence.
pub struct LoadedLogs {
    pub logs: Vec<OperationLog>,
    /// Directory entries that could not be read or parsed as an
    /// `OperationLog`, within the most-recent-`limit` window actually
    /// requested (RFC-047 D1) — not a count of every bad file that may sit
    /// further back in the directory, unrequested.
    pub unreadable: usize,
    /// The history directory itself could not be read (e.g. a permissions
    /// failure, a missing mount, or the directory blocked by something
    /// other than a directory) — distinct from the directory never having
    /// been created, which is genuinely "no history yet" (RFC-047 D3):
    /// `save_operation_log` creates the directory on first write, so a
    /// `NotFound` here is a first run, not a loss, once confirmed by
    /// `treat_missing_directory_as_absent`.
    pub directory_unreadable: bool,
}

/// Load the most recent `limit` operation logs from the history directory.
///
/// RFC-047 D1: filters before taking. `read_dir` yields every directory
/// entry — a corrupt file, a stray `.DS_Store`, a half-written file — and
/// the previous `.take(limit)` ran before parsing, so any one of those
/// consumed a slot a valid older entry could have filled. This walks
/// entries newest-first and keeps going until `limit` *valid* logs are
/// collected (or the directory is exhausted), so `limit` means what its
/// name says.
pub fn load_recent_logs(paths: &AppPaths, limit: usize) -> LoadedLogs {
    let dir = &paths.history_dir;
    let mut entries: Vec<_> = match std::fs::read_dir(dir) {
        Ok(e) => e.flatten().collect(),
        Err(e)
            if e.kind() == std::io::ErrorKind::NotFound
                && treat_missing_directory_as_absent(dir) =>
        {
            return LoadedLogs {
                logs: Vec::new(),
                unreadable: 0,
                directory_unreadable: false,
            };
        }
        Err(_) => {
            return LoadedLogs {
                logs: Vec::new(),
                unreadable: 0,
                directory_unreadable: true,
            };
        }
    };

    // Sort descending by file name (timestamp prefix).
    entries.sort_by_key(|b| std::cmp::Reverse(b.file_name()));

    let mut logs = Vec::new();
    let mut unreadable = 0;
    for entry in entries {
        if logs.len() >= limit {
            break;
        }
        let parsed = std::fs::read_to_string(entry.path())
            .ok()
            .and_then(|text| serde_json::from_str::<OperationLog>(&text).ok());
        match parsed {
            Some(log) => logs.push(log),
            None => unreadable += 1,
        }
    }

    LoadedLogs {
        logs,
        unreadable,
        directory_unreadable: false,
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use knotra_vcs::model::operation::{
        OperationId, OperationKind, OperationResult, ProjectOperationOutcome,
        ProjectOperationResult,
    };

    fn paths_in(tmp: &tempfile::TempDir) -> AppPaths {
        AppPaths {
            config_file: tmp.path().join("config.toml"),
            workspaces_dir: tmp.path().join("workspaces"),
            history_dir: tmp.path().join("history"),
        }
    }

    /// A minimal, valid log at an explicit, controllable timestamp — RFC-047's
    /// tests need deterministic newest-first ordering, which `Utc::now()`
    /// calls a few microseconds apart cannot reliably guarantee at
    /// second-resolution filenames.
    fn log_at(seconds: i64) -> OperationLog {
        let ts = chrono::DateTime::from_timestamp(seconds, 0).unwrap();
        OperationLog {
            result: OperationResult {
                operation_id: OperationId::new(),
                kind: OperationKind::Fetch,
                started_at: ts,
                finished_at: ts,
                per_project: Vec::new(),
                rollback_attempted: false,
                rollback_succeeded: None,
            },
            recovery_hints: Vec::new(),
        }
    }

    /// A file `load_recent_logs` will encounter and fail to parse, named to
    /// sort at the given position among real log files (same
    /// `{timestamp}_{suffix}.json` shape `save_operation_log` uses).
    fn write_corrupt_file(paths: &AppPaths, seconds: i64) {
        std::fs::create_dir_all(&paths.history_dir).expect("create history dir");
        let ts = chrono::DateTime::from_timestamp(seconds, 0)
            .unwrap()
            .format("%Y%m%dT%H%M%SZ");
        let path = paths.history_dir.join(format!("{ts}_corrupt.json"));
        std::fs::write(path, "not valid json").expect("write corrupt file");
    }

    /// RFC-046 D4/R7: an entry written before D1's contract was enforced
    /// holds rendered prose in `skip_reason`, not a code. D4 chose not to
    /// migrate existing log files — this pins that decision as a test, so a
    /// later change cannot quietly start discarding or mangling pre-fix
    /// records. Covers the full chain R7 names: the record survives
    /// `save_operation_log` -> `load_recent_logs` (no panic, not dropped),
    /// and still renders through the same fallback the on-screen path uses.
    #[test]
    fn a_pre_fix_prose_skip_reason_round_trips_and_still_renders() {
        let tmp = tempfile::TempDir::new().expect("tempdir");
        let paths = paths_in(&tmp);
        let now = chrono::Utc::now();
        let prose = "このプロジェクトは今は確認できません。";

        let log = OperationLog {
            result: OperationResult {
                operation_id: OperationId::new(),
                kind: OperationKind::Fetch,
                started_at: now,
                finished_at: now,
                per_project: vec![ProjectOperationResult {
                    project_id: knotra_vcs::ProjectId::new(),
                    outcome: ProjectOperationOutcome::Skipped,
                    success: true,
                    skip_reason: Some(prose.to_owned()),
                    commands_executed: Vec::new(),
                    stdout: String::new(),
                    stderr: String::new(),
                    exit_code: None,
                    error_message: None,
                }],
                rollback_attempted: false,
                rollback_succeeded: None,
            },
            recovery_hints: Vec::new(),
        };

        save_operation_log(&log, &paths).expect("save a pre-fix record");

        let loaded = load_recent_logs(&paths, 10).logs;
        assert_eq!(loaded.len(), 1, "a pre-fix record must not be dropped");
        assert_eq!(
            loaded[0].result.per_project[0].skip_reason.as_deref(),
            Some(prose),
            "a pre-fix prose value must round-trip byte-for-byte"
        );

        let state = crate::state::AppState::new(crate::config::AppConfig::default());
        let rendered = crate::view::skip_reason_display(
            &state,
            loaded[0].result.per_project[0]
                .skip_reason
                .as_deref()
                .unwrap(),
        );
        assert_eq!(
            rendered, prose,
            "an unrecognised value must render verbatim -- no panic, no blank"
        );
    }

    /// RFC-047 D1, the reordering fix itself. Five valid logs plus one
    /// corrupt file *newer than all of them*, `limit` smaller than the
    /// total file count. At `9db1296` (before this handoff)
    /// `.take(limit)` ran before parsing, so the corrupt file — sorted
    /// first — consumed one of the 3 requested slots and this assertion
    /// failed with `left: 2, right: 3`. Confirmed by running this exact
    /// scenario against the unmodified baseline before writing the fix,
    /// reported verbatim in the review request per the handoff's request —
    /// a reordering fix whose test passes before the change was not
    /// testing the reorder.
    #[test]
    fn load_recent_logs_fills_the_limit_with_valid_logs_despite_a_newer_corrupt_file() {
        let tmp = tempfile::TempDir::new().expect("tempdir");
        let paths = paths_in(&tmp);

        for s in [100, 101, 102, 103, 104] {
            save_operation_log(&log_at(s), &paths).expect("save a valid log");
        }
        write_corrupt_file(&paths, 105); // newer than every valid log

        let loaded = load_recent_logs(&paths, 3);
        assert_eq!(
            loaded.logs.len(),
            3,
            "expected the 3 most recent VALID logs, not limit - 1"
        );
        assert_eq!(loaded.unreadable, 1);
        assert!(!loaded.directory_unreadable);
    }

    /// RFC-047 D2: a corrupt file among valid ones is reported, not just
    /// silently absorbed — the valid ones all still load (D1's slot
    /// behaviour), and the skipped count says one entry could not be read.
    #[test]
    fn load_recent_logs_reports_the_unreadable_count() {
        let tmp = tempfile::TempDir::new().expect("tempdir");
        let paths = paths_in(&tmp);

        for s in [100, 101, 102] {
            save_operation_log(&log_at(s), &paths).expect("save a valid log");
        }
        write_corrupt_file(&paths, 103);

        let loaded = load_recent_logs(&paths, 10);
        assert_eq!(loaded.logs.len(), 3, "all three valid logs must load");
        assert_eq!(loaded.unreadable, 1);
        assert!(!loaded.directory_unreadable);
    }

    /// RFC-047 D3: an unreadable directory is its own, distinct state, not
    /// indistinguishable from "no history yet". A directory that was never
    /// created (no prior `save_operation_log` call) is the first-run case
    /// and must NOT report `directory_unreadable` — only a directory that
    /// exists but genuinely cannot be read should.
    #[test]
    #[cfg(unix)]
    fn load_recent_logs_reports_an_unreadable_directory_distinctly() {
        use std::os::unix::fs::PermissionsExt;

        let tmp = tempfile::TempDir::new().expect("tempdir");
        let paths = paths_in(&tmp);
        std::fs::create_dir_all(&paths.history_dir).expect("create history dir");
        std::fs::set_permissions(&paths.history_dir, std::fs::Permissions::from_mode(0o000))
            .expect("remove read permission");

        let loaded = load_recent_logs(&paths, 10);

        // Restore permissions before the tempdir is dropped, or cleanup fails.
        std::fs::set_permissions(&paths.history_dir, std::fs::Permissions::from_mode(0o755))
            .expect("restore permission for cleanup");

        assert!(loaded.logs.is_empty());
        assert_eq!(loaded.unreadable, 0);
        assert!(
            loaded.directory_unreadable,
            "a permissions failure must be reported, not read as an empty directory"
        );
    }

    /// The other half of D3: a directory that has simply never been
    /// created is genuinely "no history yet", not an error.
    #[test]
    fn load_recent_logs_treats_a_missing_directory_as_no_history_not_an_error() {
        let tmp = tempfile::TempDir::new().expect("tempdir");
        let paths = paths_in(&tmp); // history_dir never created

        let loaded = load_recent_logs(&paths, 10);

        assert!(loaded.logs.is_empty());
        assert_eq!(loaded.unreadable, 0);
        assert!(!loaded.directory_unreadable);
    }

    /// Task 082: a history directory blocked by a plain file must not read
    /// as "no history yet" — the same ambiguity Task 081 removed from
    /// `delete_workspace_file`, one directory up. Not gated to any
    /// platform: unlike the permissions-based test above, this fixture
    /// (a plain file where the directory should be) works identically on
    /// both.
    #[test]
    fn load_recent_logs_reports_a_directory_blocked_by_a_plain_file() {
        let tmp = tempfile::TempDir::new().expect("tempdir");
        let mut paths = paths_in(&tmp);
        paths.history_dir = tmp.path().join("not-a-directory");
        std::fs::write(&paths.history_dir, "file").expect("create blocking file");

        let loaded = load_recent_logs(&paths, 10);

        assert!(loaded.logs.is_empty());
        assert_eq!(loaded.unreadable, 0);
        assert!(
            loaded.directory_unreadable,
            "a blocked directory must be reported, not read as no history yet"
        );
    }
}