direnv integration - updating PATH (#213)

## Summary
- Added a small command that updates the PATH to use devbox packages
when users integration direnv and cd into a devbox project.
- Added guidelines on how to setup `direnv` and integrate with devbox.

## How was it tested?
- Have direnv installed and hooked to your shell
- Create an empty directory
- `devbox init`
- `devbox shell` then `exit`
- `touch .envrc` then put the following inside it:
   ```bash
    use_devbox() {
      watch_file devbox.json
      eval $(devbox setup-direnv)
    }
    use devbox
     ```
- `direnv allow`
- Compare running `which python3` or `which go` from inside the
directory and outside

Author: mohsenari

boxcli/shell.go

@@ -13,42 +13,56 @@ import (
 	"go.jetpack.io/devbox"
 )
 
+type shellFlags struct {
+	PrintEnv bool
+}
+
 func ShellCmd() *cobra.Command {
+	flags := &shellFlags{}
 	command := &cobra.Command{
 		Use:               "shell [<dir>] -- [<cmd>]",
 		Short:             "Start a new shell or run a command with access to your packages",
 		Long:              "Start a new shell or run a command with access to your packages. \nIf invoked without `cmd`, this will start an interactive shell based on the devbox.json in your current directory, or the directory provided with `dir`. \nIf invoked with a `cmd`, this will start a shell based on the devbox.json provided in `dir`, run the command, and then exit.",
 		Args:              validateShellArgs,
 		PersistentPreRunE: nixShellPersistentPreRunE,
-		RunE:              runShellCmd,
+		RunE:              runShellCmd(flags),
 	}
+	command.Flags().BoolVar(
+		&flags.PrintEnv, "print-env", false, "Print script to setup shell environment")
 	return command
 }
 
-func runShellCmd(cmd *cobra.Command, args []string) error {
-	path, cmds := parseShellArgs(cmd, args)
+func runShellCmd(flags *shellFlags) runFunc {
+	return func(cmd *cobra.Command, args []string) error {
+		path, cmds := parseShellArgs(cmd, args)
 
-	// Check the directory exists.
-	box, err := devbox.Open(path, os.Stdout)
-	if err != nil {
-		return errors.WithStack(err)
-	}
+		// Check the directory exists.
+		box, err := devbox.Open(path, os.Stdout)
+		if err != nil {
+			return errors.WithStack(err)
+		}
 
-	if devbox.IsDevboxShellEnabled() {
-		return errors.New("You are already in an active devbox shell.\nRun 'exit' before calling devbox shell again. Shell inception is not supported.")
-	}
+		if flags.PrintEnv {
+			// return here to prevent opening a devbox shell
+			return box.PrintShellEnv()
+		}
 
-	if len(cmds) > 0 {
-		err = box.Exec(cmds...)
-	} else {
-		err = box.Shell()
-	}
+		if devbox.IsDevboxShellEnabled() {
+			return errors.New("You are already in an active devbox shell.\nRun 'exit' before calling devbox shell again. Shell inception is not supported.")
+		}
+
+		if len(cmds) > 0 {
+			err = box.Exec(cmds...)
+		} else {
+			err = box.Shell()
+		}
 
-	var exitErr *exec.ExitError
-	if errors.As(err, &exitErr) {
-		return nil
+		var exitErr *exec.ExitError
+		if errors.As(err, &exitErr) {
+			return nil
+		}
+		return err
 	}
-	return err
 }
 
 func nixShellPersistentPreRunE(cmd *cobra.Command, args []string) error {

devbox.go

@@ -207,6 +207,17 @@ func (d *Devbox) Exec(cmds ...string) error {
 	return nix.Exec(nixDir, cmds)
 }
 
+func (d *Devbox) PrintShellEnv() error {
+	profileBinDir, err := d.profileBinDir()
+	if err != nil {
+		return errors.WithStack(err)
+	}
+	// TODO: For now we just updated the PATH but this may need to evolve
+	// to essentially a parsed shellrc.tmpl
+	fmt.Fprintf(d.writer, "export PATH=\"%s:$PATH\"", profileBinDir)
+	return nil
+}
+
 // saveCfg writes the config file to the devbox directory.
 func (d *Devbox) saveCfg() error {
 	cfgPath := filepath.Join(d.srcDir, configFilename)

docs/app/docs/cli_reference/devbox_shell.md

@@ -15,6 +15,7 @@ devbox shell [<dir>] -- [<cmd>] [flags]
 ## Options
 
 ```text
+  --print-env  Print a script to setup a devbox shell environment
   -h, --help   help for shell
 ```
 

docs/app/docs/ide_configuration/direnv.md

@@ -0,0 +1,43 @@
+---
+title: direnv configuration
+---
+
+
+## direnv
+___
+[direnv](https://direnv.net) is an open source environment management tool that allows setting unique environment variables per directory in your file system. This guide covers how to configure direnv to seemlessly work with a devbox project.
+
+### Prerequisites
+* Install direnv and hook it to your shell. Follow [this guide](https://direnv.net/#basic-installation) if you haven't done it. 
+
+### Setting up with Devbox Shell and direnv
+
+Note: If you already have a devbox project you may skip to step 3.
+
+1. `devbox init` if you don't have a devbox.json in the root directory of your project.
+2. `devbox shell -- 'ls'` to activate devbox shell temporarily and make sure dependencies mentioned in your devbox.json are installed.
+3. Create a new file, name it `.envrc` and put the following snippet inside it:
+    ```bash
+    use_devbox() {
+        watch_file devbox.json
+        eval $(devbox shell --print-env)
+    }
+    use devbox
+    ```
+4. Run `direnv allow` to give permission to `direnv` to setup your environment variables.
+5. At this point, your project directory is setup so that every time you `cd` into it, the binaries from your devbox shell will be used. To test this, you can compare running `which python3` from your project directory and outside.
+
+### Global settings for direnv
+
+Note that every time changes are made to `devbox.json` via `devbox add ...`, `devbox rm ...` or directly editing the file, requires `direnv allow` to run so that `direnv` can setup the new changes.
+
+Alternatively, a project directory can be whitelisted so that changes will be automatically picked up by `direnv`. This is done by adding following snippet to direnv config file typically at `~/.config/direnv/direnv.toml`. You can create the file and directory if it doesn't exist.
+
+```toml
+[whitelist]
+prefix = [ "/absolute/path/to/project" ]
+
+```
+<!-- TODO: add steps for vscode integration -->
+
+If this guide is missing something, feel free to contribute by opening a [pull request](https://github.com/jetpack-io/devbox/pulls) in Github.