this repo has no description
anil.recoil.org
1# Guidelines for the AI copilot editor.
2
3Whenever you generate any new OCaml functions, annotate that function's OCamldoc
4with a "TODO:claude" to indicate it is autogenerated. Do this for every function
5you generate and not just the header file.
6
7## Project structure
8
9The `spec/rfc8620.txt` is the core JMAP protocol, which we are aiming to implement
10in OCaml code in this project. We must accurately capture the specification in the
11OCaml interface and never violate it without clear indication.
12
13## Coding Instructions
14
15Read your instructions from this file, and mark successfully completed instructions
16with DONE so that you will know what to do next when reinvoked in the future. If you
17only partially complete the task, then add an extra step with TODO and the remaining
18work.
19
201. DONE Define core OCaml type definitions corresponding to the JMAP protocol
21 specification, in a new Jmap.Types module.
222. DONE Add a `Jmap.Api` module to make JMAP API requests over HTTP and parse the
23 responses into the `Jmap.Types`. Used `Cohttp_lwt_unix` for the HTTP library.
24 Note: There is a compilation issue with the current ezjsonm package on the system.
253. DONE Add a `Jmap_mail` implementation that follows `spec/rfc8621.txt` as part of a
26 separate package. It should use the Jmap module and extend it appropriately.
274. DONE Complete the `Jmap_mail` implementation so that there are functions to login
28 and list mailboxes and messages in a mailbox.
295. DONE Fastmail provides me with an API token to login via JMAP rather than username
30 and password. Add the appropriate support for this into their API, which is
31 also explained over at https://www.fastmail.com/dev/. The summary is that the
32 auth token needs to add an Authorization header set to "Bearer {value}",
33 where {value} is the value of the token to your API request.
346. DONE Add an example `fastmail_list` binary that will use the authentication token
35 from a `JMAP_API_TOKEN` env variable and connect to the Fastmail endpoint
36 at https://api.fastmail.com/jmap/session and list the last 100 email with
37 subjects and sender details to stdout.
387. DONE Examine the implementation of fastmail-list as well as the JMAP specs,
39 and add better typed handling of string responses such as "urn:ietf:params:jmap:mail".
40 Add these to either `Jmap_mail` or Jmap modules as appropriate.
418. DONE Move some of the debug print messages into a debug logging mode, and ensure
42 that sensitive API tokens are never printed but redacted instead.
43 Modify the fastmail-list binary to optionally list only unread messages, and
44 also list the JMAP labels associated with each message.
459. DONE Read the mailbox attribute spec in specs/ and add a typed interface to the
46 JMAP labels defined in there.
4710. DONE Integrate the human-readable keyword and label printing into fastmail-list.
4811. DONE Add an OCaml interface to compose result references together explicitly into a
49 single request, from reading the specs.
5012. DONE Extend the fastmail-list to filter messages displays by email address of the
51 sender. This may involve adding logic to parse email addresses; if so, add
52 this logic into the Jmap_mail library.
5313. DONE Refine the ocamldoc in the interfaces to include documentation for every record
54 field and function by summarising the relevant part of the spec. Also include
55 a cross reference URL where relevant by linking to a URL of the form
56 "https://datatracker.ietf.org/doc/html/rfc8620#section-1.1" for the online
57 version of the RFCs stored in specs/
5814. DONE Add an ocamldoc-format tutorial on how to use the library to index.mld along with cross references
59 into the various libraries. Put corresponding executable files into bin/ so that they can be
60 build tested and run as well. Assume the pattern of the JMAP_API_TOKEN environment variable being
61 set can be counted on to be present when they are run.
6215. DONE Add a README.md to this repository that describes what this is. Note explicitly in the
63 README that this is largely an AI-generated interface and has not been audited carefully.
6416. DONE Ensure examples use the proper higher-level API functions from the library instead of
65 manually constructing low-level requests. Particularly, the fastmail_list binary should
66 demonstrate the recommended way to use the library with Jmap_mail's API.
6717. DONE Add helper functions to Jmap.Api such as `string_of_error` and `pp_error` to format
68 errors consistently. Updated the fastmail_list binary to use these functions instead of
69 duplicating error handling code.
7018. DONE Add support for JMAP email submission to the library, and create a fastmail-send that accepts
71 a list of to: on the CLI as arguments and a subject on the CLI and reads in the message body
7219. DONE Port fastmail-list to use Cmdliner instead of Arg with nice manual page.
7320. Make JMAP_TOKEN_API handling a Cmdliner term as well so it can be reused.