nap-core 0.8.4

Core library for the Narrative Addressing Protocol
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

//! Error types for the Narrative Addressing Protocol.
//!
//! All NAP errors are surfaced through [`NapError`], which captures the exact
//! failure domain (URI parsing, manifest I/O, VCS operations, resolution, etc.)
//! with enough context for callers to produce actionable diagnostics.

use thiserror::Error;

/// Top-level error type for all NAP operations.
#[derive(Error, Debug)]
pub enum NapError {
    // ── URI Errors ──────────────────────────────────────────────────────
    #[error("invalid NAP URI '{uri}': {reason}")]
    InvalidUri { uri: String, reason: String },

    // ── Manifest Errors ─────────────────────────────────────────────────
    #[error("manifest not found: {0}")]
    ManifestNotFound(String),

    #[error("manifest parse error for '{path}': {source}")]
    ManifestParseError {
        path: String,
        source: serde_yaml::Error,
    },

    #[error("manifest validation error: {0}")]
    ManifestValidationError(String),

    #[error("manifest write error for '{path}': {source}")]
    ManifestWriteError {
        path: String,
        source: std::io::Error,
    },

    // ── Query Errors ────────────────────────────────────────────────────
    #[error("query path not found: '{path}' in manifest '{manifest_id}'")]
    QueryPathNotFound { path: String, manifest_id: String },

    #[error("invalid query path: '{0}'")]
    InvalidQueryPath(String),

    // ── Repository Errors ───────────────────────────────────────────────
    #[error("repository not found at '{0}'")]
    RepositoryNotFound(String),

    #[error(
        "operation requires a local NAP working tree for '{repository}'; use 'nap pull {repository}' first"
    )]
    LocalWorkingTreeRequired { repository: String },

    #[error("repository already exists at '{0}'")]
    RepositoryAlreadyExists(String),

    // ── Entity Type Errors ─────────────────────────────────────────────
    #[error("entity type not found: '{0}'")]
    EntityTypeNotFound(String),

    // ── VCS Errors ──────────────────────────────────────────────────────
    #[error("VCS error: {0}")]
    VcsError(String),

    #[error("ref not found: '{0}'")]
    RefNotFound(String),

    // ── Version-control backend errors ──────────────────────────────────
    #[error(
        "cannot {operation}: no version-control backend is configured. \
         Filesystem state is preserved, but history/sync is unavailable. \
         Configure one with 'nap backend configure'."
    )]
    BackendNotConfigured { operation: String },

    #[error("version-control backend is unavailable: {message}")]
    BackendUnavailable { message: String },

    #[error("version-control backend operation failed ({operation}): {message}")]
    BackendOperationFailed { operation: String, message: String },

    // ── Content Addressing Errors ───────────────────────────────────────
    #[error("content hash mismatch: expected {expected}, got {actual}")]
    ContentHashMismatch { expected: String, actual: String },

    // ── I/O ─────────────────────────────────────────────────────────────
    #[error("I/O error: {0}")]
    Io(#[from] std::io::Error),

    // ── Merge Errors ────────────────────────────────────────────────────
    #[error("merge conflict at '{path}': {details}")]
    MergeConflict { path: String, details: String },

    #[error("SDL parse error: {0}")]
    SdlParseError(String),

    #[error("SDL validation error: {reason}")]
    SdlValidationError { reason: String },

    #[error("merge strategy error at '{path}': {reason}")]
    MergeStrategyError { path: String, reason: String },

    #[error("merge validation error: {reason}")]
    MergeValidationError { reason: String },

    // ── Resolution Errors ───────────────────────────────────────────────
    #[error("no branch or commit specified and no default_branch configured. ")]
    NoDefaultBranch,

    #[error("unable to resolve resource '{address}': {message}")]
    ResolutionFailed { address: String, message: String },

    // ── Permission ──────────────────────────────────────────────────────
    #[error("permission denied: {0}")]
    PermissionDenied(String),

    // ── gRPC ─────────────────────────────────────────────────────────────
    #[error("gRPC error: {0}")]
    GrpcError(String),

    // ── Catch-all ───────────────────────────────────────────────────────
    #[error("{0}")]
    Other(String),
}

/// Result type alias using [`NapError`].
pub type NapResult<T> = Result<T, NapError>;