@@ -0,0 +1,102 @@
1++++
2+title = "Importing and exporting desks as jamfiles"
3+date = "2022-09-25"
4+
5+[taxonomies]
6+grant_type = [ "Bounty" ]
7+grant_category = [ "App Dev" ]
8+
9+[extra]
10+image = ""
11+description = "Eth-provider is a Gall agent that allows Urbit users to configure their Ethereum connection."
12+reward = "2 stars"
13+champion = ["~tinnus-napbus"]
14+assignee = [""]
15+grant_id = "B0187"
16+completed = false
17+work_request_link="https://airtable.com/shr4qt9t9kz7RaOIa?prefill_Grant+ID=B0187&prefill_Grant+Name=Desk%20jamfile%20import%2Fexport"
18++++
19+
20+## Rationale
21+
22+App development is typically done on a fake ship. Fake ships are isolated from
23+the network. If you're developing an app that interfaces with other apps, it is
24+inconvenient to install those apps on a fake ship as well as get the necessary
25+file dependencies into your own desk. Usually it involves cloning git repos,
26+copying around a bunch of files, and fiddling with desk merging, mounting and
27+editing.
28+
29+To simplify this process, a way to easily import/export desks and sets of
30+files is necessary.
31+
32+
33+## Overview
34+
35+An app should be developed that allows users to export desks or sets
36+of files as jamfiles through a web UI. The jamfiles can then be imported
37+and either initialise a desk or be merged into an existing desk.
38+
39+## User stories
40+
41+As a user, I can:
42+
43+- Jam a desk and download its jamfile through a web UI.
44+- Be presented with all files in a desk in a similar format to the output of the
45+ `+tree` generator, select a subset of those files, and export them in a
46+ jamfile through the web UI. I would use this to create jamfiles containing
47+ dependencies for other devs who want to interface with my app.
48+- Import a jamfile by fetching it from a URL I specify or by uploading it
49+ through a file browser dialog.
50+- Create a new desk from an imported jamfile.
51+- Merge an imported jamfile into an existing desk.
52+
53+## Implementation notes
54+
55+- This is going to require wrangling Clay datastructures which are a little
56+ complex (but not too bad).
57+
58+- Desk creation will have to be done with a `%park` `task:clay`, this is
59+ currently undocumented in the Clay docs as it's fairly low-level and not
60+ typically used from userspace. You can look at `new-desk:cloy` in `zuse.hoon`
61+ for how `%park` works. You can also refer to the code in [this
62+ PR](https://github.com/urbit/urbit/pull/5360) for inspiration.
63+
64+- It may be possible to design the jamfile to only contain the desk/files, but
65+ it may need to include additional metadata such as desk name, whether it's a
66+ full desk or just a set of files, etc. It is desirable for this information to
67+ be displayed to the user before they commit it to Clay. It would probably be
68+ good for it to list the files before commit too.
69+
70+- When the user wants to merge an imported desk into an existing one, they may
71+ need to be presented with merge strategies to choose from. It should probably
72+ default to a sane one so they don't need to think about it in most cases.
73+
74+- When exporting, a sensible naming scheme is desirable for the jamfile so it's
75+ obvious what it is.
76+
77+- It is probably desirable for the user to be able to choose older desk aeons to
78+ export. You would have to handle the possibility of tombstoning with this
79+ though.
80+
81+- Note: Clay no longer uses the `blob:clay` datastructure but now uses a simple
82+ `$page` in its place as defined in `arvo.hoon`. The docs are a bit out of date
83+ with this, so eg a `%blob` scry now returns a `page` rather than `blob:clay` as
84+ the docs say.
85+
86+- [Clay is reasonably well documented
87+ here.](https://developers.urbit.org/reference/arvo/clay/clay)
88+
89+- The front-end for this could be written in sail or something like React. It
90+ mostly just needs static forms so either will probably work.
91+
92+- The app probably doesn't need to store imports/exports in its state apart from
93+ maybe the current import temporarily if it needs to be examined for info to
94+ display to the user.
95+
96+## Milestones & Compenstation
97+
98+1. Implement full desk export and create a new desk from an imported jamfile.
99+ (1 star)
100+
101+2. Implement exporting a subset of a desk's files and merging imported desks
102+ into an existing desk with the user's choice of merge strategy. (1 star)