Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
32 changes: 32 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,38 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0

## [Unreleased]

### Added

- **`snp organize` — non-interactive folder and favorite updates.** A shared
`update_snippet_fields` primitive mirrors the M001 delete sequence for the
local-only `folders` and `favorite` fields. `snp organize` (alias `o`) and
`snp data organize` resolve one target through the mutating selector, support
`--favorite`, `--unfavorite`, `--add-folder`, and `--remove-folder`, and emit
`--json` with `status` `updated` or `unchanged`.

### Changed

- **Shared diagnostic vocabulary and library scan (behavior-preserving).**
`validate`, `doctor`, and `repair` now share `DiagnosticSeverity`,
`DiagnosticCode`, and `DiagnosticRepairability` in `src/diagnostics.rs`, plus
`LibraryManager::scan_libraries()` for side-effect-free discovery. No diagnostic
code, message, exit code, or JSON output shape changed.
- **Shared backup copy policy.** Every snapshot, backup, and rollback-point path
now uses one copy primitive in `src/utils/atomic.rs`: symlink sources,
non-regular sources, and sources that resolve outside the configuration
directory are refused (the refusal names the path), and produced material is
fsynced under `Durability::DurableUserData`.
- **`snp repair --apply` refuses unsafe backup sources.** When the configuration
directory contains a symlinked or non-regular library file, repair fails with
exit code 1 before applying any fix, instead of silently copying the symlink
target into the pre-repair backup.
- **`snp restore` refuses unsafe pre-restore sources.** A symlinked or
non-regular library file aborts the restore before any live configuration is
modified (exit code 1), instead of skipping that entry with a warning.
- **Pre-repair backups are restorable.** `snp repair --apply` now writes a
`manifest.toml` through the same writer as `snp backup`, so the repair backup
directory is a valid `snp restore` input.

## [1.4.1] - 2026-10-25

### Added
Expand Down
10 changes: 10 additions & 0 deletions Cargo.toml
Original file line number Diff line number Diff line change
Expand Up @@ -97,6 +97,16 @@ name = "library_manager_contracts"
path = "tests/library_manager_contracts.rs"
required-features = ["test-support"]

[[test]]
name = "diagnostic_vocabulary_agreement"
path = "tests/diagnostic_vocabulary_agreement.rs"
required-features = ["test-support"]

[[test]]
name = "diagnostic_output_stability"
path = "tests/diagnostic_output_stability.rs"
required-features = ["test-support"]

[package.metadata.docs.rs]
all-features = false
default-target = "x86_64-unknown-linux-gnu"
Expand Down
11 changes: 6 additions & 5 deletions architecture/cli.md
Original file line number Diff line number Diff line change
Expand Up @@ -229,13 +229,13 @@ Routing facts worth auditing:
- **Top-level and `data` spellings share one code path.** `handle_validate`
(`src/main.rs:432`), `handle_backup` (`src/main.rs:437`), `handle_restore`
(`src/main.rs:449`), `handle_repair` (`src/main.rs:458`), `handle_status`
(`src/main.rs:465`), and `handle_delete` (`src/main.rs:477`) are the only
implementations; `Commands::Validate`
(`src/main.rs:465`), `handle_delete` (`src/main.rs:477`), and
`handle_organize` are the only implementations; `Commands::Validate`
(`src/main.rs:845-847`), `Commands::Backup` (`src/main.rs:848-850`),
`Commands::Restore` (`src/main.rs:851-853`), `Commands::Repair`
(`src/main.rs:842-844`), `Commands::Status` (`src/main.rs:854-856`),
`Commands::Delete` (`src/main.rs:909-911`) and all
six `DataCommands` arms (`src/main.rs:862-892`) call them.
seven `DataCommands` arms call them (including `organize`).
- **Commands that own their outcome return it directly** instead of falling
through to the `Ok(CliOutcome::Success)` tail at `src/main.rs:907`:
`select` (`src/main.rs:632-639`), `doctor` (`src/main.rs:794-806`),
Expand All @@ -249,7 +249,8 @@ Routing facts worth auditing:
### Canonical `*Args` structs

One canonical Clap `*Args` struct lives beside each handler — `ValidateArgs`,
`BackupArgs`, `RestoreArgs`, `RepairArgs`, `StatusArgs`, `DeleteArgs`, plus
`BackupArgs`, `RestoreArgs`, `RepairArgs`, `StatusArgs`, `DeleteArgs`,
`OrganizeArgs`, plus
`NewArgs`, `ListArgs`, `RunArgs`, `ClipArgs`, `SearchArgs`, `SelectArgs`,
`EditArgs`, `GetArgs`, `DoctorArgs`, `CronArgs`, `RegisterArgs`. `src/main.rs`
keeps only the `Commands` composition, runtime/signal/log setup, dispatch, and
Expand Down Expand Up @@ -304,7 +305,7 @@ initializes file logging plus `log_startup_info()` / `log_shutdown_info()`.
| `SuppressReadOnly` | `Minimal` | `restore --dry-run`, `repair --dry-run`, `import pet --dry-run` | `src/main.rs:944-962` |
| `SuppressReadOnly` | `Minimal` | `data validate`, `data status`, `data backup`, `data restore --dry-run`, `data repair --dry-run` | `src/main.rs:966-981` |
| `Allow` | `Logging` | `data repair`, `data restore` (non-dry-run) | `src/main.rs:982-984` |
| `Allow` | `Logging` | `new`, `run`, `clip`, `search`, `edit`, `import`, `repair`, `restore`, `premade`, `library create`, `library delete`, `library set-primary` | `src/main.rs:988-1004` |
| `Allow` | `Logging` | `new`, `run`, `clip`, `search`, `edit`, `import`, `repair`, `restore`, `delete`, `organize`, `premade`, `library create`, `library delete`, `library set-primary` | `src/main.rs` |
| `SuppressExplicitSync` | `Logging` | `sync`, `cron`, `register` | `src/main.rs:1007-1010` |
| `SuppressInternal` | `Logging` | `auto-sync-worker` | `src/main.rs:1013-1016` |
| `SuppressConfiguration` | `Logging` | `update`, `__self-replace`, `doctor`, `completions`, `shell`, `keybindings` | `src/main.rs:1019-1029` |
Expand Down
14 changes: 10 additions & 4 deletions architecture/commands/doctor_cmd.md
Original file line number Diff line number Diff line change
Expand Up @@ -54,9 +54,10 @@ Doctor uses the `CompatibilityDiagnostic` family from `src/diagnostics.rs`, **no

```rust
pub enum DiagnosticSeverity { Info, Warning, Error }
pub struct DiagnosticCode(/* validated String */);

pub struct CompatibilityDiagnostic {
pub code: String,
pub code: DiagnosticCode,
pub severity: DiagnosticSeverity,
pub message: String,
pub entry_index: Option<usize>,
Expand All @@ -66,7 +67,12 @@ pub struct CompatibilityDiagnostic {
}
```

(`src/diagnostics.rs:9-38`.) There is **no generic finding DSL**: `validate`, `doctor`, and `import` each keep their own diagnostic types and their own pass/fail semantics. What they *do* share is the classification input — `LibraryManager::inspect_library_index()` and `crate::library::find_orphaned_ids` — so the commands never disagree about the underlying state.
(`src/diagnostics.rs`.) Severity and code are the shared M003 vocabulary;
`validate` also uses `DiagnosticRepairability`. Each surface still keeps its
own report type and pass/fail semantics. Classification inputs are shared —
`LibraryManager::inspect_library_index()` / `scan_libraries()` and
`crate::library::find_orphaned_ids` — so the commands never disagree about
the underlying state.

Doctor's report is `DoctorReport` (`src/diagnostics.rs:106-145`), documented in `doctor_report.md`.

Expand Down Expand Up @@ -176,10 +182,10 @@ The only temp file doctor creates is the shell-init syntax-check fixture, which
|---|---|
| `src/commands/doctor_cmd.rs` | This command: modes, the environment audit, file analysis, strict elevation. |
| `src/commands/doctor_report.rs` | Report rendering (`DiagnosticReportFormat`, `emit_human_report`). |
| `src/diagnostics.rs` | `DoctorReport`, `CompatibilityDiagnostic`, `DiagnosticSeverity`. |
| `src/diagnostics.rs` | `DoctorReport`, `CompatibilityDiagnostic`, `DiagnosticSeverity`, `DiagnosticCode`. |
| `src/commands/pet_analysis.rs` | `read_source_file`, `parse_pet_toml`, `detect_unknown_fields`, `analyze_entry`, `detect_duplicates`. |
| `src/status_snapshot.rs` | `capture_snapshot` — the canonical sync status view. |
| `src/library/manager.rs` | `inspect_library_index` — the shared primary-state view. |
| `src/library/manager.rs` | `inspect_library_index` / `scan_libraries` — shared index and scan views. |
| `src/commands/shell_cmd.rs` | `generate_bash` / `generate_zsh` / `generate_fish`. |
| `architecture/commands/doctor_report.md` | The rendering layer. |
| `architecture/diagnostics.md` | The shared diagnostic model. |
Expand Down
66 changes: 66 additions & 0 deletions architecture/commands/organize_cmd.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,66 @@
# organize_cmd — Deterministic Folder and Favorite Updates

[← Back to Overview](../overview.md)

## Overview

`src/commands/organize_cmd.rs` updates a snippet's local-only `folders` and
`favorite` fields without a TUI. It resolves its target through the
**mutating** selector (`selector::resolve_selector`) and applies the shared
field-update primitive (`commands::update_snippet_fields`).

## CLI surface

`OrganizeArgs` (`organize_cmd.rs`), `snp organize`:

| Flag | Type | Meaning |
|------|------|---------|
| `--id` | `Option<String>` | Exact snippet ID (case-sensitive) |
| `--description-exact` | `Option<String>` | Exact description (case-insensitive) |
| `--command-exact` | `Option<String>` | Exact command text (case-insensitive) |
| `-q/--query` | `Option<String>` | Fuzzy query |
| `-l/--library` | `Option<String>` | One library name; `all` is refused |
| `--favorite` | bool | Set the favorite flag |
| `--unfavorite` | bool | Clear the favorite flag |
| `--add-folder <NAME>` | `Option<String>` | Add a folder membership |
| `--remove-folder <NAME>` | `Option<String>` | Remove a folder membership |
| `--json` | bool | Pretty `OrganizeJsonOutput` |

Exactly one selector and exactly one action flag are required. Folder names
must be non-empty after trimming and must not contain `;` (CSV ambiguity).

`OrganizeJsonOutput` is `{schema, status, id, description, library, favorite,
folders}` with `schema: 1` and `status` ∈ {`updated`, `unchanged`}.

## The shared primitive

`commands::update_snippet_fields` (`src/commands/mod.rs`) mirrors
`delete_snippet`: mutation gate, local-data lock, re-read under the lock,
lookup by identifier with `!deleted`, durable save, best-effort audit, and
auto-sync notification after commit.

No-ops (re-setting the current favorite, adding an existing folder, removing
an absent folder) return `SnippetFieldUpdateOutcome::Unchanged` **without**
rewriting the library file.

Audit action names: `favorite`, `unfavorite`, `add-folder`, `remove-folder`.

## Outcomes and exit codes

| Situation | stdout | stderr | Exit |
|-----------|--------|--------|------|
| Updated / unchanged | result document | – | 0 |
| Ambiguous selector | – | candidates | 5 |
| Not found | – | diagnostic | 3 |
| Usage (selector, action, folder name) | – | diagnostic | 2 |
| Operational failure | – | diagnostic | 1 |

There is no exit 9 analogue: an unchanged end state succeeds with
`status: "unchanged"`.

## Related modules

- `src/commands/mod.rs` — `update_snippet_fields`, `SnippetFieldMutation`
- `src/selector.rs` — mutating resolution
- `src/library/model.rs` — `folders` / `favorite` serde rules
- `docs/JSON_SCHEMAS.md` — `--json` envelope
23 changes: 15 additions & 8 deletions architecture/commands/repair_cmd.md
Original file line number Diff line number Diff line change
Expand Up @@ -82,7 +82,7 @@ pub enum RepairAction {
| `config` | `LibraryManager::new()` failed, or a library file failed to parse (`repair_cmd.rs:271-283`, `:373-385`) | `false` | Reported, never auto-applied. |
| `ids` | snippet with empty ID, or duplicate ID across libraries (`:324-352`) | `false` | Reported only — `apply_repair` cannot execute `RepairSnippetIds` either, see [Gotchas](#gotchas). |
| `timestamps` | `created_at == 0` or `updated_at == 0` (`:355-371`) | `false` | Same caveat as `ids`. |
| `primary` | primary library missing its file, or no primary set (`:392-432`) | `false` | Uses the shared `LibraryManager::inspect_library_index()` so `repair` and `validate` classify the primary state identically. |
| `primary` | primary library missing its file, or no primary set | `false` | Uses the shared `LibraryManager::scan_libraries()` so `repair` and `validate` classify the primary state identically. |
| `usage` | orphaned usage entries (`:444-453`) | `true` | Count comes from `crate::library::find_orphaned_ids`, the same classifier `validate` uses. |
| `transaction` | interrupted or legacy journals (`:461-588`) | `true` | Recovered via `crate::transaction::recover_transaction_by_id`. |
| `unsafe` | corrupt journals, unsafe artifacts, `Failed` transactions (`:466-481`, `:487-505`, `:535-552`) | `false` | Reported only; the operator must inspect the journal and artifacts manually. |
Expand Down Expand Up @@ -134,9 +134,11 @@ The report is emitted **exactly once**, after all work is complete, so JSON coun
usage.toml # copy of the usage index
```

The backup is a **plain recursive copy** (`copy_dir_recursive`, `:908-926`) — not a manifest-backed `snp backup` snapshot, and not a transaction. It is therefore **not** restorable by `snp restore` (which requires a `manifest.toml`); it is a manual escape hatch.

Note that `libraries.toml` and `usage.toml` copies use `let _ = fs::copy(...)` — a **copy failure is silently ignored** (`:895`, `:901`).
The backup is a **manifest-backed snapshot** written through the same
`atomic_write_backup` path as `snp backup`, using the shared
`read_copy_source` / `copy_file` admission half. Symlink, non-regular, and
out-of-root sources fail the repair before any mutation. The directory name
keeps the `repair-<timestamp>-<uuid>` shape and is restorable by `snp restore`.

## `apply_repair` — what each action actually does

Expand Down Expand Up @@ -218,7 +220,7 @@ pub enum RepairExitStatus {
|---|---|
| `src/commands/repair_cmd.rs` | This command: item collection, apply logic, backup, report, exit status. |
| `src/transaction.rs` | `scan_transaction_journals`, `classify_journal_recovery`, `recover_transaction_by_id`. |
| `src/library/manager.rs` | `inspect_library_index` — the shared primary-state classifier. |
| `src/library/manager.rs` | `scan_libraries` — the shared library scan (sources ∪ orphans ∪ primary). |
| `src/library/persistence.rs` | `find_orphaned_ids` / usage classifier used for the orphan count. |
| `src/usage.rs` | `UsageIndex` load / prune / save. |
| `architecture/persistence.md` | Journal states, recovery classes, lock hierarchy. |
Expand All @@ -230,7 +232,12 @@ pub enum RepairExitStatus {
- The report is emitted exactly once, after all work completes.
- A pre-repair backup of `libraries/`, `libraries.toml`, and `usage.toml` is taken before any repair is applied.
- Orphaned artifact deletion is containment-checked against `<config>/.transaction/artifacts/` and rejects symlinks (`repair_cmd.rs:688-708`).
- Primary-state and orphan-usage classification are **shared** with `validate` and `doctor` via `inspect_library_index` and `find_orphaned_ids`, so the three commands never disagree about what "orphaned" or "no primary" means.
- Primary-state and orphan-usage classification are **shared** with `validate`
and `doctor` via `scan_libraries` / `inspect_library_index` and
`find_orphaned_ids`, so the three commands never disagree about what
"orphaned" or "no primary" means. Repair also carries internal
`DiagnosticSeverity` / `DiagnosticCode` / `DiagnosticRepairability` on each
item while preserving the existing JSON `category` / `safe` envelope.
- The exit code distinguishes "found unsafe work" (`10`) from "usage error" (`2`) and from "some repairs failed" (`1`).

## Gotchas
Expand All @@ -240,7 +247,7 @@ pub enum RepairExitStatus {
- The `safe` **field on the item** is what `--apply` filters on (`repair_cmd.rs:200`); `RepairAction::is_safe()` is a separate, unused helper (`:98-110`). Do not assume the enum method drives the filter.
- **`FindingsSafe` is not `UnsafeOnly`.** A report-only run whose findings are all safe exits `0` with `FindingsSafe`; only a run that finds at least one unsafe finding exits `10` (`repair_cmd.rs:243-252`, `src/main.rs:401-414`).
- `snp repair` does **not** hold the local-data lock for the whole run, and it takes no transaction lock for the non-transaction actions. It can therefore run concurrently with a `snp backup` snapshot; only the individual actions take their own locks.
- The pre-repair backup is **not** a `snp backup` snapshot: it has no `manifest.toml` and cannot be restored with `snp restore`.
- `libraries.toml` / `usage.toml` copy failures in the pre-repair backup are swallowed (`repair_cmd.rs:895`, `:901`).
- The pre-repair backup carries a `manifest.toml` and is restorable by `snp restore`.
- Symlink / non-regular / escaped sources refuse the repair with exit code 1 before any fix is applied.
- `--library` restricts only the **library-level** checks. Transaction and orphan-artifact repairs always run against the whole transaction directory.
- A corrupt journal is reported as `unsafe` with the fix "Requires manual quarantine or deletion" (`repair_cmd.rs:466-481`) — repair will not delete a corrupt journal for you.
Loading
Loading