[[docs]] first-pass on updating documentation to the new desktop version.

Author: soapdog

docs/_sidebar.md

@@ -10,6 +10,8 @@
 - [Packages](packages/)
 - [Privacy Policy](privacy-policy.md)
 - Release Notes
+  - [Version 2022.9.3-alpha](release_notes/2022.9.3-alpha.md)
+  - [Version 2022.9.2-alpha](release_notes/2022.9.2-alpha.md)
   - [Version 2022.9.1-alpha](release_notes/2022.9.1-alpha.md)
   - [Version 2022.4.1](release_notes/2022.4.1.md)
   - [Version 2022.2.1](release_notes/2022.2.1.md)

docs/development/README.md

@@ -16,8 +16,8 @@ The driving ideas behind Patchfox are:
 
 The way Patchfox works is:
 
-1. A core set of low-level code, which should be changed as infrequently as possible, provides features to the packages. It can be found in the `src/core` folder.
-2. Everything a user interacts with is provided by a package from `src/packages`.
+1. A core set of low-level code, which should be changed as infrequently as possible, provides features to the packages. It can be found in the `ui/core` folder.
+2. Everything a user interacts with is provided by a package from `ui/packages`.
 
 The main avenues for contribution are:
 

docs/development/app-development.md

@@ -5,14 +5,14 @@ Apps are self-contained [packages](/development/packages.md). They are accessibl
 ![application launcher](d-launcher.png)
 _Application Launcher_
 
-Before you can create a new mini-app, you should study the [packages documentation](/development/packages.md) and the source code for one of the included mini-apps. The [Books](https://github.com/soapdog/patchfox/tree/master/ui/packages/books) mini-app is a good place to start because it has many of the features you might want to learn how to implement.
+Before you can create a new mini-app, you should study the [packages documentation](/development/packages.md) and the source code for one of the included mini-apps. The [Books](https://github.com/soapdog/patchfox/tree/master/ui/packages/books) mini-app is a good place to start because it is a good example of a self-contained application with many features.
 
 What makes a package a mini-app is the inclusion of: `app: true` in its `patchfox.package()` declaration. This will place it on the _Launcher_.
 
 ## Steps to create a new mini-app
 
-1. Create a folder for your mini-app under `src/packages/`. The name of the folder should match the name of the mini-app (which is also the name of the package).
+1. Create a folder for your mini-app under `ui/packages/`. The name of the folder should match the name of the mini-app (which is also the name of the package).
 2. Don't forget to include `app: true` in the `patchfox.package()` declaration.
-3. Create a _default view_ for your package. It should be a Svelte view. Add it with `view: myDefaultView` in the declaration. This is the view that the _Launcher_ loads when a user launches your app.
+3. Create a _default view_ for your package. It should be a Mithril component. Add it with `view: myDefaultView` in the declaration. This is the view that the _Launcher_ loads when a user launches the app.
 4. Include a nice icon. :-)
 5. Only packages added to `ui/packages/packages.js` will be loaded.

docs/development/building.md

@@ -42,6 +42,7 @@ After saving Patchfox will then try loading your public feed. You need to have a
 * `npm run builder:*` many different scripts to build binaries for each platform.
 * `npm run docs`: builds the documentation.
 * `npm run localbuild`: builds the CSS, the docs, and binaries for various platforms on your local machine. 
+* `npm run release`: Makes a new release and upload it to Github.
 
 # Testing the protocol schemas
 

docs/development/core.md

@@ -1,8 +1,8 @@
 # Patchfox Core
 
-The _core_ contains the low-level code that supports the [Patchfox packaging system](/development/packages.md). The source lives in `src/core`. The best way to understand it is to learn about how the folders are organized.
+The _core_ contains the low-level code that supports the [Patchfox packaging system](/development/packages.md). The source lives in `ui/core`. The best way to understand it is to learn about how the folders are organized.
 
-## `src/ui/core/components`
+## `ui/core/components`
 
 This mess is the collection of reusable [Mithril](https://mithril.js.org) components that make up the UI for the packages.
 
@@ -14,27 +14,27 @@ Some of current reusable components are:
 * **GenericMsg**: This is the component used to generically render a message of an unknown type.
 * **MessageDropdown**: This is a "kebab" or "three-dots" menu, used by all messages to provide a list of options.
 * **MessageRaw**: This component renders a message in plain text. The above Dropdown component provides an option to view this component.
-* **MessageRenderer**: This is the jack-of-all-trades message rendering component that will select the correct _card view_ for the given _message type_. These _card views_ come from the packages inside `src/ui/packages/`.
+* **MessageRenderer**: This is the jack-of-all-trades message rendering component that will select the correct _card view_ for the given _message type_. These _card views_ come from the packages inside `ui/packages/`.
 * **QueryRepeater**: Lots of views are just a collection of messages obtained with an _SSB query_. This is a handy component to render them.
 * **VoteCounter**: The component to show _likes_ on a message.
 * **Timestamp**: Just a convenient way to render timestamps.
 
-## `src/ui/kernel`
+## `ui/core/kernel`
 
 Patchfox has a kernel that provides the `patchfox.*` API used by the packages. This should eventually get its own documentation page.
 
 The kernel is responsible for the routines for preference handling, navigation, menu and event handling, and package loading.
 
 You need to be doing something very deep to find yourself in this folder. Most code here has not seen any changes in years.
 
-## `src/ui/platforms/nodejs-ssb`
+## `ui/core/platforms/nodejs-db1`
 
 It's been a longtime dream of mine to support other protocols beyond SSB. To make that more feasible, I created a _platforms_ folder and placed the _ssb core_ inside it.
 
 The _ssb core_ provides the `ssb.*` APIs to Patchfox. There is a lot of work to do there because it's messy, has a lot of dead code, and a ton of duplication.
 
-The main idea behind this folder is to be able to support different SSB backends such as _go ssb_ and the new _db2_. This is also where IPFS and Hyper code will live once I bring them back in.
+This folder will also enable Patchfox to support different SSB backends such as _go ssb_ and the new _db2_. This is also where IPFS and Hyper code will live once I bring them back in.
 
-## `src/ui/runtimes`
+## `ui/core/runtimes`
 
 At the moment this is just a placeholder waiting for when I add _Lua_ and _Scheme_ to Patchfox again.

docs/development/packages.md

@@ -8,7 +8,7 @@ Below is an excerpt from [this message](ssb:message/sha256/hYLSp_zPkvUj2f3DMk9vz
 
 Many SSB apps are developed as monoliths with tight interdependence between their various parts and features. There is nothing wrong with that, and it's a reasonable way of developing a cohesive application. Patchfox has been through many rewrites (and it probably needs a couple more) but the current version has coalesced into something that resembles an application platform.
 
-There is a [_core_](https://github.com/soapdog/patchfox/tree/master/src/core) which provides the necessary core features upon which the rest of Patchfox is built. Inside them you'll find the shared components and the platforms. Patchfox is designed in a way that makes it possible to plug in additional platforms such as Hyper or IPFS in the future.
+There is a [_core_](https://github.com/soapdog/patchfox/tree/master/ui/core) which provides the necessary core features upon which the rest of Patchfox is built. Inside it, you'll find the kernel, the shared components, and the platforms. Patchfox is designed in a way that makes it possible to plug in additional platforms such as Hyper or IPFS in the future.
 
 These resources from `core` do not provide features for the user. All they do is create a blank slate on which miniature applications can coexist and avoid interfering with each other.
 
@@ -20,7 +20,7 @@ Everything in Patchfox is provided by a package.
 
 ![Patchfox main sourcetree](d-patchfox-sourcetree.png)
 
-As can be seen on the above screenshot, Patchfox's main source tree is divided between the _core_ and _packages_. A file called [`package.js`](https://github.com/soapdog/patchfox/blob/master/src/ui/packages/packages.js) dictates which packages are loaded. By changing this file, you can customize the features you need, and how the user's experience should be.
+As can be seen on the above screenshot, Patchfox's main source tree is divided between the _core_ and _packages_. A file called [`package.js`](https://github.com/soapdog/patchfox/blob/master/ui/packages/packages.js) dictates which packages are loaded. By changing this file, you can customize the features you need, and how the user's experience should be.
 
 ## Looking closer into some packages
 
@@ -32,11 +32,11 @@ In the screenshot below, the _hub feature_ (highlighted in red) provides the _fe
 
 ![screenshot showing the menus from hub package](d-hub-package.png)
 
-Zooming into the [hub](https://github.com/soapdog/patchfox/tree/master/src/ui/packages/hub) package folder, we can quickly see that it is providing some feed views: mentions, popular, public, thread, and channel. It also provides a `channelCard` which is a specialised view that can appear inside any feed browser. So when you're browsing SSB and see a line saying _This person subscribed to channel whatever._, that is from the `channelCard`.
+Zooming into the [hub](https://github.com/soapdog/patchfox/tree/master/ui/packages/hub) package folder, we can quickly see that it is providing some feed views: mentions, popular, public, thread, and channel. It also provides a `channelCard` which is a specialised view that can appear inside any feed browser. So when you're browsing SSB and see a line saying _This person subscribed to channel whatever._, that is from the `channelCard`.
 
 ![hub package folder screenshot](d-hub-source.png)
 
-All packages have a file named after the package that holds its configuration. In the case of hub, it is called [`hub.js`](https://github.com/soapdog/patchfox/blob/master/src/packages/hub/hub.js). It will list all the views and it is also used to assemble the hub menu.
+All packages have a file named after the package that holds its configuration. In the case of hub, it is called [`hub.js`](https://github.com/soapdog/patchfox/blob/master/ui/packages/hub/hub.js). It will list all the views, and it is also used to assemble the hub menu.
 
 A developer can completely replace that package, or turn off features, without dealing with the other packages (with the caveat that some packages will attempt to redirect the user to views from hub, but as long as your new package follows a similar API it should be OK).
 

docs/packages/README.md

@@ -6,8 +6,8 @@ These are the packages that Patchfox is loading.
 * [KoFiIntegration](/packages/KoFiIntegration/)
 * [blog](/packages/blog/)
 * [books](/packages/books/)
-* [calendar](/packages/calendar/)
 * [errorHandler](/packages/errorHandler/)
+* [calendar](/packages/calendar/)
 * [contacts](/packages/contacts/)
 * [firstTimeSetup](/packages/firstTimeSetup/)
 * [githubIntegration](/packages/githubIntegration/)
@@ -23,9 +23,9 @@ These are the packages that Patchfox is loading.
 * [reindexingDialog](/packages/reindexingDialog/)
 * [search](/packages/search/)
 * [settings](/packages/settings/)
-* [settings-old](/packages/settings-old/)
 * [sourcehutIntegration](/packages/sourcehutIntegration/)
-* [statusBar](/packages/statusBar/)
 * [system](/packages/system/)
+* [statusBar](/packages/statusBar/)
 * [vote](/packages/vote/)
 * [zine](/packages/zine/)
+* [settings-old](/packages/settings-old/)

docs/release_notes/2022.9.2-alpha.md

@@ -0,0 +1,25 @@
+# Release 2022.9.2-alpha
+
+This is a complete rework of Patchfox. I've outlined the challenges and decisions regarding the future of Patchfox in [Patchfox reborn as a desktop app](https://andregarzia.com/2022/05/Patchfox-reborn-as-a-desktop-app.html). 
+
+Patchfox is now an Electron-based application. What you're using now is an alpha quality release.
+
+# WARNINGS
+
+This is an alpha version of Patchfox.
+
+This version uses `db1`, it is not compatible with existing `db2` installations such as Manyverse and Perihelion.
+
+Patchfox will attempt to use your current installed identity. You can choose to let Patchfox run its own server or keep using  other SSB clients as a server for Patchfox. The setup dialog will ask you that. Patchfox will reindex the database if needed. This process might take a while (there is a dialog showing the progress). If you switch back from Patchfox to Patchwork, Patchwork will reindex the database to its taste.
+
+Patchfox saves its configuration to `~/.ssb/patchfox.toml`, this file is sensitive, **IT HAS YOUR SECRET/KEYS IN IT**. Patchfox can use multiple identities and you can set it up so that it uses a totally different identity than the one installed in the local machine. Because of that, instead of assuming you want to use the current `~/.ssb/secret` as an identity Patchfox will ask you about it during _setup_, and store whatever keys you chose to use in its own configuration file.
+
+**DO NOT SHARE THAT FILE.**
+
+## Changes
+
+oh boy...
+
+## I SAID CHANGES
+
+Okay, besides the whole _Patchfox is now a desktop app_ change, I've replaced all Svelte-based code with [Mithril](https://mithril.js.org)-based code. That means that Patchfox no longer requires a build system to transpile its source code into something a browser can understand. This makes development a lot faster and also makes it easier to reason about the code.

docs/release_notes/2022.9.3-alpha.md

@@ -0,0 +1,5 @@
+# Pre-release 2022.9.3-alpha
+
+## Fixes
+
+* Done a first-pass on the documentation, updating it for the new codebase.

docs/troubleshooting/no-configuration.md

@@ -1,28 +1,32 @@
-# No Configuration
-
-To use Patchfox, you need to configure it with your Secure Scuttlebutt secret and remote. The easiest way to do it is by <a href="#" id="options-trigger">going to the Add-on options page for Patchfox</a>, there you can use the button labeled <i>Select Secret</i> to browse for your `.ssb/secret` file. Your remote and keys will be acquired from that file.
-
-The <i>.ssb</i> folder is a hidden folder and your system might not display it to you by default. 
-
-## How to show hidden files on macOS
-
-* If you're running Sierra or later macOS, you can press <code>CMD + SHIFT + .</code> to toggle the display of hidden files on Finder (or on a file selection dialog). You'll be able to select the file named <code>secret</code>
-* If you're running an earlier version of macOS then you can press <code>CMD + OPTION + G</code> on the file selection dialog to open a <b>location sheet</b> that allows you to type in what folder do you want to open, you can then type <code>~/.ssb/</code> and confirm. You should then be directed to that folder where you'll be able to select the file named <code>secret</code>.
-
-## How to show hidden files on Windows 10
-
-1. Open File Explorer from the taskbar. 
-2. Select View > Options > Change folder and search options.
-3. Select the View tab and, in Advanced settings, select Show hidden files, folders, and drives and OK.
-
-Check <a href="https://support.microsoft.com/en-gb/help/4028316/windows-view-hidden-files-and-folders-in-windows-10">this page for more information</a>.
-
-## How to show hidden files on Linux
-Oh my, it kinda depends on some factors but I believe that it should be viewable by default on most Linux distros. Please reach back to me with feedback on this if you're running Linux.
-
-## How to fix this
-
-* <a href="#" id="options-trigger">Go to the Add-on options page for Patchfox</a> and add your remote and keys.
-* Want a more hands-on guide on configuring and using Patchfox? Try the [Getting Started](guide.md) guide.
-
-<script src="/docs/help.js">
+# No Configuration
+
+To use Patchfox, you need to configure it with your Secure Scuttlebutt secret and remote. If this is your first time using a SSB client, don't worry Patchfox will set it all up for you. If you're already a SSB user, you'll need to tell Patchfox what identity to use.
+
+Patchfox will attempt to load the default identity that is usually stored on `~/.ssb/secret`. It will show a _setup screen_ on the first-run that lets you confirm that you want to use that identity and also enable or disable the built-in server. If you don't enable the built-in server, you'll need to run your own SSB server.
+
+If you went through setup already but want to change something. Quit Patchfox, delete the file `~/.ssb/patchfox.toml` — which is where Patchfox saves its data — and start the application again. The _setup dialog_ will appear.
+
+The <i>.ssb</i> folder is a hidden folder and your system might not display it to you by default. 
+
+## How to show hidden files on macOS
+
+* If you're running Sierra or later macOS, you can press <code>CMD + SHIFT + .</code> to toggle the display of hidden files on Finder (or on a file selection dialog). You'll be able to select the file named <code>secret</code>
+* If you're running an earlier version of macOS then you can press <code>CMD + OPTION + G</code> on the file selection dialog to open a <b>location sheet</b> that allows you to type in what folder do you want to open, you can then type <code>~/.ssb/</code> and confirm. You should then be directed to that folder where you'll be able to select the file named <code>secret</code>.
+
+## How to show hidden files on Windows 10
+
+1. Open File Explorer from the taskbar. 
+2. Select View > Options > Change folder and search options.
+3. Select the View tab and, in Advanced settings, select Show hidden files, folders, and drives and OK.
+
+Check <a href="https://support.microsoft.com/en-gb/help/4028316/windows-view-hidden-files-and-folders-in-windows-10">this page for more information</a>.
+
+## How to show hidden files on Linux
+Oh my, it kinda depends on some factors but I believe that it should be viewable by default on most Linux distros. Please reach back to me with feedback on this if you're running Linux.
+
+## How to fix this
+
+* Quit the application, delete the file called `patchfox.toml` inside the `.ssb` folder inside your home folder. Start Patchfox again and go through the first-run setup process.
+* Want a more hands-on guide on configuring and using Patchfox? Try the [Getting Started](guide.md) guide.
+
+<script src="/docs/help.js">

docs/troubleshooting/no-connection.md

@@ -1,16 +1,21 @@
-# Can't connect to _sbot_
-
-_sbot_ also known as _ssb-server_ is the server that does all the peer to peer networking in Secure Scuttlebutt. Even though we call it a server, it is just a program running on your machine. Other Secure Scuttlebutt application such as [Patchwork](https://github.com/ssbc/patchwork) or [Patchbay](https://github.com/ssbc/patchbay) start their own embedded server when they launch (unless instructed otherwise). Unfortunately, browser add-ons cannot bundle [ssb-server](https://www.npmjs.com/package/ssb-server) for it would be a security risk if all add-ons started bundling their own server. 
-
-Because of that, Patchfox is a _bring your own sbot_ client. You must start _sbot_ on your own. You can do it from the command line if you have the [ssb-server NPM package installed](https://www.npmjs.com/package/ssb-server) or by starting [Patchwork](https://github.com/ssbc/patchwork) or [Patchbay](https://github.com/ssbc/patchbay).
-
-In the near future we'll refactor [Scuttle Shell](https://github.com/ssbc/scuttle-shell) to work with Patchfox again.
-
-## Things to double check
-
-* Did you filled the correct keys and remote in the <a href="#" id="options-trigger">Patchfox Add-on options page</a>?
-* Are you running _sbot_? Do you have another client running?
-* Does the identity you used in Patchfox options page matches the identity on the running _sbot_?
-
-<script src="help.js">
-
+# Can't connect to _sbot_
+
+_sbot_ also known as _ssb-server_ is the server that does all the peer to peer networking in Secure Scuttlebutt. Even though we call it a server, it is just a program running on your machine. This part of Secure Scuttlebutt is usually not visible to the user. Applications just load this server up when they start.
+
+When you run Patchfox for the first time, it displays a setup dialog that lets you select what identity to use, fill in your remote configuration, and tell Patchfox if you want it to start the server part or if you're going to run your own.
+
+The default values are:
+
+- Load the default identity stored in `~.ssb/secret`.
+- Run the built-in server.
+
+These values should get you the best Patchfox experience. Running it with different values require more knowledge about SSB such as how to run a server and which remote you're going to use.
+
+## Things to double check
+
+* Did you filled the correct keys and remote in the first-run setup process?
+* Are you running _sbot_? Do you have another client running? If you have another client running at the same time, you might need to setup Patchfox so that it doesn't start its own server. Unless you really know what you're doing, you can't have two running SSB servers at the same time. So no running Patchwork and Patchfox at the same time unless you tell Patchfox not to start its server.
+* Does the identity you used in Patchfox setup matches the identity on the running _sbot_?
+
+<script src="help.js">
+

electron-builder.config.js

@@ -120,6 +120,7 @@ module.exports = {
   win: {
     icon: path.join(__dirname, "ui", "assets", "images", "patchfox_pixel_512.png"),
     publisherName: AUTHOR,
+    target: [{target: "zip", arch: ["arm64", "x64", "ia32"]}]
   },
 
   // nsis: {

package.json

@@ -1,6 +1,6 @@
 {
   "name": "patchfox",
-  "version": "2022.9.1-alpha",
+  "version": "2022.9.3-alpha",
   "repository": {
     "url": "https://github.com/soapdog/patchfox"
   },
@@ -19,7 +19,9 @@
     "builder:mac": "electron-builder build --config electron-builder.config.js --mac",
     "build": "run-s css docs",
     "docs": "node scripts/copy-package-docs.js",
-    "localbuild": "run-s build builder:*"
+    "release-script": "node scripts/make-release.js",
+    "localbuild": "run-s build builder:*",
+    "release": "run-s localbuild release-script"
   },
   "devDependencies": {
     "@fortawesome/fontawesome-free": "^6.0.0",

scripts/README.md

@@ -1 +1,15 @@
-All files in here are related to developing patchfox itself and are not part of the codebase of the add-on.
+# Scripts
+All files in here are related to developing patchfox itself and are not part of the codebase of the add-on.
+
+
+### `copy-package-docs.js` 
+
+this script picks the documentation that is bundled with each package in `ui/packages/` and place them in `docs/` while processing them further so that they have links to source-code and related materials. This script is run by the release generation task.
+
+It also does some dance moves with the release notes for the current release.
+
+### `make-release.js`
+
+Creates a new release and upload the assets to Github. The build happens locally. Mac universal builds are not working inside Github Actions for some reason but work fine from my machine.
+
+Having this all happen locally also helps avoid lock-in to GH.

scripts/make-release.js

@@ -0,0 +1,75 @@
+#!env node
+
+// SPDX-FileCopyrightText: 20022 Patchfox Authors
+//
+// SPDX-License-Identifier: CC0-1.0
+
+const path = require("path")
+const fs = require("fs")
+const { spawn } = require("child_process")
+const rimraf = require("rimraf")
+const PackageJSON = require("../package.json")
+const version = PackageJSON.version
+
+const releaseNotes = "./build/release-notes.md"
+
+const windowsFiles = [
+  `./build/Patchfox-${version}-ia32-win.zip#Patchfox for Windows (32bits)`,
+  `./build/Patchfox-${version}-win.zip#Patchfox for Windows (64bits)`,
+  `./build/Patchfox-${version}-arm64-win.zip#Patchfox for Windows (arm64)`,
+]
+
+const linuxFiles = [
+  `./build/Patchfox-${version}-universal.dmg#Patchfox for macOS (universal)`
+]
+
+const macFiles = [
+  `./build/Patchfox-${version}.tar.gz#Patchfox for Linux (64bits)`,
+  `./build/Patchfox-${version}-arm64.tar.gz#Patchfox for Linux (arm64)`,
+]
+
+const files = [
+  ...windowsFiles,
+  ...linuxFiles,
+  ...macFiles
+]
+
+files.forEach(fileWithLabel => {
+  let f = fileWithLabel.slice(0, fileWithLabel.indexOf("#"))
+  if (!fs.existsSync(f)) {
+    throw `Missing release file: '${f}'`
+  }
+})
+
+if (!fs.existsSync(releaseNotes)) {
+  throw "missing release notes"
+}
+
+const fileList = files
+
+let args = [
+  "release",
+  `create`,
+  `v${version}`,
+  "-p",
+  "--discussion-category",
+  "General",
+  `--title`,
+  `Patchfox v${version} Pre-release`,
+  `-F`,
+  `${releaseNotes}`,
+  ...fileList
+]
+const defaults = {
+  cwd: process.cwd(),
+  env: process.env
+}
+const child = spawn("gh", args)
+
+child.stdout.on("data", data => {
+  console.log(`stdout:\n${data}`)
+})
+
+child.stderr.on("data", data => {
+  console.error(`stderr: ${data}`)
+})