@@ -0,0 +1,83 @@
3+App development is typically done on a fake ship. Fake ships are isolated from
4+the network. If you're developing an app that interfaces with other apps, it is
5+inconvenient to install those apps on a fake ship as well as get the necessary
6+file dependencies into your own desk. Usually it involves cloning git repos,
7+copying around a bunch of files, and fiddling with desk merging, mounting and
10+To simplify this process, a way to easily import/export desks and sets of
16+An app should be developed that allows users to export desks or sets
17+of files as jamfiles through a web UI. The jamfiles can then be imported
18+and either initialise a desk or be merged into an existing desk.
24+- Jam a desk and download its jamfile through a web UI.
25+- Be presented with all files in a desk in a similar format to the output of the
26+ `+tree` generator, select a subset of those files, and export them in a
27+ jamfile through the web UI. I would use this to create jamfiles containing
28+ dependencies for other devs who want to interface with my app.
29+- Import a jamfile by fetching it from a URL I specify or by uploading it
30+ through a file browser dialog.
31+- Create a new desk from an imported jamfile.
32+- Merge an imported jamfile into an existing desk.
34+## Implementation notes
36+- This is going to require wrangling Clay datastructures which are a little
37+ complex (but not too bad).
39+- Desk creation will have to be done with a `%park` `task:clay`, this is
40+ currently undocumented in the Clay docs as it's fairly low-level and not
41+ typically used from userspace. You can look at `new-desk:cloy` in `zuse.hoon`
42+ for how `%park` works. You can also refer to the code in [this
43+ PR](https://github.com/urbit/urbit/pull/5360) for inspiration.
45+- It may be possible to design the jamfile to only contain the desk/files, but
46+ it may need to include additional metadata such as desk name, whether it's a
47+ full desk or just a set of files, etc. It is desirable for this information to
48+ be displayed to the user before they commit it to Clay. It would probably be
49+ good for it to list the files before commit too.
51+- When the user wants to merge an imported desk into an existing one, they may
52+ need to be presented with merge strategies to choose from. It should probably
53+ default to a sane one so they don't need to think about it in most cases.
55+- When exporting, a sensible naming scheme is desirable for the jamfile so it's
58+- It is probably desirable for the user to be able to choose older desk aeons to
59+ export. You would have to handle the possibility of tombstoning with this
62+- Note: Clay no longer uses the `blob:clay` datastructure but now uses a simple
63+ `$page` in its place as defined in `arvo.hoon`. The docs are a bit out of date
64+ with this, so eg a `%blob` scry now returns a `page` rather than `blob:clay` as
67+- [Clay is reasonably well documented
68+ here.](https://developers.urbit.org/reference/arvo/clay/clay)
70+- The front-end for this could be written in sail or something like React. It
71+ mostly just needs static forms so either will probably work.
73+- The app probably doesn't need to store imports/exports in its state apart from
74+ maybe the current import temporarily if it needs to be examined for info to
79+1. Implement full desk export and create a new desk from an imported jamfile.
82+2. Implement exporting a subset of a desk's files and merging imported desks
83+ into an existing desk with the user's choice of merge strategy. (1 star)