ftrucli

ftrucli is a Food Truck CLI used to find food trucks near a geospatial coordinate (especially in San Francisco).

• ftrucli
  • MVP Meta
    • Foundational Intent
    • MVP Design Intent
    • Out of Scope for MVP
    • Initial Design Description
  • CLI Instructions
    • Installation
    • Usage
      • Help Dump
      • Usage Examples
  • Development
    • Build Toolchain Setup
      • Install node14, using nvm
      • Install pnpm and heft
    • Install Dependencies
    • Build
    • Test
    • Linting
  • CI/CD
    • Continuous Integration
    • Continuous Deployment
  • Publishing
    • Versioning
    • npm Publishing
    • Release Branching
  • Decision Log

MVP Meta

This section describes the author's intent while building the minimum viable product (MVP) for ftrucli.

Foundational Intent

Above and beyond all else, the intent of this project is to...

• Demonstrate author's values
• Showcase author's problem solving process
• Curate collaboration environment (provide ideal open-source dev experience)
• Cut a release ~3 hours after init commit

MVP Design Intent

The following areas of focus drove the design of the ftrucli MVP...

• Implement bare minimum feature set (serve at least five (5) food trucks, given a coordinate pair)
• Prioritize production readiness by focusing on...
  • Organization
  • Design
  • Testing
  • Deployment
  • Documentation
• Design for extensibility

Out of Scope for MVP

Out of scope features for the MVP...

• --open-now - filter for open food trucks
• data caching - all queries will be against the SF SODA endpoint
• search by street address, using the Bing Maps API
• using an app token (and storing it in a .env file or Azure Key Vault)

Initial Design Description

The CLI will follow the basic flow of the following diagram...

)

The Output class uses a factory to provide transparent extensibility for the Action component (to output results in either a prettified table or raw format).

CLI Instructions

Installation

Install the CLI globally from npm.

npm install --global ftrucli

Usage

This section contains the CLI help messages and some examples.

Help Dump

General help dump...

$ ftrucli --help
usage: ftrucli [-h] [-v] <command> ...

Food Truck CLI used to find food trucks near a geospatial coordinate
(especially in San Francisco).

Positional arguments:
  <command>
    coord        Finds food trucks within a specified distance from a
                 coordinate pair.

Optional arguments:
  -h, --help     Show this help message and exit.
  -v, --verbose  Print out all the debug!

For detailed help about a specific command, use: ftrucli <command> -h

coord command help dump...

$ ftrucli coord --help
usage: ftrucli coord [-h] --long LONGITUDE --lat LATITUDE [-n LIMIT]
                     [-d DISTANCE] [-o {prettyJson,raw,table}]


Finds food trucks within a specified distance from a coordinate pair. Filters
exist for limiting the number of food trucks which are displayed.

Optional arguments:
  -h, --help            Show this help message and exit.
  --long LONGITUDE      A user's longitude.
  --lat LATITUDE        A user's latitude.
  -n LIMIT, --limit LIMIT
                        Limits the number of responses returned from a SODA
                        query. The default value is 6.
  -d DISTANCE, --distance DISTANCE
                        The distance (in meters) to search outwards from a
                        coordinate point. The default value is 5000.
  -o {prettyJson,raw,table}, --output {prettyJson,raw,table}
                        Determines how the results are displayed. The default
                        value is "table".

Usage Examples

# Set long/lat, use default distance and limit
ftrucli coord --lat 37.80 --long -122.43

# Specify distance
ftrucli coord --lat 37.80 --long -122.43 --distance 1000

# Specify limit
ftrucli coord --lat 37.80 --long -122.43 --distance 2500 --limit 9

# Use different output format
ftrucli coord --lat 37.80 --long -122.43 --output raw

Development

Build Toolchain Setup

This section describes how to set up the project's build toolchain. node14 (managed by nvm), pnpm, and heft are the critical tools which enable our build process. ftrucli uses build tools from the Rush Stack toolset family.

Install node14, using nvm

# Install nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.37.2/install.sh | bash
source ~/.bashrc

# Install node14
nvm install 14
nvm use 14

Install pnpm and heft

npm install --global pnpm
pnpm install --global @rushstack/heft

NOTE: Since this project uses pnpm, please use it to install new packages (instead of npm). This helps maintain the pnpm-lock.yaml file.

Install Dependencies

Use pnpm to install all project dependencies.

pnpm i

Build

This project uses heft as a build coordinator.

heft build

Test

This project uses heft as a test orchestrator (jest under the covers).

heft test

Linting

This project uses eslint for linting. (TSLint is now deprecated.)

We recommend using this eslint VS Code extension.

CI/CD

This section details this project's CI and CD practices.

Continuous Integration

Continuous integration is performed on TravisCI, as defined by .travis.yml. Heft is installed, used to build the project, then used to test the project.

Continuous Deployment

Continuous deployment is out of scope, but on the roadmap.

The plan is to use GitHub actions to "watch" branches of the pattern release/*, create GitHub releases, and publish said releases to the ftrucli package repository.

Publishing

ftrucli is published on npm. This section describes best practices surrounding publishing ftrucli to its npm repository.

Versioning

Semantic versioning via using npm is standard procedure.

npm version <major|minor|patch>

npm Publishing

Use npm to publish the package at the current version.

npm publish

Please create a release branch following each successful publish.

Release Branching

Release flow dictates we create a release/* branch, off of main, after each release. This is done by checking out a new branch after npm publish to "snapshot" the release version using the release/* naming convention. The wildcard, *, represents a monotonically increasing sequence of non-negative integers that is incremented on each publish.

Hotfixes are implemented in a hotfix branch and then pulled into both the current release branch and main, via PR. Old releases are treated as discardable, thus not patched.

Decision Log

| Decision | Brief Description | | -------------------------------------------------------------------------- | ------------------------------------------------------- | | Rushstack used as project tool chain | Rushstack provides us with build and CLI tools. | | TravisCI used for CI | TravisCI is this project's continuous integration tool. |