path: root/readme.org

#+TITLE: Shackle Shell
#+AUTHOR: Justin Wernick

A shell for restricting access on a version control server.

This is intended as a replacement for [[https://git-scm.com/docs/git-shell][Git Shell]], but with a few opinionated
differences:

- Additional commands, like creating new repos, are built in. No extension with
  shell scripts.
- Strict enforcement of a specified directory structure. Git push / pull
  commands only work for these paths. New repos are created in these paths.
  - Private git repos are created in =~/git/<username>/<reponame>.git=
  - Shared git repos are created in =~/git/<groupname>/<reponame>.git=
- Better interactive UX than Git Shell, including:
  - Command history (limited to the current session).
  - Emacs-style shortcuts (eg =Ctrl+a= to move cursor to the beginning of line).
  - Docs available for all commands, available in the shell itself.
- (coming soon!) Support for other other version control systems.

* Getting Started

** Usage

Shackle Shell is intended to be set as the default shell for a user on a git
server, where the user connects over SSH (see the Installation section below).

When you log in over SSH, you'll see a prompt, ready for you to type commands.

#+begin_src fundamental
  >
#+end_src

You can see the built in help by running the =help= command.

#+begin_src fundamental
  > help
  Usage: <COMMAND>

  Commands:
    init              Create a new repository
    list              List all repositories available
    set-description   Sets the description of a repository, as shown in the CLI listing and web interfaces
    set-branch        Sets the main branch of the repository
    exit              Quit the shell
    git-upload-pack   Server side command required to git fetch from the server
    git-receive-pack  Server side command required by git push to the server
    help              Print this message or the help of the given subcommand(s)

  Options:
    -h, --help  Print help
#+end_src

The =init= command is used to create a new repo. In its simplest form, you just
provide it with the name of your new repo. This will create a git repo with
individual ownership.

#+begin_src fundamental
  > init awesome-project-idea
  Successfully created "git/shukkie/awesome-project-idea.git"
#+end_src

The path given here is relative to your home directory. So the full URL to clone
this repo is =<username>@<server domain>:<git path>=

#+begin_src fundamental
  $ git clone shukkie@example.com:git/shukkie/awesome-project-idea.git
#+end_src

You can learn its advanced options by using the =--help= flag. This works for
all of the options, and is a great way to learn what all the commands do.

#+begin_src fundamental
  > init --help
  Create a new repository

  Usage: init [OPTIONS] <REPO_NAME>

  Arguments:
    <REPO_NAME>  Name of the new repository

  Options:
        --group <GROUP>              Share repository ownership with the specified group (user must be a member of the group)
        --description <DESCRIPTION>  Sets the description of the repository, as shown in the CLI listing and web interfaces
        --branch <BRANCH>            Sets the main branch of the repository [default: main]
    -h, --help                       Print help
#+end_src

** Installation

#+begin_src sh
  cargo install --git https://code.worthe-it.co.za/shackle.git/ --root /opt/bin/shackle --force
#+end_src

# TODO

# - cargo install to build from source
# - set as the user's shell
# - create the appropriate directory structure
# - requires git installed on the server
# - I assume users will be connecting over SSH. This is not enforced by the shell.

* Operating System Support

Currently, Shackle Shell only supports running on Linux.

It will likely work on other Unix-like platforms, such as MacOS, but this is not
currently tested, and there are currently no plans to do so. I would not expect
it to work on Windows.

* Development Guide

** Development Environment Setup

- Rust
  - This project is built using the Rust programming language, and its build
    tool Cargo. Information on how to install these tools is available on [[https://www.rust-lang.org/learn/get-started][the
    Rust website]].
- C Compiler
  - This is used to built one of the dependencies, libgit2. This can be
    obtained from your operating system's package manager.
- Docker
  - Some of the tests use Docker to create a simulated environment. This can be
    obtained from your operating system's package manager, or the [[https://www.docker.com/][Docker
    website]].
  - Docker must be installed, with the =docker= executable on the path.
  - Your user must have permission to use docker, including building and running
    Docker containers.
- Git
  - Some of the tests use Git to test the end to end functionality of the
    shell. This can be obtained from your operating system's package manager, or
    the [[https://git-scm.com/][Git website]].
  - Git must be installed, with the =git= executable on the path.
- SSH
  - Some of the tests use an SSH client to test the end to end functionality of
    the shell. I have tested this with OpenSSH, which can be obtained from your
    operating system's package manager, or the [[https://git-scm.com/][Git website]].
  - with the =ssh= executable on the path.
    
If you're running Arch Linux, these are the steps you'll need to get your
environment ready.

#+begin_src sh
  sudo pacman -S rustup docker git openssh gcc

  # Rust
  rustup default stable

  # Docker
  sudo usermod -a -G docker $USER
  sudo systemctl start docker.service

  # Note: you need to log out and in again for the new group to take effect
#+end_src

** Running Tests

All unit tests are run with Cargo.

#+begin_src sh
  cargo test --workspace
#+end_src

** Linting

Clippy should be used for linting. This can be installed using Rustup.

#+begin_src sh
  rustup component add clippy
#+end_src

And it can be run via Cargo.

#+begin_src sh
  cargo clippy
#+end_src

** Building a Release Binary

Release binaries should be built in release mode.

#+begin_src sh
  cargo build --release
#+end_src

After running this, the binary is available in =./target/release/shackle=

* Roadmap / Issue Tracker TODO list

** MVP

- [X] interactive command prompt
- [X] non-interactive commands can be run with -c
- [X] exit command
- [X] git init of private repo
- [X] responds to unknown commands
- [X] Isolation of workdir between tests
- [X] git fetch with git upload-pack
- [X] git push with git receive-pack
- [X] proper shell argument lexing, with quote stuff
- [X] history (only within same session)
- [X] don't quit interactive shell sessions if there's an error
- [X] help command
- [X] restrict repos to only acceptable paths
  - [X] clone / pull
  - [X] push
- [X] git init of shared repos
  - [X] create the shared repo in the right place
  - [X] use the right file permissions and config
  - [X] don't allow this to be a group the user isn't in
  - [X] allow pull and push from shared repos
- [X] listing of repos
- [X] set repo descriptions
  - [X] init new repo
  - [X] change an existing repo
- [X] Change ~git-init~ name to just be ~init~. Later, the ~git~ part will be an
  option which defaults to git.
- [X] set the main branch of a repo
- [X] help docs on all the commands

** Post-MVP

- [X] proper licensing
- [ ] all the getting started stuff in the readme
- [ ] clean up crates.io-friendly readme
  - It needs to be markdown, and probably not all the content of the "full" readme?
- [ ] consider having the workspace root abstract so that --workspace isn't needed
- [ ] publish to crates.io
- [ ] project website
- [ ] functions correctly when the git path isn't created yet
- [ ] git archive with git upload-archive
- [ ] git config management around protected branches
- [ ] move a repo to a different group
- [ ] housekeeping git tasks (git fsck, git gc)
- [ ] pijul fetch and pijul push
- [ ] pijul support on other commands

* License

Licensed under [[./LICENSE][MIT License]].