From 3367920371ee5ed3880ed26cc19d886eb2166f7a Mon Sep 17 00:00:00 2001 From: Peter Harpending Date: Wed, 12 Oct 2022 01:19:17 -0600 Subject: [PATCH] improve sidekick README --- sidekick/README.md | 125 +++++++++++---------------------------------- 1 file changed, 31 insertions(+), 94 deletions(-) diff --git a/sidekick/README.md b/sidekick/README.md index be83c94..286083d 100644 --- a/sidekick/README.md +++ b/sidekick/README.md @@ -4,38 +4,22 @@ Sidekick is a simple JavaScript library for talking to an Aeternity browser wallet extension such as Jaeck Russell or Superhero from the document context of a webpage. -> One of the most important things for designing a computer, which I -> think most designers don't do, is you study the problem you want to -> solve. And then use what you learn from studying the problem you -> want to solve to put in the mechanisms needed to solve it in the -> computer you're building. No more, no less. - -— Gerald Jay Sussman - - - # Build Prereqs Assuming Ubuntu 18.04. Adapt these instructions for your own system. You need -- `npm` to build TypeScript +- `npm` to build TypeScript (and TypeDoc if you want to build the + documentation) - `tsc` to compile -- [`jx`][jx] to orchestrate the build properly -- Python 3.6 or later to run `jx` +- [jex](../utils/jex/) to facilitate the build -[jx]: https://gitlab.com/pharpend/jx/-/tree/master/#jx-secure-typescript-package-manager - -Steps +Steps: sudo snap refresh sudo snap install node --channel 18/stable npm install -g typescript - wget https://gitlab.com/pharpend/jx/-/raw/master/jx -O ~/.local/bin/jx - chmod u+x ~/.local/bin/jx - - ## Protip: avoid using `sudo npm install -g` @@ -53,84 +37,37 @@ NPM_PACKAGES="${HOME}/.npm-packages" export PATH=$NPM_PACKAGES/bin:$PATH ``` +# Build Steps +## 1. Build dependencies -# Build - - make - - -# Examples - -There is a repository of examples at https://gitlab.com/pharpend/sidekick_examples.git - -# What sidekick is NOT - -Sidekick is **not** ideal if you operate in the Node/NPM ecosystem. If you are -working in the Node/NPM ecosystem, you probably want the [Aeternity JavaScript -SDK](https://github.com/aeternity/aepp-sdk-js/). Every single -Aeternity-related thing you could ever possibly want to do is possible to -accomplish with the SDK. - -All that Sidekick knows how to do is talk to a browser wallet extension. In an -application, there is a great deal of necessary functionality (e.g. forming -transactions for the wallet to sign) which sidekick assumes your server-side -code has already handled. - -In all software there is a tradeoff between simplicity and number of features. -Sidekick is very simple: 2300 lines of TypeScript, including comments, with no -dependencies. Therefore Sidekick intentionally only has a very limited set of -features. - - - -# Where is the NPM package or the webpack bundle? - -There isn't one. - -## Why? - -Sidekick is a library that deals with cryptocurrency. The security -model is based on transparency and trust. A user must be able to -inspect code that is running on his hardware handling his money. - -We don't support NPM because of the security issues that NPM -introduces. Briefly, the code can change at any time under the -developer's nose without the developer knowing. The [leftpad -debacle][lpad] and the [RIAEvangelist debacle][ria] are good examples -of the types of vulnerabilities that package managers like NPM -enable. - -[lpad]: https://archive.ph/Qsh7j -[ria]: https://archive.ph/OF5I9 - -We don't use something like webpack because that introduces an opaque -rewrite using an untrusted tool. Webpack could plausibly alter the -runtime behavior of the program, and we would have no way to detect -that. Even if we trusted webpack, how do we obtain webpack? NPM. -So. - -It is debatable whether or not we should trust the TypeScript -compiler (TSC). On the whole, TSC probably makes Sidekick more -secure, simply by virtue of increasing overall code quality and -eliminating the largest categories of potential bugs. Moreover, the -output that TSC produces is human-readable, and has a very -straightforward mapping to the original source code. A human can -easily read the TSC-generated JavaScript tree, even without the aid -of the source map, and have a high degree of faith that the code is -trustworthy and that TSC is behaving as promised. - - - - -Source: https://github.com/sindresorhus/guides/blob/main/npm-global-without-sudo.md - - -# How to build and view documentation +The examples require `parasite` as a dependency, but sidekick itself does not. ``` -make build_docs -make serve_docs +~/src/vanillae $ cd libs/awcp +~/src/vanillae/libs/awcp $ jex dwim+ +~/src/vanillae/libs/awcp $ cd ../parasite +~/src/vanillae/libs/parasite $ jex dwim+ ``` +## 2. Build sidekick +``` +~/src/vanillae/libs/parasite $ cd ../../sidekick +~/src/vanillae/sidekick $ jex dwim+ +``` + +## 3. Build examples + +Note the `-`, not the `+`. The difference is that `-` just builds the project, +but does not package it. + +``` +~/src/vanillae/sidekick $ cd examples +~/src/vanillae/sidekick/examples $ jex dwim- +~/src/vanillae/sidekick/examples $ python3 -m http.server 8000 +``` + +Navigate to `http://localhost:8000/` in your browser to see the examples + +The examples are the best documentation, for now.