Update guides (#134)

* update desktop guide

* update pear terminal guides

* fixes

* fix ctrl-c for example terminal app

* use SIGINT on readline close

---------

Co-authored-by: rafapaezbas <rafaelpaezbastida@gmail.com>

guide/debugging-a-pear-terminal-app.md

@@ -30,7 +30,7 @@ if (Pear.config.dev) {
 As the code specifies, `pear-inspect` is only running when in dev mode, so start the app:
 
 ```
-pear dev .
+pear run --dev .
 ```
 
 The application will output something similar to:

guide/making-a-pear-desktop-app.md

@@ -159,7 +159,7 @@ Start by defining the app's layout in `index.html`:
 </html>
 ```
 
-Running `pear dev` should show
+Running `pear run --dev .` should show
 
 ![Layout of the app](../assets/chat-app-3.png)
 
@@ -190,7 +190,7 @@ Replace `app.js` with
 import Hyperswarm from 'hyperswarm'   // Module for P2P networking and connecting peers
 import crypto from 'hypercore-crypto' // Cryptographic functions for generating the key in app
 import b4a from 'b4a'                 // Module for buffer-to-string and vice-versa conversions 
-const { teardown } = Pear             // Cleanup function
+const { teardown, updates } = Pear             // Cleanup and updates function
 
 const swarm = new Hyperswarm()
 
@@ -198,6 +198,10 @@ const swarm = new Hyperswarm()
 // (This is not a requirement, but it helps avoid DHT pollution)
 teardown(() => swarm.destroy())
 
+// Enable automatic reloading for the app
+// This is optional but helpful during production
+updates(() => Pear.reload())
+
 // When there's a new connection, listen for new messages, and add them to the UI
 swarm.on('connection', (peer) => {
   // name incoming peers after first 6 chars of its public key as hex
@@ -267,11 +271,7 @@ function onMessageAdded (from, message) {
 
 ## Step 4. Chat
 
-Open two app instances by running `pear dev` in two terminals. For now, you will need to specify a different storage directory for the second `pear` instance to allow for two instances to run simultaneously:
+Open two app instances by running `pear run --dev .` in two terminals. 
-
-```
-pear dev -s /tmp/tmp_pear_instance
-```
 
 In the first app, click on `Create`. A random topic will appear at the top.
 

guide/making-a-pear-terminal-app.md

@@ -14,7 +14,7 @@ Pear runs on [`Bare`](https://github.com/holepunchto/bare), a lightweight JavaSc
 
 
 ```
-npm i bare-readline bare-tty hyperswarm b4a hypercore-crypto
+npm i bare-readline bare-tty bare-process hyperswarm b4a hypercore-crypto
 ```
 
 ## Step 2. JavaScript
@@ -28,9 +28,10 @@ import b4a from 'b4a'                 // Module for buffer-to-string and vice-ve
 import crypto from 'hypercore-crypto' // Cryptographic functions for generating the key in app
 import readline from 'bare-readline'  // Module for reading user input in terminal
 import tty from 'bare-tty'            // Module to control terminal behavior
+import process from 'bare-process'    // Process control for Bare
 
 
-const { teardown, config } = Pear    // Import configuration options and cleanup functions from Pear
+const { teardown, config, updates } = Pear    // Import configuration options, updates and cleanup functions from Pear
 const key = config.args.pop()       // Retrieve a potential chat room key from command-line arguments
 const shouldCreateSwarm = !key      // Flag to determine if a new chat room should be created
 const swarm = new Hyperswarm()
@@ -39,6 +40,10 @@ const swarm = new Hyperswarm()
 // (This is not a requirement, but it helps avoid DHT pollution)
 teardown(() => swarm.destroy())
 
+// Enable automatic reloading for the app
+// This is optional but helpful during production
+updates(() => Pear.reload())
+
 const rl = readline.createInterface({
   input: new tty.ReadStream(0),
   output: new tty.WriteStream(1)
@@ -70,6 +75,10 @@ rl.on('data', line => {
 })
 rl.prompt()
 
+rl.on('close', () => {
+  process.kill(process.pid, 'SIGINT')
+})
+
 async function createChatRoom () {
   // Generate a new random topic (32 byte string)
   const topicBuffer = crypto.randomBytes(32)
@@ -86,7 +95,7 @@ async function joinChatRoom (topicStr) {
 }
 
 async function joinSwarm (topicBuffer) {
-    // Join the swarm with the topic. Setting both client/server to true means that this app can act as both.
+  // Join the swarm with the topic. Setting both client/server to true means that this app can act as both.
   const discovery = swarm.join(topicBuffer, { client: true, server: true })
   await discovery.flushed()
 }
@@ -105,7 +114,7 @@ function appendMessage ({ name, message }) {
 
 ## Step 3. Run in dev mode
 
-To test this chat app, in one terminal run `pear dev .`
+To test this chat app, in one terminal run `pear run --dev .`
 
 The app will output something similar to:
 
@@ -113,7 +122,7 @@ The app will output something similar to:
 [info] Created new chat room: a1b2c35fbeb452bc900c5a1c00306e52319a3159317312f54fe5a246d634f51a
 ```
 
-In another terminal use this key as input, `pear dev . a1b2c35fbeb452bc900c5a1c00306e52319a3159317312f54fe5a246d634f51a`
+In another terminal use this key as input, `pear run --dev . a1b2c35fbeb452bc900c5a1c00306e52319a3159317312f54fe5a246d634f51a`
 
 The app will output:
 
@@ -128,4 +137,4 @@ Type something in one of the applications. Two Terminal Applications are now con
 
 ## Next
 
-* [Sharing a Pear Application](./sharing-a-pear-app.md)
+* [Sharing a Pear Application](./sharing-a-pear-app.md)

guide/releasing-a-pear-app.md

@@ -52,7 +52,7 @@ pear seed production
 
 After marking a release, make a trivial change to the project (e.g. add a `console.log(...)` somewhere).
 
-First verify that it works by running `pear dev`.
+First verify that it works by running `pear run --dev .`
 
 Now stage the change with `pear stage production`.
 

guide/sharing-a-pear-app.md

@@ -12,7 +12,7 @@ cd staging-example
 pear init -y
 ```
 
-If starting from [Making a Pear Desktop Application](./making-a-pear-desktop-app.md) or [Making a Pear Terminal Application](./making-a-pear-terminal-app.md) ensure that the comamnd-line current working directory is set to the project folder of the application.
+If starting from [Making a Pear Desktop Application](./making-a-pear-desktop-app.md) or [Making a Pear Terminal Application](./making-a-pear-terminal-app.md) ensure that the command-line current working directory is set to the project folder of the application.
 
 ## Step 1. Stage the app
 
@@ -50,7 +50,7 @@ Copy the application key that was output when the application was staged in the
 pear run pear://nykmkrpwgadcd8m9x5khhh43j9izj123eguzqg3ygta7yn1s379o
 ```
 
-Where `pear dev` opens an application from the filesystem, `pear run`  opens the application from Pear's application storage. So far the application has remained local, in order to share it with other peers it must be seeded.
+`pear run`  opens the application from Pear's application storage. So far the application has remained local, in order to share it with other peers it must be seeded.
 
 ## Step 3. Seed the app
 
@@ -111,7 +111,7 @@ The trust dialog is a security mechanism in Pear that appears when the user trie
 
 ![Trust dialog](../assets/trust-dialog.png)
 
-> During development with `pear dev`, applications are automatically trusted, as they are assumed to be safe for testing purposes. Trust dialog can be suppressed using the  `--no-ask-trust` flag with `pear run` in which case the application will automatically decline unknown keys.
+> During development with `pear run --dev`, applications are automatically trusted, as they are assumed to be safe for testing purposes. Trust dialog can be suppressed using the  `--no-ask-trust` flag with `pear run` in which case the application will automatically decline unknown keys.
 
 The application has no state when it's opened for the first time, so the application may show a loader until it's ready to reveal.
 

guide/starting-a-pear-desktop-project.md

@@ -23,21 +23,35 @@ This creates the base project structure.
 
 ## Step 2. Verify Everything Works
 
-Use `pear dev` to verify everything works as expected.
+Use `pear run` to verify everything works as expected.
 
 ```
-pear dev
+pear run --dev .
 ```
 
-The app should open in development mode. By default, developer tools are also opened.
+> A directory or link needs to be specified with `pear run`, here `.` denotes the current Project directory.
 
-![Running pear dev](../assets/chat-app-1.png)
+The app should open in development mode. In this mode developer tools are also opened.
+
+![Running pear run --dev .](../assets/chat-app-1.png)
 
 ## Step 3. Automatic Reload
 
-Pear watches project files. When they change, the app is automatically reloaded.
+To enable automatic reloading, add the following lines to `app.js` :
 
-While keeping the `pear dev` command running, open `index.html` in an editor.
+```js
+Pear.updates(() => Pear.reload())
+```
+
+Run the app again using:
+
+```js
+pear run --dev .
+```
+
+Now Pear watches project files. When they change, the app is automatically reloaded.
+
+While keeping the `pear run --dev .` command running, open `index.html` in an editor.
 
 Change `<h1>chat</h1>` to `<h1>Hello world</h1>`.
 
@@ -58,7 +72,6 @@ Open `package.json` and update it to:
   ...
   "pear": {
     "gui": {
-      "backgroundColor": "#012a02",
       "height": 400,
       "width": 700
     }
@@ -67,7 +80,7 @@ Open `package.json` and update it to:
 }
 ```
 
-Close the app and re-run `pear dev` to see the changes:  the background is now light blue, and the initial window size is different.
+Close the app and re-run `pear run --dev .` to see the changes, the initial window size is different now.
 
 See the [Configuration Documentation](../reference/pear/configuration.md) for all options.
 

guide/starting-a-pear-terminal-project.md

@@ -19,12 +19,14 @@ This creates the base project structure.
 
 ## Step 2. Verify Everything Works
 
-Use `pear dev` to see that it works.
+Use `pear run` to see that it works.
 
 ```
-pear dev
+pear run --dev .
 ```
 
+> A directory or link needs to be specified with `pear run`, here `.` denotes the current Project directory.
+
 The app will now run. Note that it will keep running until you exit with `ctrl + c`.
 
 That's all there is to getting a Pear Terminal project started.