Merge branch 'main' into live

building-blocks/hyperdht.md

@@ -42,8 +42,8 @@ Notable features include:
         * [node.unannounce(topic, keyPair, \[options\])](hyperdht.md#node.unannounce)
   * [Mutable/immutable records:](hyperdht.md#mutable-immutable-records)
     * Methods:
-      * [node.immutablePut(value, \[options\])](hyperdht.md#node.inmutableput)
-      * [node.immutableGet(hash, \[options\])](hyperdht.md#node.inmutableget)
+      * [node.immutablePut(value, \[options\])](hyperdht.md#node.immutableput)
+      * [node.immutableGet(hash, \[options\])](hyperdht.md#node.immutableget)
       * [node.mutablePut(keyPair, value, \[options\])](hyperdht.md#node.mutableput)
       * [node.mutableGet(publicKey, \[options\])](hyperdht.md#node.mutableget)
 
@@ -243,17 +243,17 @@ Unannounces a key pair.
 
 Any passed options are forwarded to dht-rpc.
 
-### Mutable/Immutable Records {#mutable-inmutable-records}
+### Mutable/Immutable Records {#mutable-immutable-records}
 
 #### Methods
 
-#### **`const { hash, closestNodes } = await node.immutablePut(value, [options])`** {#node.inmutableput}
+#### **`const { hash, closestNodes } = await node.immutablePut(value, [options])`** {#node.immutableput}
 
 Stores an immutable value in the DHT. When successful, the hash of the value is returned.
 
 Any passed options are forwarded to dht-rpc.
 
-#### **`const { value, from } = await node.immutableGet(hash, [options])`** {#node.inmutableget}
+#### **`const { value, from } = await node.immutableGet(hash, [options])`** {#node.immutableget}
 
 Fetch an immutable value from the DHT. When successful, it returns the value corresponding to the hash.
 

building-blocks/hyperswarm.md

@@ -21,7 +21,7 @@ Notable features include:
       * [swarm.peers](hyperswarm.md#swarm.peers)
       * [swarm.dht](hyperswarm.md#swarm.dht)
     * Methods:
-      * [swarm.join(topic, [options])](hyperswarm.md#const-discovery--swarmjointopic-options)
+      * [swarm.join(topic, [options])](hyperswarm.md#swarm.join)
     * Events:
       * [connection](hyperswarm.md#swarm.onconnection)
       * [update](hyperswarm.md#swarm.onupdate)

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

@@ -17,7 +17,7 @@ pear init --yes
 This creates the base project structure.
 
 - `package.json`. App configuration. Notice the `pear` property.
-- `index.js`. App entrypoint.
+- `index.html`. App entrypoint.
 - `app.js`. Main code.
 - `test/index.test.js`. Test skeleton.
 

howto/connect-to-many-peers-by-topic-with-hyperswarm.md

@@ -49,7 +49,7 @@ process.stdin.on('data', d => {
 })
 
 // Join a common topic
-const topic = process.argv[2] ? b4a.from(process.argv[2], 'hex') : crypto.randomBytes(32)
+const topic = process.argv[3] ? b4a.from(process.argv[3], 'hex') : crypto.randomBytes(32)
 const discovery = swarm.join(topic, { client: true, server: true })
 
 // The flushed promise will resolve when the topic has been fully announced to the DHT
@@ -62,9 +62,9 @@ In one terminal, open `peer-app` with `pear dev`
 
 ```
 cd peer-app
-pear dev
+pear dev .
 ```
 
-This will display the topic. Copy/paste that topic into as many additional terminals as desired with `pear dev -- <SUPPLY TOPIC HERE>` (assuming that the current working directory of each terminal is the `peer-app` folder). Each peer will log information about the other connected peers.
+This will display the topic. Copy/paste that topic into as many additional terminals as desired with `pear dev . <SUPPLY TOPIC HERE>` (assuming that the current working directory of each terminal is the `peer-app` folder). Each peer will log information about the other connected peers.
 
 Start typing into any terminal, and it will be broadcast to all connected peers.

howto/connect-two-peers-by-key-with-hyperdht.md

@@ -67,8 +67,8 @@ import DHT from 'hyperdht'
 import b4a from 'b4a'
 import process from 'bare-process'
 
-console.log('Connecting to:', process.argv[2])
-const publicKey = b4a.from(process.argv[2], 'hex')
+console.log('Connecting to:', process.argv[3])
+const publicKey = b4a.from(process.argv[3], 'hex')
 
 const dht = new DHT()
 const conn = dht.connect(publicKey)

howto/create-a-full-peer-to-peer-filesystem-with-hyperdrive.md

@@ -165,7 +165,7 @@ In a new terminal, create the `bee-reader-app` project with these commands:
 mkdir bee-reader-app
 cd bee-reader-app
 pear init -y -t terminal
-npm install corestore hyperswarm hyperdrive debounceify b4a bare-process
+npm install corestore hyperswarm hyperdrive hyperbee b4a bare-process
 ```
 
 Adjust the `bee-reader-app/index.js` file to:
@@ -174,7 +174,6 @@ Adjust the `bee-reader-app/index.js` file to:
 import Hyperswarm from 'hyperswarm'
 import Corestore from 'corestore'
 import Hyperbee from 'hyperbee'
-import debounce from 'debounceify'
 import b4a from 'b4a'
 import process from 'bare-process'
 
@@ -188,7 +187,7 @@ Pear.teardown(() => swarm.destroy())
 swarm.on('connection', conn => store.replicate(conn))
 
 // create/get the hypercore instance using the public key supplied as command-line arg
-const core = store.get({ key: b4a.from(process.argv[2], 'hex') })
+const core = store.get({ key: b4a.from(process.argv[3], 'hex') })
 
 // create a hyperbee instance using the hypercore instance
 const bee = new Hyperbee(core, {
@@ -229,4 +228,4 @@ pear dev
 
 The `bee-reader-app` creates a Hyperbee instance using the Hypercore instance created with the copied public key. Every time the Hyperbee is updated (an `append` event is emitted on the underlying Hypercore), all file metadata nodes will be logged out.
 
-Try adding or removing a few files from the writer's data directory, then pressing `Enter` in the writer's terminal to mirror the changes.
+Try adding or removing a few files from the writer's data directory, then pressing `Enter` in the writer's terminal to mirror the changes.

howto/share-append-only-databases-with-hyperbee.md

@@ -188,7 +188,7 @@ Pear.teardown(() => swarm.destroy())
 swarm.on('connection', conn => store.replicate(conn))
 
 // create or get the hypercore using the public key supplied as command-line argument
-const core = store.get({ key: b4a.from(process.argv[2], 'hex') })
+const core = store.get({ key: b4a.from(process.argv[3], 'hex') })
 // wait till the properties of the hypercore instance are initialized
 await core.ready()
 

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

@@ -130,7 +130,7 @@ for (const key of otherKeys) {
 In one terminal, open `multicore-writer-app` with `pear dev`.
 
 ```
-cd  mutlicore-writer-app
+cd  multicore-writer-app
 pear dev
 ```
 
@@ -143,4 +143,4 @@ cd multicore-reader-app
 pear dev . <SUPPLY THE KEY HERE>
 ```
 
-As inputs are made to the terminal running the writer application, outputs should be shown in the terminal running the reader application.
+As inputs are made to the terminal running the writer application, outputs should be shown in the terminal running the reader application.

reference/bare/overview.md

@@ -26,7 +26,7 @@ Bare is built on top of [libjs](https://github.com/holepunchto/libjs), which pro
 2. A native addon system supporting both statically and dynamically linked addons.
 3. Light-weight thread support with synchronous joins and shared array buffer support.
 
-Everything else if left to userland modules to be implemented using these primitives, keeping the runtime itself succinct and _bare_.
+All additional features are implemented by userland modules using these primitives, keeping the runtime itself lean and _bare_.
 
 ## API
 

reference/pear/api.md

@@ -280,9 +280,9 @@ A bidirectional pipe is also created which enables communication between the par
 
 Reference counting is handled automatically to manage the sidecar lifecycle.
 
-### `const pipe = Pear.worker.run(key <String>)`
+### `const pipe = Pear.worker.run(link <String>, args <Array<String>>)`
 
-Spawns a new process with the specified key as the entry point. Resolves to a `Duplex` stream object representing a pipe.
+Runs a Pear Worker by spawning a Pear Terminal Application process from the specified `link` parameter. The Worker uses the flags of the parent application but any application arguments must be passed using the `args` parameter, the `args` parameter also sets `Pear.config.args`. Returns a pipe (a [`streamx`](https://github.com/mafintosh/streamx) `Duplex` stream) for Worker communication. 
 
 ### `const pipe = Pear.worker.pipe()`
 
@@ -354,9 +354,9 @@ Captures available desktop sources. Resolves to an array of objects with shape `
 * https://www.electronjs.org/docs/latest/api/structures/desktop-capturer-source
 * [`<NativeImage>`](https://www.electronjs.org/docs/latest/api/native-image)
 
-### `Pear.versions <Object>`
+### `Pear.versions <Async Function>`
 
-Versions object. Pear versions are objects with the shape `{ fork <Integer>, length <Integer>, key <Buffer> }`.
+Function that returns a promise which resolves to a Pear versions object with the shape `{ fork <Integer>, length <Integer>, key <Buffer> }`.
 
 The `key` is a Buffer of the run key. The `length` is the size of the relevant Hypercore. The `fork` property is determined by data truncation.
 
@@ -366,10 +366,14 @@ These three properties together are a unique identifier for the entire state of
 
 The platform version.
 
-### `Pear.versions.application { fork <Integer>, length <Integer>, key <Buffer> }`
+### `Pear.versions.app { fork <Integer>, length <Integer>, key <Buffer> }`
 
 The application version.
 
+### `Pear.versions.runtimes { bare <Integer>, electron <Integer>, pear <Integer> }`
+
+The versions of runtimes.
+
 **References**
 
 * [Pear.config.key](#pearconfigkey-objectnull)
@@ -385,6 +389,10 @@ Functions supplied to teardown will be executed in order of registration when
 an application begins to unload. Any promise returned from each supplied function
 will be waited upon until resolution before calling the next teardown handler.
 
+### Pear.reload()
+
+Soft-restart Terminal applications (keeps I/O), refresh application in Desktop applications.
+
 ### `Pear.restart()`
 
 Restart the application.
@@ -427,12 +435,16 @@ The `listener` function is called for every incoming wakeup with a `wakeup` obje
 {
   type: 'pear/wakeup',
   link: <String>,
-  data: <String>
+  linkData: <String>,
+  fragment: <String>,
+  entrypoint: <String>
 }
 ```
 
 * `link` is the `pear://` link for the application receiving the wakeup
-* `data` is everything after the key in the `pear://` link - this would be `pathname` of a [`URL`](https://developer.mozilla.org/en-US/docs/Web/API/URL/URL) object but without the leading slash (`/`). Given `pear://8ts9yz9dtucxzwbxafygnjasqe9ti3dt3w7rm6sbiu8prmidacao/some/more/stuff` the `data` string would hold `some/more/stuff`.
+* `linkData` is everything after the key in the `pear://` link - this would be `pathname` of a [`URL`](https://developer.mozilla.org/en-US/docs/Web/API/URL/URL) object but without the leading slash (`/`). Given `pear://8ts9yz9dtucxzwbxafygnjasqe9ti3dt3w7rm6sbiu8prmidacao/some/more/stuff` the `data` string would hold `some/more/stuff`.
+* `fragment` is the `fragment` part of `pear://link#fragment` (location hash without the `#` prefix).
+* `entrypoint` includes `entrypoint` of `pear://link/some/entry/point` (URL pathname).
 
 Also returns a [`streamx`](https://github.com/mafintosh/streamx) `Readable`) stream.
 

reference/pear/cli.md

@@ -4,15 +4,22 @@
 
 The Command Line Interface is the primary interface for Pear Development.
 
-## `pear init [dir]`
+## `pear init [flags] <link|type=desktop> [dir]`
 
 Create initial project files.
 
+Template Types: desktop, terminal, terminal-node
+
+> Default Project directory path is `.`
+
+Template can also be initialized from a pear:// link, the template should contain a `_template.json` file. This file defines the prompts which are converted to locals that are injected into the template.
+
 ```
 --yes|-y         Autoselect all defaults
---type|-t=type   Project type: desktop (default) or terminal
+--type|-t=type   Template type. Overrides <link|type>
 --force|-f       Force overwrite existing files
 --with|-w=name   Additional functionality. Available: node
+--help|-h        Show help
 ```
   
 ## `pear dev [flags] [dir] [...app-args]`
@@ -58,15 +65,14 @@ Specify a remote key to reseed.
   --verbose|-v  Additional output
 ```
   
-## `pear run [flags] <key|dir|alias> [...app-args]`
+## `pear run [flags] <link|dir> [...app-args]`
 
 Run an application from a key or dir.
 
 |       |                                                   |
 |-------|---------------------------------------------------|
-| key   | `pear://<key>`                            |
+| link  | `pear://<key>`  \| `pear://<alias>`                |
 | dir   | `file://<absolute-path>` \| `<absolute-path>` \| `<relative-path>` |
-| alias | `pear://<alias>`                          |
 
 
 ```
@@ -77,6 +83,7 @@ Run an application from a key or dir.
   --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
+  --links <kvs>              Override configured links with comma-separated key-values
   --chrome-webrtc-internals  Enable chrome://webrtc-internals
   --unsafe-clear-app-storage Clear app storage
   --unsafe-clear-preferences Clear preferences (such as trustlist)
@@ -86,6 +93,7 @@ Run an application from a key or dir.
   --checkout=staged          Run checkout from latest version length
   --no-ask-trust             Exit instead of asking to trust unknown keys
   --detached                 Wakeup existing app or run detached
+  --help|-h                  Show help
 ```
 
 ### Examples 
@@ -135,13 +143,16 @@ Supply no argument to view platform information.
   --json            Newline delimited JSON output
 ```
   
-## `pear dump <key> [dir]`
+## `pear dump [flags] <link> <dir>`
 
 Synchronize files from key to dir.
 
+> To dump to stdout use `-` in place of `<dir>`
+
 ```
+  --checkout=n    Dump from specified checkout, n is version length
   --json          Newline delimited JSON output
-  --checkout=n    Dump from a custom release length (version)
+  --help|-h       Show help
 ```
   
 ## `pear sidecar`