Merge branch 'main' into live

README.md

@@ -12,19 +12,19 @@ Welcome to the Internet of Peers
 
 ## Table of Contents
 
-### Pear runtime
+### Pear Runtime
 
-References for utilizing the Pear runtime.
+References for Pear Runtime.
 
 * [Command-Line-Interface (CLI)](./reference/pear/cli.md)
 * [Application-Programming-Interface (API)](./reference/pear/api.md)
 * [Application Configuration](./reference/pear/configuration.md)
 
-> The Pear runtime uses [Bare](https://github.com/holepunchto/bare) JavaScript runtime, which is a small and modular JavaScript runtime for desktop and mobile. To learn more, see [Bare Reference](./reference/bare/overview.md).
+> The Pear Runtime uses [Bare](https://github.com/holepunchto/bare) JavaScript runtime, which is a small and modular JavaScript runtime for desktop and mobile. To learn more, see [Bare Reference](./reference/bare/overview.md).
 
 ### Guides
 
-Guides on using the pear runtime to build and share P2P applications.
+Guides on using the Pear Runtime to build and share P2P applications.
 
 * [Getting Started](./guide/getting-started.md)
 * [Starting a Pear Desktop Project](./guide/starting-a-pear-desktop-project.md)

guide/sharing-a-pear-app.md

@@ -93,7 +93,27 @@ With another machine or friend that has `pear` installed execute the `pear run <
 pear run pear://nykmkrpwgadcd8m9x5khhh43j9izj123eguzqg3ygta7yn1s379o
 ```
 
-When `pear run` is executed on the peer machine the staged application should open on that peer. If the application is being opened for the first time on the peer it has no state at all, so the application may show a loader until it's ready to reveal.
+When `pear run` is executed on the peer machine there will be a security prompt to add the key to a list of trusted applications by typing 'TRUST'.
+
+When running a terminal application using an untrusted key for the first time the prompt would be:
+
+```
+pear run pear://nykmkrpwgadcd8m9x5khhh43j9izj123eguzqg3ygta7yn1s379o
+✖ Key pear://nykmkrpwgadcd8m9x5khhh43j9izj123eguzqg3ygta7yn1s379o is not known
+
+Be sure that software is trusted before running it
+
+Type "TRUST" to allow execution or anything else to exit
+
+Trust application? 
+```
+The trust dialog is a security mechanism in Pear that appears when the user tries to run an application from an unknown or untrusted key for the first time. In case that the app is run in detached mode, for example, when clicking on a pear link in the browser, the trust dialog is a GUI (Graphical User Interface). 
+
+![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.
+
+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.
 
 The application staging machine that is running the seeding process should show output similar to:
 

howto/work-with-many-hypercores-using-corestore.md

@@ -37,7 +37,7 @@ await Promise.all([core1.ready(), core2.ready(), core3.ready()])
 console.log('main core key:', b4a.toString(core1.key, 'hex'))
 
 // Here we'll only join the swarm with the core1's discovery key
-// We don't need to announce core2 and core3, because they'll replicated with core1
+// We don't need to announce core2 and core3, because they'll be replicated with core1
 swarm.join(core1.discoveryKey)
 
 // Corestore replication internally manages to replicate every loaded core

reference/bare/nodejs-compatibility-with-bare.md

@@ -1,22 +1,32 @@
 # Node.js Compatibility with Bare
-Bare offers seamless compatibility with Node.js counterparts.
+Bare offers great compatibility with Node.js counterparts.
 Most of the modules and APIs used by developers are covered and supported.
 
 ## Currently supported modules
-
+* `assert`: [`bare-assert`](https://github.com/holepunchto/bare-assert) (through `npm:bare-node-assert)`
+* `buffer`: [`bare-buffer`](https://github.com/holepunchto/bare-buffer) (through `npm:bare-node-buffer)`
 * `child_process`: [`bare-subprocess`](https://github.com/holepunchto/bare-subprocess) (through `npm:bare-node-child-process)`
 * `console`: [`bare-console`](https://github.com/holepunchto/bare-console) (through `npm:bare-node-console)`
+* `crypto`: [`bare-crypto`](https://github.com/holepunchto/bare-crypto) (through `npm:bare-node-crypto)`
 * `events`: [`bare-events`](https://github.com/holepunchto/bare-events) (through `npm:bare-node-events)`
 * `fs`: [`bare-fs`](https://github.com/holepunchto/bare-fs) (through `npm:bare-node-fs)`
 * `http`: [`bare-http1`](https://github.com/holepunchto/bare-http1) (through `npm:bare-node-http)`
+* `https`: [`bare-https`](https://github.com/holepunchto/bare-https) (through `npm:bare-node-https)`
 * `inspector`: [`bare-inspector`](https://github.com/holepunchto/bare-inspector) (through `npm:bare-node-inspector)`
+* `module`: [`bare-module`](https://github.com/holepunchto/bare-module) (through `npm:bare-node-module)`
 * `os`: [`bare-os`](https://github.com/holepunchto/bare-os) (through `npm:bare-node-os)`
 * `path`: [`bare-path`](https://github.com/holepunchto/bare-path) (through `npm:bare-node-path)`
 * `process`: [`bare-process`](https://github.com/holepunchto/bare-process) (through `npm:bare-node-process)`
 * `readline`: [`bare-readline`](https://github.com/holepunchto/bare-readline) (through `npm:bare-node-readline)`
 * `repl`: [`bare-repl`](https://github.com/holepunchto/bare-repl) (through `npm:bare-node-repl)`
+* `stream`: [`bare-stream`](https://github.com/holepunchto/bare-stream) (through `npm:bare-node-stream)`
+* `timers`: [`bare-timers`](https://github.com/holepunchto/bare-timers) (through `npm:bare-node-timers)`
+* `tls`: [`bare-tls`](https://github.com/holepunchto/bare-tls) (through `npm:bare-node-tls)`
 * `tty`: [`bare-tty`](https://github.com/holepunchto/bare-tty) (through `npm:bare-node-tty)`
 * `url`: [`bare-url`](https://github.com/holepunchto/bare-url) (through `npm:bare-node-url)`
+* `util`: [`bare-utils`](https://github.com/holepunchto/bare-utils) (through `npm:bare-node-util)`
+* `worker_threads`: [`bare-worker`](https://github.com/holepunchto/bare-worker) (through `npm:bare-node-worker-threads)`
+* `zlib`: [`bare-zlib`](bhttps://github.com/holepunchto/bare-zlib) (through `npm:bare-node-zlib)`
 
 ## Config for the Node.js stdlib
 
@@ -25,18 +35,28 @@ To get the full Node.js compatible layer that Bare currently supports add the fo
 ```json
 {
   "dependencies": {
+    "bare-assert": "^1.0.1",
+    "assert": "npm:bare-node-assert",
+    "bare-buffer": "^2.3.0",
+    "buffer": "npm:bare-node-buffer",
     "bare-subprocess": "^2.0.4",
     "child_process": "npm:bare-node-child-process",
     "bare-console": "^4.1.0",
     "console": "npm:bare-node-console",
+    "bare-crypto": "^1.0.0",
+    "crypto": "npm:bare-node-crypto",
     "bare-events": "^2.2.0",
     "events": "npm:bare-node-events",
     "bare-fs": "^2.1.5",
     "fs": "npm:bare-node-fs",
     "bare-http1": "^2.0.3",
     "http": "npm:bare-node-http",
+    "bare-https": "^1.0.0",
+    "https": "npm:bare-node-https",
     "bare-inspector": "^1.1.2",
     "inspector": "npm:bare-node-inspector",
+    "bare-module": "^1.2.5",
+    "module": "npm:bare-node-module",
     "bare-os": "^2.2.0",
     "os": "npm:bare-node-os",
     "bare-path": "^2.1.0",
@@ -47,10 +67,22 @@ To get the full Node.js compatible layer that Bare currently supports add the fo
     "readline": "npm:bare-node-readline",
     "bare-repl": "^1.0.3",
     "repl": "npm:bare-node-repl",
+    "bare-stream": "^1.0.0",
+    "stream": "npm:bare-node-stream",
+    "bare-timers" : "^1.0.0",
+    "timers": "npm:bare-node-timers",
+    "bare-tls": "^1.0.0",
+    "tls": "npm:bare-node-tls",
     "bare-tty": "^3.2.0",
     "tty": "npm:bare-node-tty",
     "bare-url": "^1.0.7",
-    "url": "npm:bare-node-url"
+    "url": "npm:bare-node-url",
+    "bare-utils": "^1.0.0",
+    "util": "npm:bare-node-util",
+    "bare-worker": "^1.0.0",
+    "worker_threads": "npm:bare-node-worker-threads",
+    "bare-zlib": "^1.0.0",
+    "zlib": "npm:bare-node-zlib"
   }
 }
 ```

reference/pear/api.md

@@ -261,6 +261,24 @@ async function logPrefUpdates () {
 logPrefUpdates().catch(console.error)
 ```
 
+## `Pear.worker <Object>`
+
+Pear Worker is used to spawn processes and facilitate communication between the parent and child processes in the Pear Runtime.
+
+The spawned worker process inherits standard input, output, and error from the parent process.
+
+A bidirectional pipe is also created which enables communication between the parent and worker process.
+
+Reference counting is handled automatically to manage the sidecar lifecycle.
+
+### `const pipe = Pear.worker.run(key <String>)`
+
+Spawns a new process with the specified key as the entry point. Resolves to a `Duplex` stream object representing a pipe.
+
+### `const pipe = Pear.worker.pipe()`
+
+Returns the communication pipe created to the worker process. Resolves to a `Duplex` stream object representing a pipe.
+
 ## `Pear.media <Object>`
 
 Media interface
@@ -362,6 +380,10 @@ will be waited upon until resolution before calling the next teardown handler.
 
 Restart the application.
 
+### `Pear.exit(code)`
+
+Exits the process with the provided exit code.
+
 ### `Pear.updates(listener <Async Function|Function>) => streamx.Readable`
 
 The `listener` function is called for every incoming update with an `update` object of the form:

reference/pear/cli.md

@@ -70,13 +70,17 @@ Run an application from a key or dir.
 
 
 ```
-  --dev                      Enable --devtools & --updates-diff
+  --dev|-d                   Enable --devtools & --updates-diff
   --devtools                 Open devtools with application [Desktop]
   --updates-diff             Enable diff computation for Pear.updates
   --no-updates               Disable updates firing via Pear.updates
   --link=url                 Simulate deep-link click open
   --store|-s=path            Set the Application Storage path
   --tmp-store|-t             Automatic new tmp folder as store path
+  --chrome-webrtc-internals  Enable chrome://webrtc-internals
+  --unsafe-clear-app-storage Clear app storage
+  --unsafe-clear-preferences Clear preferences (such as trustlist)
+  --appling=path             Set application shell path
   --checkout=n               Run a checkout, n is version length
   --checkout=release         Run checkout from marked released length
   --checkout=staged          Run checkout from latest version length
@@ -115,15 +119,19 @@ Use this to indicate production release points.
   --checkout=n|current     Set a custom release length (version)
 ```
   
-## `pear info [key]`
+## `pear info [channel|key]`
 
 Read project information.
 
-Supply a key to view application info
+Supply a key or channel to view application information.
 
-Without a key pear info shows Pear info
+Supply no argument to view platform information.
 
 ```
+  --changelog       View changelog only
+  --full-changelog  Full record of changes
+  --metadata        View metadata only
+  --key             View key only
   --json            Newline delimited JSON output
 ```
   
@@ -149,12 +157,6 @@ and then becomes the sidecar.
   --attach-boot-io   include initial sidecar I/O (if applicable)
 ```
 
-## `pear repl`
-
-Connect to a Read-Eval-Print-Loop session with sidecar.
-
-A key is printed out, use with repl-swarm module to connect.
-
 ## `pear versions`
 
 Output version information.
@@ -172,7 +174,19 @@ Move user application storage between applications.
 --json      Newline delimited JSON output
 ```
 
-
+## `pear gc [flags] [command]`
+
+Perform garbage collection and remove unused resources.
+
+| Commands      |           Description                                        |
+|-------|---------------------------------------------------|
+| releases   | Clear inactive releases                       |
+| sidecars   |  Clear running sidecars                       |
+
+```
+  --json      Newline delimited JSON output
+  --help|-h   Show help
+```
 
 
   

reference/pear/configuration.md

@@ -120,6 +120,14 @@ Enable transparency. Must be set for opacity to work.
 
 Background color (Hex, RGB, RGBA, HSL, HSLA, CSS color).
 
+###  `pear.links <Object|Array>` 
+
+An array or object containing trusted Pear application keys.
+
+#### `pear.links.worker <String>`
+
+The key of the Pear application that contains the worker script. For more info, please check the [terminal](https://github.com/holepunchto/pear/blob/main/examples/terminal/index.js#L21) and [desktop](https://github.com/holepunchto/pear/blob/main/examples/desktop/app.js#L27) examples.
+
 ### `pear.stage <Object>`
 
 Staging configuration options.