feat: Jira app (#1)

.env-example

@@ -0,0 +1,3 @@
+# copy to .env and complete values
+FORGE_EMAIL="email-address-here"
+FORGE_API_TOKEN="token-here"

.gitignore

@@ -0,0 +1,5 @@
+/node_modules/
+/dist/
+/.vscode/
+.idea
+.env

.npmrc

@@ -0,0 +1,2 @@
+engine-strict=true
+save-exact=true

.nvmrc

@@ -0,0 +1 @@
+v20.9.0

.tool-versions

@@ -0,0 +1 @@
+nodejs 20.9.0

README.md

@@ -1 +1,67 @@
-# flagsmith-jira-integration
+# Flagsmith Jira Integration
+
+This repository contains an outer folder to install and configure the Forge CLI with an inner folder containing the Jira app itself.
+
+See [developer.atlassian.com/platform/forge](https://developer.atlassian.com/platform/forge) for documentation and tutorials explaining Forge.
+
+## Architectural Decisions
+
+See [docs/decisions/README.md](docs/decisions/README.md) for decision records.
+
+## Forge CLI installation
+
+The following steps reflect the usual [Getting started](https://developer.atlassian.com/platform/forge/getting-started/) instructions but diverge for reproducability and portability reasons.
+
+### Before you begin
+
+Forge CLI requires [Docker](https://docs.docker.com/get-docker/) and Node.js 20 (LTS) to be installed:
+
+- [Apple macOS](https://developer.atlassian.com/platform/forge/installing-forge-on-macos)
+- [Linux](https://developer.atlassian.com/platform/forge/installing-forge-on-linux)
+
+Forge recommend installing Node using using [nvm](https://github.com/nvm-sh/nvm#installing-and-updating) but [asdf](https://asdf-vm.com/) also works.
+Ensure you are using the correct Node.js version before executing any other commands:
+
+    nvm use
+
+### Install the Forge CLI
+
+Forge instructions start by [installing the CLI globally](https://developer.atlassian.com/platform/forge/getting-started/#install-the-forge-cli) but instead we will use a local installation with pinned requirements:
+
+    npm ci
+
+The Forge CLI is then available by typing `npx forge`.
+
+### Log in with an Atlassian API token
+
+Create an Atlassian API token to log in to the CLI. The CLI uses your token when running commands.
+
+1. Go to <https://id.atlassian.com/manage/api-tokens>.
+1. Click Create API token.
+1. Enter a label to describe your API token. For example, forge-api-token.
+1. Click Create.
+1. Click Copy to clipboard and close the dialog.
+
+The `forge login` command attempts to store credentials in your operating system keychain and may not work on all platforms. Instead, we can skip this command and set environment variables instead.
+
+### Using environment variables to login
+
+Copy `.env-example` to `.env` and complete your Atlassian account email address and API token.
+
+If you use [direnv](https://direnv.net/) these values should be picked up automatically. Alternatively use the activate script:
+
+    source <(./bin/activate)
+
+This reads `.env` values into your shell environment and also sets an alias so you can execute Forge CLI commands by typing `forge` without needing an `npx` prefix or to or mess with your path variable.
+
+Check installation and authentication by typing e.g.:
+
+    forge whoami
+
+## Flagsmith Jira app deployment
+
+First change into the app folder:
+
+    cd flagsmith-jira-app
+
+See [flagsmith-jira-app/README.md](flagsmith-jira-app/README.md).

bin/activate

@@ -0,0 +1,3 @@
+#!/bin/sh
+npx dotenv-export
+echo 'alias forge="npx forge"'

docs/decisions/0001-use-atlassian-forge.md

@@ -0,0 +1,37 @@
+# Use Atlassian Forge
+
+* Status: Accepted
+
+## Context and Problem Statement
+
+Need to choose a development platform which allows UI modules to be added to Jira and to be distributed as an app in the Atlassian Marketplace.
+
+## Decision Drivers
+
+* Overall requirement to quickly tick the box that Flagsmith has a Jira integration and offer MVP functionality which can be iterated on later.
+
+## Considered Options
+
+* Atlassian Forge (newer mechanism, app hosted by Atlassian)
+* Atlassian Connect (older mechanism, iframe only, app hosted by Flagsmith)
+
+## Decision Outcome
+
+Chosen option: "Atlassian Forge", because it allows for faster development of an app that meets requirements with capacity to scale to meet future requirements.
+
+### Positive Consequences
+
+* Use of recommended platform with roadmap
+* Built-in authentication, sandboxing, and hosting environments
+* Built-in console to manage, distribute, and monitor apps
+* CLI tooling for testing, deployment and installation
+* Allows for Connect-style iframe apps if required
+
+### Negative Consequences
+
+* Limited to JavaScript/TypeScript but that is the UI stack we use anyway
+* Less control over (but less responsibility for) hosting as it is provided by Atlassian
+
+## Links
+
+* https://developer.atlassian.com/developer-guide/cloud-development-options/

docs/decisions/0002-use-current-forge-runtime.md

@@ -0,0 +1,37 @@
+# Use Current Forge Runtime
+
+* Status: Accepted
+
+## Context and Problem Statement
+
+Need to choose a JavaScript runtime that executes the app code and provides libraries for Jira and Flagsmith REST API calls, storage, authorisation, etc.
+
+## Decision Drivers
+
+* Overall requirement to quickly tick the box that Flagsmith has a Jira integration and offer MVP functionality which can be iterated on later.
+
+## Considered Options
+
+* Current runtime (limited Node.js 14, generally available)
+* Native runtime (full Node.js 18, in preview)
+
+## Decision Outcome
+
+Chosen option: "Current runtime", while avoiding falling into any of the breaking changes between the runtimes, i.e. use latest Forge libraries, set Content-Type on API calls, don't rely on snapshotting. This allows for faster, more reliable, development without ruling out a future change of runtime.
+
+### Positive Consequences
+
+* Stability as preview releases are subject to change
+* Reliable tunnelling as local environment is same as deployment environment
+* Ability to use runtime features (e.g. debugging) not yet available in new runtime
+* Avoids confusion between Forge CLI Node.js (20) and Runtime Node.js (18)
+* Minimal obstacles to migrate to the new runtime later
+
+### Negative Consequences
+
+* Potentially slower but should be fast enough, if not we can re-evaluate this decision
+* Less Node features in the older runtime but we don't need them now
+
+## Links
+
+* https://developer.atlassian.com/platform/forge/runtime-reference/native-nodejs-runtime/

docs/decisions/0003-use-ui-kit.md

@@ -0,0 +1,40 @@
+# Use UI Kit
+
+* Status: Accepted
+
+## Context and Problem Statement
+
+Need to choose a JavaScript library for UI components (text, tables, inputs, buttons, etc) and Jira UI (app settings, project settings, issue panel, menus, modals, etc).
+
+## Decision Drivers
+
+* Overall requirement to quickly tick the box that Flagsmith has a Jira integration and offer MVP functionality which can be iterated on later.
+
+## Considered Options
+
+* UI Kit (original Jira UI component library)
+* UI Kit 2 (updated library, under development, in preview)
+* Custom UI (provide own UI components, use bridge to Jira components)
+
+## Decision Outcome
+
+Chosen option: "UI Kit", because it offers the simplest route to developing an MVP UI without ruling out more complex UI in future. Keep UI and business logic code separate and avoid using withdrawn UI Kit features to minimise barriers to transition.
+
+### Positive Consequences
+
+* Stability as preview releases are subject to change
+* Reduced complexity as UI Kit 2 requires new native runtime and splits execution between frontend and backend
+* Reduced effort as UI Kit provides pre-built UI components styled to fit with Jira
+* Greater compatibility as UI Kit is expected to work well with Jira styling features such as dark mode
+* Minimal obstacles to migrate to UI Kit 2 later
+
+### Negative Consequences
+
+* Less control over UI, but assuming it looks no worse than competing integrations, that should meet requirements, if not we can re-evaluate this decision
+
+## Links
+
+* https://developer.atlassian.com/platform/forge/ui-kit-components/
+* https://developer.atlassian.com/platform/forge/ui-kit-2/
+* https://developer.atlassian.com/platform/forge/custom-ui/iframe/
+* https://trello.com/b/z2GIJ3xD/forge-roadmap-for-developers

docs/decisions/README.md

@@ -0,0 +1,9 @@
+# Decisions
+
+This directory contains decision records for the Flagsmith for Jira app.
+
+For new ADRs, please use [adr-template.md](adr-template.md) as basis.
+More information on MADR is available at <https://adr.github.io/madr/>.
+General information about architectural decision records is available at <https://adr.github.io/>.
+
+Built using <https://marketplace.visualstudio.com/items?itemName=StevenChen.vscode-adr-manager>

docs/decisions/adr-template.md

@@ -0,0 +1,76 @@
+# {short title of solved problem and solution}
+
+## Context and Problem Statement
+
+{Describe the context and problem statement, e.g., in free form using two to three sentences or in the form of an illustrative story.
+ You may want to articulate the problem in form of a question and add links to collaboration boards or issue management systems.}
+
+<!-- This is an optional element. Feel free to remove. -->
+## Decision Drivers
+
+* {decision driver 1, e.g., a force, facing concern, …}
+* {decision driver 2, e.g., a force, facing concern, …}
+* … <!-- numbers of drivers can vary -->
+
+## Considered Options
+
+* {title of option 1}
+* {title of option 2}
+* {title of option 3}
+* … <!-- numbers of options can vary -->
+
+## Decision Outcome
+
+Chosen option: "{title of option 1}", because
+{justification. e.g., only option, which meets k.o. criterion decision driver | which resolves force {force} | … | comes out best (see below)}.
+
+<!-- This is an optional element. Feel free to remove. -->
+### Positive Consequences
+
+* {e.g., improvement of one or more desired qualities, …}
+* …
+
+<!-- This is an optional element. Feel free to remove. -->
+### Negative Consequences
+
+* {e.g., compromising one or more desired qualities, …}
+* …
+
+<!-- This is an optional element. Feel free to remove. -->
+## Validation
+
+{describe how the implementation of/compliance with the ADR is validated. E.g., by a review or an ArchUnit test}
+
+<!-- This is an optional element. Feel free to remove. -->
+## Pros and Cons of the Options
+
+### {title of option 1}
+
+<!-- This is an optional element. Feel free to remove. -->
+{example | description | pointer to more information | …}
+
+* Good, because {argument a}
+* Good, because {argument b}
+<!-- use "neutral" if the given argument weights neither for good nor bad -->
+* Neutral, because {argument c}
+* Bad, because {argument d}
+* … <!-- numbers of pros and cons can vary -->
+
+### {title of other option}
+
+{example | description | pointer to more information | …}
+
+* Good, because {argument a}
+* Good, because {argument b}
+* Neutral, because {argument c}
+* Bad, because {argument d}
+* …
+
+<!-- This is an optional element. Feel free to remove. -->
+## More Information
+
+{You might want to provide additional evidence/confidence for the decision outcome here and/or
+ document the team agreement on the decision and/or
+ define when this decision when and how the decision should be realized and if/when it should be re-visited and/or
+ how the decision is validated.
+ Links to other decisions and resources might here appear as well.}

flagsmith-jira-app/.eslintrc

@@ -0,0 +1,29 @@
+{
+  "parserOptions": {
+    "sourceType": "module",
+    "ecmaVersion": 2017,
+    "ecmaFeatures": {
+      "jsx": true
+    }
+  },
+  "plugins": ["react-hooks"],
+  "extends": [
+    "eslint:recommended",
+    "plugin:react/recommended",
+    "plugin:react/jsx-runtime",
+    "plugin:@typescript-eslint/recommended",
+    "plugin:prettier/recommended"
+  ],
+  "rules": {
+    "@typescript-eslint/no-explicit-any": "warn",
+    "@typescript-eslint/no-unused-vars": "warn",
+    "prettier/prettier": "warn",
+    "react-hooks/rules-of-hooks": "error",
+    "react/display-name": "off"
+  },
+  "settings": {
+    "react": {
+      "version": "17"
+    }
+  }
+}

flagsmith-jira-app/.gitignore

@@ -0,0 +1,4 @@
+/node_modules/
+/dist/
+/.vscode/
+.idea

flagsmith-jira-app/.prettierrc

@@ -0,0 +1,3 @@
+{
+    "printWidth": 100
+}