Pear Platform

If you are contributing to Pear or developing for the platform, you can set up a local development environment (referred to as localdev) by cloning the repository, installing dependencies, and building the runtime binaries.

Built artifacts are stored in out/make. To run the current checkout directly in localdev mode, use the ./pear.dev script (or . pear.ps1 / . pear.cmd on Windows).

git clone https://github.com/holepunchto/pear && cd pear
npm install
npm run make
./pear.dev

You can install Pear onto your system using Node.js's npx command. After running the command, you must follow the specific instructions provided in the terminal output to set your PATH to ensure the pear command is available globally.

npx pear

By default, pear stage expects to find a valid package.json file in the target directory.

If no package.json is found:

1. In non-interactive environments (e.g., CI/CD or --json mode): The command will throw an ERR_INVALID_PROJECT_DIR error.
2. In interactive terminals: The command will prompt for confirmation. You must type STAGE (in uppercase) to confirm staging a folder without a package.json.

To bypass this check automatically, use the --skip-package-json flag.

After successfully running pear stage, you can follow up with these commands depending on your goal:

• To keep the staged version available:

  pear seed <link>

• To provision for prerelease, stakeholder preview, QA, or dogfooding:

  pear touch
  # OR
  pear provision --dry-run <source-verlink> <target-link> <production-verlink>

Pear provides built-in help documentation for its commands. You can view help information using the following syntax:

• pear help <cmd>: Detailed help for a specific command.
• pear <cmd> --help: Standard help flag for a command.
• pear <cmd> -h: Short help flag for a command.

To inspect what changes would be applied to a target without actually modifying it, use the --dry-run flag. This is the recommended workflow to ensure the diff looks correct before committing to a provision.

pear provision <source-verlink> <target-link> <production-verlink> --dry-run

After a successful dry run, if the diff is satisfactory, run the command again without the --dry-run flag to apply the changes.

The validate(dir) function checks if a given path is a valid directory. It will throw an ERR_INVALID_PROJECT_DIR error if the path does not exist or if the path points to a file instead of a directory.

const { validate } = require('pear/lib/package')

try {
  await validate('./my-project')
  console.log('Directory is valid')
} catch (err) {
  console.error('Validation failed:', err.message)
}

The Model class provides the following methods for interacting with the sidecar database:

• ready(): Returns a Promise that resolves when the underlying hyperdb is ready.
• getDhtNodes(): Retrieves the list of nodes from the @pear/dht namespace. Returns an empty array if no nodes exist.
• setDhtNodes(nodes): Atomically updates the @pear/dht namespace with the provided nodes array using a database transaction.
• getMultisig(key): Retrieves a multisig record matching the provided key from the @pear/multisig namespace.
• allMultisig(): Returns an array of all records found in the @pear/multisig namespace.
• setMultisig(key): Atomically inserts a new multisig record with the provided key into the @pear/multisig namespace.
• close(): Closes the underlying hyperdb instance.

The Sidecar provides properties and methods to manage active IPC clients:

• sidecar.clients: Returns a list of all connected IPC clients.
• sidecar.hasClients: A boolean indicating if there are any active clients.
• sidecar.closeClients(params, originClient): Closes all clients except for the originClient. It returns an array of metadata containing the cmdArgs of the closed clients.

You can query the current platform and runtime information using the versions(params, client) method. This returns an object containing:

• platform: An object with the UPGRADE key (containing the version, fork, and length), and the current version.
• runtimes: An object containing the versions for bare and pear runtimes.

// Example of what the return shape looks like
// {
//   platform: { key: '...', version: '...', fork: ..., length: ... },
//   runtimes: { bare: '...', pear: '...' }
// }

The getLinksByName(params, client) method allows you to search for metadata cores within the corestore that match a specific package name. It iterates through the corestore, inspects the package.json of the associated Hyperdrive, and returns the links of matching metadata cores.

Parameters:

• params.name: The string name of the package to search for.

const links = await sidecar.getLinksByName({ name: 'my-app-name' }, client)