CoolCiv

This repository contains the web-based CoolCiv project, which implements a HotCiv spin-off from Flexible, Reliable Software by Henrik Bærbak Christensen.

Caution

All commands in this README document are to be executed from the project root directory (where this document resides).

Table of Contents

Get Started
Tasks

Get Started

This project uses the zero-install feature of the Yarn package manager. Upon cloning the Git repository, the .yarn/cache directory already contains a cache of the third-party dependencies, effectively replacing the usual node_modules directory.

Install Node.js and Yarn

macOS and Linux users should install Node.js via Node Version Manager and opt for Yarn via Corepack:

$ curl https://raw.githubusercontent.com/nvm-sh/nvm/master/install.sh | bash
$ source ~/.bashrc
$ nvm install --lts
$ corepack enable yarn
$ yarn run setup

Windows users should install Node.js via Windows Package Manager and install Yarn via npm (which is actually a workaround until Corepack supports Windows):
```
$ winget install OpenJS.NodeJS.LTS
$ npm install --global yarn
$ yarn run setup
```

Prepare Git

Generate an SSH key with the Ed25519 algorithm, for example using ssh-keygen or 1Password, and add it to the SSH agent on your computer. If you already have an SSH key on your computer, you may skip this step.
```
$ ssh-keygen -t ed25519 -f "$HOME/.ssh/<my-ssh-key>"
$ ssh-add ~/.ssh/<my-ssh-key>
```
- Windows users must instruct Git to use Microsoft OpenSSH as the SSH agent:
  $ git config --global core.sshCommand "C:/Windows/System32/OpenSSH/ssh.exe"
Grab the public key. It appears like ssh-ed25519 AAAAC3(…).
```
$ cat ~/.ssh/<my-ssh-key>.pub
```
Register the public key in GitHub as a signing key.
Obtain your masked email address in GitHub. It appears like <id+username>@users.noreply.github.com.

Declare your identity within the scope of this repository and use the public key to sign your commits:

$ git config user.name "<FirstName> <LastName>"
$ git config user.email "<id+username>@users.noreply.github.com"

$ git config user.signingkey "ssh-ed25519 AAAAC3<PublicKey>"
$ git config gpg.format "ssh"
$ git config commit.gpgsign "true"
$ git config tag.gpgsign "true"

Prepare Your IDE

IntelliJ IDEA (and WebStorm) users should open the project directory:
```
$ idea .
```
1. Install these plugins (follow the popup message, or go to File › Settings › Plugins):
  - AsciiDoc
  - Prettier
2. Go to File › Settings › Languages & Frameworks › Node.js. Select the appropriate Node.js interpreter and enable coding assistance.
Visual Studio Code users should open the project directory:
```
$ code .
```
1. Install these extensions (Ctrl+Shift+X and search for @recommended):
  - AsciiDoc
  - ESLint
  - Prettier
  - ZipFS (required by the Yarn SDK)

Tasks

The scripts field in package.json defines a set of work tasks. Corresponding configurations for IntelliJ IDEA and Visual Studio Code are located in .idea/runConfigurations and .vscode/tasks.json, respectively.

Start a Local Development Server

$ yarn run start.development

Visit http://localhost:8000 to access the web app from your local computer. Use the LAN IP address printed in the console to access it from another device.

Validate the Software Quality

$ yarn run validate

It runs the following means of validation:

Type checking via TypeScript (validate.types).
Static program analysis (linting) via ESLint (validate.lint).
- validate.lint.fix fixes certain issues automatically.
Source code formatting via Prettier (validate.format).
- validate.format.fix reformats the source code files accordingly.
Automated unit testing via Vitest (validate.test).
- validate.test.coverage creates a code coverage report in the coverage directory.
- validate.test.ui launches the Vitest user interface in a web browser.
- validate.test.watch makes the test suite run continuously.

Run validate.fix to automatically fix as much as possible.

Build for Production

$ yarn run build

It saves the output in the build directory.

Run start.production to serve a preview at http://localhost:80.

spdiswal/coolciv