.some(.md)

.gitbook.yaml

@@ -0,0 +1 @@
+root: ./docs/

README.md

@@ -0,0 +1,7 @@
+# tea/docs
+
+This documentation is processed by [gitbook.com] and published to
+[docs.tea.xyz].
+
+[gitbook.com]: https://gitbook.com
+[docs.tea.xyz]: https://docs.tea.xyz

docs/FAQ.md

@@ -0,0 +1,122 @@
+## How do I update?
+
+```sh
+$ tea --sync
+# ^^ updates the pantries, and any packages in the virtual-environment
+
+$ tea --sync +deno.land
+# ^^ updates specific packages
+
+$ sh <(curl tea.xyz) --sync
+# ^^ updates `tea` as well
+```
+
+## How do I view what is stowed?
+
+```sh
+open $(tea --prefix)
+```
+
+We hope to improve this UX very soon.
+
+## I need a tool in `PATH` (aka `brew install`)
+
+Symlinks to `tea` automatically invoke their namesake:
+
+```sh
+$ ln -s $(which tea) /usr/local/bin/bun
+$ bun --version
+tea: installing bun…
+bun 0.4.0
+
+# you can version tools this way too
+$ ln -s $(which tea) /usr/local/bin/bun~0.3
+$ bun~0.3 --version
+tea: installing bun=0.3.0
+bun 0.3.0
+
+# if you prefer you can symlink with a `tea+` or `tea_` prefix
+$ ln -s $(which tea) /usr/local/bin/tea+node
+$ tea+node --version
+v19.3.0
+```
+
+{% hint style="warning" %}
+This doesn’t work on Linux; you’ll need to use hard-links. \
+This is a platform limitation we cannot work around 😞
+{% endhint %}
+
+## How do I use tea with editors like VSCode?
+
+We intend to make a VSCode extension that automatically fetches the
+environment for the active workspace. In the meantime, add tools to your `PATH`
+as described in the above FAQ.
+
+## What are these `^`, `~`, etc. symbols?
+
+tea adheres to [semantic versioning](https://semver.org), and uses
+[`semver`](https://github.com/npm/node-semver#versions) for parsing versions.
+
+## How do I find available packages?
+
+We list all packages at [tea.xyz](https://tea.xyz/+/).
+Or `open ~/.tea/tea.xyz/var/pantry`.
+We hope to improve this UX very soon, too.
+
+## Will you support platform `foo`?
+
+We want to support *all* platforms.
+Start a [discussion] and let’s talk about how to move forward with that.
+
+## What happened to executable markdown?
+
+We may revisit it, but we realized quickly that because tea makes it
+so trivial to use anything from the open source ecosystem, it also makes it trivial
+for you as a developer to use [`xc`]†, `make` or [`just`] or any of the
+myriad of other tools that are tightly scoped to the initial goals of
+executable markdown.
+
+> † xc actually *is* a more mature implementation of executable markdown and
+> we think you should definitely check it out.
+
+[`xc`]: https://github.com/joerdav/xc
+[`just`]: https://just.systems
+
+## What are you doing to my computer?
+
+We install compartmentalized packages to `~/.tea`.
+
+We then suggest you add our one-liner to your shell `.rc` and a symlink
+for `/usr/local/bin/tea`.
+
+We might not have installed tea, if you used `sh <(curl tea.xyz) foo` and tea
+wasn’t already installed, then we only fetched any packages, including
+tea, temporarily.
+
+## Packaging up tea packages with your `.app`, etc.
+
+Our packages are relocatable by default. Just keep the directory structure the
+same. And ofc. you are licensed to do so (by us! each package has its own
+license!). Honestly we think you should
+absolutely bundle and deploy tea’s prefix with your software. We designed it
+so that it would be easier for you to do this than anything that has come
+before.
+
+## I thought you were decentralized and web3 and shit
+
+tea is creating new technologies that will change how open source is funded.
+tea/cli is an essential part of that endeavor and is released
+prior to our protocol in order to bootstrap our holistic vision.
+
+We don’t subscribe to any particular “web” at tea.xyz, our blockchain
+component will be an implementation detail that you won’t need to think about
+(but we think you will want to).
+
+Check out our [white paper] for more information.
+
+# I have another question
+
+Start a [discussion] and we’ll get back to you.
+
+[discussion]: https://github.com/orgs/teaxyz/discussions
+[white paper]: https://github.com/teaxyz/white-paper

docs/README.md

@@ -0,0 +1,24 @@
+`tea` is the next-generation, cross-platform package manager from the creator
+of [`brew`].
+
+# Getting Started
+
+| <p>​<a href="get-started/install-tea.md/">Quickstart</a><br>Get started fast with our installer</p> | <p><a href="get-started/without-installer.md">Without the Installer</a><br>`tea`’s a standalone binary download</p> |
+| ----- | ----- |
+| <p>​<a href="using-tea/">Using `tea`</a><br>A guide to the simple, yet powerful `tea`/cli</p> |
+
+# Features
+
+| <p>​<a href="magic.md">Magic</a><br>Put the entire open source ecosystem at your fingertips</p> | <p><a href="using-tea/developer-environments.md">Developer Environments</a><br>Thin containers for work projects</p> | <p>​<a href="using-tea/tea-scripts.md">`tea` Scripts</a><br>Giving scripts more than just `bash` |
+| ----- | ----- | ----- |
+
+# Support
+
+We appreciate your using `tea` and would love to help you solve any problems
+you may be having.
+
+* [github.com/orgs/teaxyz/discussions](https://github.com/orgs/teaxyz/discussions)
+* [discord.tea.xyz](https://discord.tea.xyz)
+
+
+[`brew`]: https://brew.sh

docs/SUMMARY.md

@@ -0,0 +1,31 @@
+‌# Summary​
+
+* [Contents](README.md)
+
+## Getting Started
+​
+* [Installing `tea`](get-started/install-tea.md)
+    * [Without the Installer](get-started/without-installer.md)
+* [Using tea](using-tea/README.md)
+
+
+## Features
+* [Magic](magic.md)
+    * [Using `tea` without Magic](using-tea/without-magic.md)
+* [Developer Environments](using-tea/developer-environments.md)
+* [`tea` Scripts](using-tea/tea-scripts.md)
+
+
+## Packaging
+
+* [The Pantry](packaging/README.md)
+
+​
+## Appendix
+​
+* [FAQ](FAQ.md)
+* [Uninstalling `tea`](appendix/uninstall-tea.md)
+* [GitHub Actions](appendix/github-actions.md)
+* [The `tea` One-Liner](using-tea/the-tea-one-liner.md)
+* [Troubleshooting](troubleshooting.md)
+* [Suffix](appendix.md)

docs/appendix.md

@@ -0,0 +1,58 @@
+# A Brief Diatribe
+
+Every programming language, every build system, every compiler, web server, database and email client seem to gravitate towards adding infinite features and complexity so that their users can do ever more and more.
+
+This is contrary to the UNIX philosophy: tools should do one thing and —by being tight and focused— do it damn well. If they are composable and flexible then they can be combined, piped and leveraged into a larger, more capable toolbox. The Internet is built with this toolbox.
+
+Nowadays every programming language reimplements the same set of libraries and tools because using a well-maintained, mature and portable library that lives higher up the stack adds too much complexity. This extends the adolescence of new languages, results in no single language even becoming truly state of the art and leads to degrees of duplication that make the open source ecosystem fragile. This is to the detriment of all software, everywhere.
+
+tea removes this complexity and adds some much needed robustness for the good of the entire open source ecosystem, the larger Internet and the whole world of software.
+
+
+# What is tea?
+
+tea is not a package manager.
+
+*tea is unified packaging infrastructure*.
+
+From the creator of [`brew`], tea is a standalone, binary download for all
+platforms that puts the entire open
+source ecosystem at your fingertips. Casually and effortlessly use the latest
+and greatest or the oldest and most mature from any layer of any stack. Break
+down the silos between programming communities, throw together scripts that
+use entirely separate tools and languages and share them with the world with
+a simple one-liner.
+
+All you need is `tea`.
+
+> tea is pre v1. This means there may still be some rough edges in day to day use.
+> It also means that you should absolutely get involved. This is the key and
+> golden time when getting involved is both easy and hugely fun. We look
+> forward to meeting you 👊
+
+
+# Our Goals
+
+- To create incredible tooling: the base of every developer’s stack.
+- To cater to our users, not ourselves.
+- To take open source to the next level by funding the unpaid maintainers who thanklessly create the stack that powers the Internet.
+
+
+# Philosophy
+
+* Be non‑intrusive
+    > don’t interfere with our users’ systems or habits
+* Be “just works”
+    > our users have better things to do than fix us
+* Error messages must be excellent
+    > trust that if it comes to it, our users can fix things provided we give
+    > them a helping hand
+* Be intuitive
+    > being clever is good—but don’t be so clever nobody gets it
+* Resist complexity
+    > rethink the problem until a simpler solution emerges
+* Be fast
+    > we are in the way of our users’ real work, don’t make them wait
+
+
+[`brew`]: https://brew.sh

docs/appendix/github-actions.md

@@ -0,0 +1,25 @@
+You can easily use `tea` in GitHub Actions:
+
+```yaml
+- uses: teaxyz/setup@v0
+```
+
+* Our action installs your dependencies and makes them and their environments
+available for the rest of the run.
+* Our action has no dependencies and will
+work in very slim docker containers.
+
+See its GitHub for usage information
+[github.com/teaxyz/setup](https://github.com/teaxyz/setup).
+
+
+## Other CI Services
+
+```sh
+sh <(curl https://tea.xyz) --yes
+
+set -a
+tea -SE
+```
+
+Will export the environment for your developer environment.

docs/appendix/uninstall-tea.md

@@ -0,0 +1,31 @@
+# Uninstalling `tea`
+
+You can delete `~/.tea` or if you customized tea’s prefix, that directory.
+
+```sh
+rm -rf ~/.tea
+```
+
+Remove the one liner in your `~/.shellrc`; one of:
+
+* `~/.zshrc`
+* `~/.bashrc`
+* `~/.config/fish/config.fish`
+* etc.
+
+That’s it!
+
+
+{% hint style="warning" %}
+## Caveats
+
+Though not a problem unique to `tea` you should note that tools installed with
+`tea` may have polluted your system during use. Check directories like:
+
+* `~/.local`
+* `~/.gem`
+* `~/.npm`
+* `~/.node`
+* etc.
+
+{% endhint %}

docs/get-started/install-tea.md

@@ -0,0 +1,57 @@
+# Getting Started with the Installer
+
+The easiest way to install tea is with our installer:
+
+```sh
+sh <(curl https://tea.xyz)
+```
+
+The script installs to `~/.tea` and sets up magic (we ask politely first).
+
+{% hint style="info" %}
+### Want to Read the Sources for that Script First?
+[https://github.com/teaxyz/setup/blob/main/install.sh]
+{% endhint %}
+
+
+## What Happens
+
+* Firstly we confirm you’re cool before we do *anything*
+    * If so we install tea to `~/.tea`
+    * If not we exit with failure
+* We then ask if you want [magic](../using-tea/with-magic.md)
+    * If so we add one line to your `~/.shellrc`
+    * If not we exit successfully
+
+<details><summary><code>`preview.gif`</code></summary>
+
+![charm.sh/vhs recording](https://teaxyz.github.io/setup/sample.gif)
+
+</details>
+
+
+## It’s Not Just an Installer
+
+If you run it again, it’ll update `tea`.
+
+### That’s Not All
+
+The tea one-liner can also be used to provide your users a temporary sandbox
+for your projects. They can use the power of tea to try out your project
+without installing tea or your project.
+
+{% hint style="success" %}
+See [The `tea` One-Liner](/using-tea/the-tea-one-liner.md) for more details
+{% endhint %}
+
+
+## Linux Caveats
+
+On Linux you may need some pre-requisite packages from your system packager.
+This is a temporary situation that we are fixing.
+
+We are keeping a list of pre-reqs in [this script].
+
+
+[this script]: https://github.com/teaxyz/setup/blob/main/install-pre-reqs.sh
+[https://github.com/teaxyz/setup/blob/main/install.sh]: https://github.com/teaxyz/setup/blob/main/install.sh

docs/get-started/without-installer.md

@@ -0,0 +1,50 @@
+# Installing `tea` Without the Installer
+
+`tea` is a standalone binary and you can prove it:
+
+```sh
+$ curl -Lo tea https://tea.xyz/$(uname)/$(uname -m)
+$ chmod u+x ./tea
+
+$ echo '# tea *really is* a standalone binary' | ./tea --sync glow -
+tea: installing charm.sh/glow
+# `tea --sync` updates pkgs, but you have to call it *at least once*
+# our installer does this for you normally
+```
+
+{% hint style="warning" %}
+`tea` stows packages in `~/.tea` and thus the above will do that!
+{% endhint %}
+
+## A Fancy One-Liner
+
+Here’s a one-liner that downloads `tea`, makes it executable and puts it in
+`/usr/local/bin`:
+
+```sh
+sudo install -m 755 \
+  <(curl --compressed -LSsf https://tea.xyz/$(uname)/$(uname -m)) \
+  /usr/local/bin/tea
+```
+
+## Via [Homebrew](https://brew.sh)
+
+We love `brew` (`tea`’s its spiritual successor) so you can use our tap:
+
+```sh
+brew install teaxyz/pkgs/tea-cli
+```
+
+## Via Docker
+
+```sh
+docker run --rm -it teaxyz/cli
+```
+
+{% hint style="info" %}
+The Docker image is built nightly: [https://github.com/teaxyz/infuser]
+{% endhint %}
+
+
+[Docker]: https://docker.com
+[https://github.com/teaxyz/infuser]: https://github.com/teaxyz/infuser

docs/magic.md

@@ -0,0 +1,97 @@
+# Magic
+
+Our magic puts the entire open source ecosystem at your fingertips.
+Our installer enables it by adding some hooks to your shell:
+
+* A hook when changing directory that sets up project environments
+  * Environments are just shell environment variables
+* A hook for the “command not found” scenario that installs that command
+    before running it
+
+{% hint style="info" %}
+Magic is entirely optional, tea is still entirely usable without it.
+{% endhint %}
+
+{% hint style="warning" %}
+Our “command not found” magic only works at a terminal prompt. Thus eg.
+VSCode won’t magically find `deno`. Shell scripts won’t automatically
+install tools they try to run. This is intentional. *Magic should not lead
+to anarchy*.
+{% endhint %}
+
+Our magic means that tea packages are not generally accessible from the rest
+of the system.
+
+```sh
+$ which bun
+bun not found
+
+$ tea --dry-run bun --version
+imagined: bun.sh^0.4
+~/.tea/bun.sh/v0.4.0/bin/bun --version
+
+$ bun --version
+tea: installing bun.sh^0.4
+0.4.0
+
+$ which bun
+bun not found
+# `bun` is not in your `PATH`
+# ∵ tea doesn’t install packages
+# ∴ using tea doesn’t compromise your system’s integrity
+
+$ tea bun --version
+0.4.0
+# ^^ the same as `bun --version` but without magic
+```
+
+All packages are installed, segregated and encapsulated in `~/.tea` for other
+parts of your system to access them you may have to make them accessible using
+`tea +pkg` syntax.
+
+
+## Symlink Magic
+
+Symlinks to tea are resolved to that tool. Eg:
+
+```sh
+$ ln -s tea node
+$ node
+Welcome to Node 16.7.0
+>
+```
+
+We support appending [semver](semver.org) ranges:
+
+```sh
+$ ln -s tea node^14
+$ node
+Welcome to Node 14.2.0
+> ^D
+
+$ ln -s tea node~16.6
+$ node
+Welcome to Node 16.6.1
+>
+```
+
+
+## Using Magic in Shell Scripts
+
+Our magic is not automatically added to scripts, but you can manually add it:
+
+```sh
+source <(tea --magic=bash)
+                   # ^^ you have to specify which shell tho
+```
+
+And of course you can also use our one-liner:
+
+```sh
+source <(curl tea.xyz | sh -s -- --magic=bash)
+```
+
+Thus you can make a script that can effortlessly use any tool from the open
+source ecosystem. If they have tea installed it uses their installation, if
+not it installs everything (including tea itself) to a temporary sandbox
+that’s gone when the script completes.

docs/packaging/README.md

@@ -0,0 +1,25 @@
+# Packaging
+
+There’s millions of open source projects and `tea` needs your help to package
+them up!
+
+{% hint style="info" %}
+Visit the [https://github.com/teaxyz/pantry] for the full documentation.
+{% endhint %}
+
+Our package listing can be viewed at our homepage: [tea.xyz/+/](https://tea.xyz/+/)
+
+
+# Packagers Who Care
+
+You trust us to just work and make your workflows happen.
+We take this job seriously and we go the extra mile on a per-package basis,
+eg. our `git` ignores `.DS_Store` files by default, and our RubyGems defaults to
+user-installs and ensures gems are in `PATH`. Also we insist our packages
+are relocatable, which is why we can install in your home directory (but this
+also means you could pick up the whole `~/.tea` directory and bundle it with
+your app.) We also begin packaging new releases almost immediately as soon as
+they go live using various automations.
+
+
+[https://github.com/teaxyz/pantry]: https://github.com/teaxyz/pantry

docs/troubleshooting.md

@@ -0,0 +1,20 @@
+
+# Troubleshooting
+
+## `env: tea: No such file or directory`
+
+If you got this error message, you need to install tea:
+`sh <(curl -Ssf https://tea.xyz)`.
+
+## Changing directory takes a long time sometimes
+
+This is a known and insidious bug. Please open a [ticket] and report it to us.
+tea’s magic should never significantly slow down directory changes.
+
+## Unquarantining on macOS
+
+If the macOS GateKeeper says no, try this:
+
+```sh
+$ xattr -d com.apple.quarantine ./tea
+```

docs/using-tea/developer-environments.md

@@ -0,0 +1,114 @@
+# Developer Environments
+
+Every project you work on needs different tools with different versions.
+Installing those tools globally *makes no sense* and could even cause subtle
+bugs during dev.
+
+tea can determine the tools a project directory needs based on the files it
+finds. With our shell magic just step into the project directory
+and type commands; tea automatically fetches the specific versions those
+projects need and runs them.
+
+We try to be as clever as possible, eg. we parse the node version out of
+a GitHub Action’s `action.yml`. If we see a `.node-version` file, we add that
+version of node to the environment. We want to support everything that makes
+sense (your PRs are *very* welcome!)
+
+Where there isn’t a convention for specifying tool versions, you can add
+YAML front matter to its configuration file. For example, if we’re
+talking a python poetry project, then you can specify your python version by
+adding YAML front matter to its `pyproject.toml`:
+
+```sh
+$ cat <<EoYAML >> pyproject.toml
+# ---
+# dependencies:
+#   python.org: ^3.11.3
+# ---
+EoYAML
+```
+
+If your poetry project needs other non pypa dependencies (like a c compiler)
+then you can add them there too (eg. `llvm.org`, our deps are always named
+after project homepages because then you just google it and there’s no
+ambiguity).
+
+If you prefer we also support extracting your deps from a markdown table
+under a `# Dependencies` section in your `README.md`:
+
+```sh
+$ cat <<EOF >>my-project/README.md
+# Dependencies
+| Project    | Version |
+| ---------- | ------- |
+| go.dev     | ^1      |
+EOF
+```
+
+Using your `README` is *kinda* neat; it makes this data both machine and human
+readable.
+
+Finally, you can just use `tea.yaml` (or `.tea.yaml`) if you like.
+
+<details><summary><i>PSA:</i> Stop using Docker</summary><br>
+
+Docker is great for deployment and cross compilation, but… let’s face it: it
+sucks for dev.
+
+*Docker stifles builders*.
+It constricts you; you’re immalleable; tech marches onwards but your docker
+container remains immobile. *Nobody knows how to use `docker`*. Once that
+`Dockerfile` is set up, nobody dares touch it.
+
+And let’s face it, getting your personal dev and debug tools working inside
+that image is incredibly frustrating. Why limit your potential?
+
+Keep deploying with Docker, but use tea to develop.
+
+Then when you do deploy you may as well install those deps with tea.
+
+Frankly, tea is properly versioned (unlike system packagers) so with tea your
+deployments actually remain *more* stable.
+</details>
+
+
+## Caveats
+
+We still need to do a bit of work here. We don’t install any packages when
+you step into a directory as that would violate the principle of least
+surprise. But this may mean the full environment doesn’t work initially.
+You can fix this with a `tea -SE && cd .`. We’re working on improving this.
+
+## Supplementing the Environment
+
+There are all sorts of variables a developer needs when working on a project
+and tea aims to make them available to you. Thus we provide `SRCROOT` and
+`VERSION`‡ in addition to everything else required to make your devenv
+function. To see the full environment for your project run `tea -En` or simply
+`env`.
+
+> ‡ extracted from the `README.md` or `VERSION` files.
+
+## Supported Files
+
+* `package.json`
+* `deno.json`, `deno.jsonc`
+* `pyproject.toml`, `pipfile`, `requirements.txt`
+* `go.mod`
+* `VERSION`
+* `.node-version`
+* `cargo.toml`
+* `Gemfile`
+* `tea.yaml`, `.tea.yml`
+* `README.md`
+* `.envrc`
+
+## I added YAML front matter and it doesn’t work; what now?
+
+* After changing any files you need to do a `cd .` to reload the environment.
+* While debugging you can do `tea -E` to see if we’re picking up your changes.
+* If it still doesn’t work open a [ticket]. This is either a bug or we don’t
+    support your toolset yet.
+
+
+[ticket]: https://github.com/teaxyz/cli/issues/new

docs/using-tea/tea-scripts.md

@@ -0,0 +1,6 @@
+# `tea` Scripts
+
+* `tea` reads the shebang of a script and installs that interpreter
+* If no shebang the extension is used
+* Any YAML Front Matter will be read in addition allowing further packages to
+    be installed for that script

docs/using-tea/the-tea-one-liner.md

@@ -0,0 +1,36 @@
+## As a Proxy
+
+Arguments passed to the one-liner act as though they were passed to `tea`
+itself.
+
+```sh
+$ sh <(curl tea.xyz) bun run start
+bun: start…
+```
+
+{% hint style="info" %}
+Notably, if `tea` is not installed the one-liner *does not install `tea`*.
+Instead it stows and packages in a temporary sandbox and runs them there.
+
+This may be useful for your getting started guides so users can try your tools
+out without consequences.
+{% endhint %}
+
+
+## As an Updater
+
+The installer will update tea if it’s already installed.
+
+
+## All Options
+
+```sh
+sh <(curl tea.xyz) --prefix /opt/tea
+# ^^ installs tea to /opt/tea
+
+sh <(curl tea.xyz) --version 0.24.10
+# ^^ installs a specific version of tea/cli
+
+sh <(curl tea.xyz) --yes
+# assumes yes for all questions (for headless environments)
+```

docs/using-tea/without-magic.md

@@ -0,0 +1,37 @@
+
+## Using `tea` Without Magic
+
+Simply prefix everything with `tea`, eg. `tea npm start`.
+
+
+## Using Developer Environments Without Magic
+
+Simply prefix commands with `tea -E`, eg. `tea -E npm start`.
+
+
+## Injecting Packages without Using Magic
+
+Our `+pkg` syntax *injects* packages into an environment, the commands are
+then run in that environment.
+
+```sh
+# a script that needs `convert`
+$ tea +imagemagick.org my-script.sh
+
+# a VHS script that needs `wget`
+$ tea +gnu.org/wget vhs demo.tape
+
+# if tea doesn’t provide the package, it passes the args through to your system
+$ tea +neovim.io which nvim
+~/.tea/neovim.io/v0.8.2/bin/nvim
+
+# in fact, `tea` is like an “env++”: just like `env` our purpose is to
+# construct environments. Our `++` is: we also fetch packages. Thus, if you
+# don’t specify what we should do with the environment, we dump it:
+$ tea +zlib.net
+MANPATH=/Users/mxl/.tea/zlib.net/v1.2.13/share/man:/usr/share/man
+PKG_CONFIG_PATH=/Users/mxl/.tea/zlib.net/v1.2.13/lib/pkgconfig
+LIBRARY_PATH=/Users/mxl/.tea/zlib.net/v1.2.13/lib
+CPATH=/Users/mxl/.tea/zlib.net/v1.2.13/include
+XDG_DATA_DIRS=/Users/mxl/.tea/zlib.net/v1.2.13/share
+```