A monorepo management tool for the agentic ages
1(** Structured audit logging for unpac operations.
2
3 This module provides hierarchical logging with JSON serialization,
4 enabling both human-readable and machine-processable audit trails.
5
6 All unpac operations are logged with their constituent git operations,
7 timestamps, durations, and outcomes. *)
8
9(** {1 Git Operation Logging} *)
10
11(** Result of a git command *)
12type git_result = {
13 exit_code : int;
14 stdout : string;
15 stderr : string;
16}
17
18(** A single git command execution *)
19type git_operation = {
20 git_id : string; (** Unique ID for this operation *)
21 git_timestamp : float; (** Unix timestamp when started *)
22 git_cmd : string list; (** Git command args (without 'git') *)
23 git_cwd : string; (** Working directory *)
24 git_duration_ms : int; (** Duration in milliseconds *)
25 git_result : git_result; (** Command result *)
26}
27
28val git_operation_jsont : git_operation Jsont.t
29(** JSON codec for git operations *)
30
31(** {1 Unpac Operation Logging} *)
32
33(** Status of an unpac operation *)
34type status =
35 | Success
36 | Failed of string
37 | Conflict of string list
38
39val status_jsont : status Jsont.t
40
41(** Type of unpac operation *)
42type operation_type =
43 | Init
44 | Project_new
45 | Project_promote
46 | Project_set_remote
47 | Opam_add
48 | Opam_init
49 | Opam_promote
50 | Opam_update
51 | Opam_merge
52 | Opam_edit
53 | Opam_done
54 | Opam_remove
55 | Git_add
56 | Git_update
57 | Git_merge
58 | Git_remove
59 | Push
60 | Unknown of string
61
62val operation_type_jsont : operation_type Jsont.t
63
64val operation_type_to_string : operation_type -> string
65(** Convert operation type to string representation *)
66
67(** An unpac operation with its git operations *)
68type operation = {
69 id : string; (** Unique operation ID (UUID) *)
70 timestamp : float; (** Unix timestamp when started *)
71 operation_type : operation_type;
72 args : string list; (** Command arguments *)
73 cwd : string; (** Working directory *)
74 duration_ms : int; (** Total duration in milliseconds *)
75 status : status; (** Final status *)
76 git_operations : git_operation list; (** Constituent git operations *)
77}
78
79val operation_jsont : operation Jsont.t
80(** JSON codec for unpac operations *)
81
82(** {1 Audit Log} *)
83
84(** Complete audit log *)
85type log = {
86 version : string; (** Log format version *)
87 entries : operation list; (** Log entries, newest first *)
88}
89
90val log_jsont : log Jsont.t
91(** JSON codec for the complete audit log *)
92
93(** Current log format version *)
94val current_version : string
95
96(** {1 Logging API} *)
97
98(** Active operation context for accumulating git operations *)
99type context
100
101(** Start a new unpac operation.
102 Returns a context for recording git operations. *)
103val start_operation :
104 operation_type:operation_type ->
105 args:string list ->
106 cwd:string ->
107 context
108
109(** Record a git operation within the current context.
110 Call this after each git command completes. *)
111val record_git :
112 context ->
113 cmd:string list ->
114 cwd:string ->
115 started:float ->
116 result:git_result ->
117 unit
118
119(** Complete an operation successfully *)
120val complete_success : context -> operation
121
122(** Complete an operation with failure *)
123val complete_failed : context -> error:string -> operation
124
125(** Complete an operation with conflict *)
126val complete_conflict : context -> files:string list -> operation
127
128(** {1 Log File Management} *)
129
130(** Default log file path relative to project root *)
131val default_log_file : string
132
133(** Load audit log from file. Returns empty log if file doesn't exist. *)
134val load : string -> (log, string) result
135
136(** Save audit log to file *)
137val save : string -> log -> (unit, string) result
138
139(** Append an operation to the log file *)
140val append : string -> operation -> (unit, string) result
141
142(** {1 Formatting} *)
143
144(** Pretty-print an operation for terminal output *)
145val pp_operation : Format.formatter -> operation -> unit
146
147(** Pretty-print the log for terminal output *)
148val pp_log : Format.formatter -> log -> unit
149
150(** Generate HTML report from log *)
151val to_html : log -> string
152
153(** {1 Audit Manager} *)
154
155(** Manager that handles full operation lifecycle with auto-commit *)
156type manager
157
158(** Create an audit manager for the given workspace *)
159val create_manager :
160 proc_mgr:[ `Generic | `Unix ] Eio.Process.mgr_ty Eio.Resource.t ->
161 main_wt:Eio.Fs.dir_ty Eio.Path.t ->
162 manager
163
164(** Begin a new audited operation. Returns the context for recording git ops. *)
165val begin_operation :
166 manager ->
167 operation_type:operation_type ->
168 args:string list ->
169 context
170
171(** End an operation successfully. Appends to log and commits. *)
172val end_success : manager -> (operation, string) result
173
174(** End an operation with failure. Appends to log and commits. *)
175val end_failed : manager -> error:string -> (operation, string) result
176
177(** End an operation with merge conflict. Appends to log and commits. *)
178val end_conflict : manager -> files:string list -> (operation, string) result
179
180(** Get the current context if one is active *)
181val get_context : manager -> context option
182
183(** Commit the audit log to git *)
184val commit_log :
185 proc_mgr:[ `Generic | `Unix ] Eio.Process.mgr_ty Eio.Resource.t ->
186 main_wt:Eio.Fs.dir_ty Eio.Path.t ->
187 log_path:string ->
188 (unit, string) result