V0.7 competitive similarity

.gitignore

@@ -1,7 +1,8 @@
 node_modules/
 .DS_Store
 *.py
-test.js
+test*.*
 companies.json
 *.pdf
-sample_pdf/
+sample_pdf/
+foo*.*

README.md

@@ -1,13 +1,15 @@
 ## Welcome to Open Source Mediumroast for GitHub.
 Products organizations must build robust product plans from competitive and customer interactions everyone can see, use, and reference. Therefore, Mediumroast for GitHub intends to help Products oranizations construct an active interactions repository close to the action of development and issue management in GitHub.
 
-**Notice:** You can review the [GitHub Page Version](https://mediumroast.github.io/mediumroast_js/) rather than the repository version of this documentation, but the screencasts of several of the CLI tutorials will not display. 
+### Notices 
+- A new version of the CLI is available and documentation is in progress.  The major focus of this version is to add in Competitive Similarity Analysis, Interaction summarization and Interaction Proto-requirements discovery. 
+- You can review the [GitHub Page Version](https://mediumroast.github.io/mediumroast_js/) rather than the repository version of this documentation, but the screencasts of several of the CLI tutorials will not display. 
 
 ## Installation and configuration
 Mediumroast for GitHub includes a [GitHub Application](https://github.com/apps/mediumroast-for-github), a Command Line Interface, and a Software Development Kit.  The following steps show you how to install the App and the CLI with SDK.
 
 ### Preinstallation requirements
-1. A GitHub organization, please 
+1. A GitHub organization
 2. Permissions in your GitHub organization to install a GitHub application.
 3. Access to a command line terminal on Linux or MacOS.
 4. [Node.js installed](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm#using-a-node-installer-to-install-nodejs-and-npm), ideally globally for all users.
@@ -36,7 +38,7 @@ Coming soon.
 Before you can use the Mediumroast for GitHub [CLI](https://github.com/mediumroast/mediumroast_js/blob/main/cli/README.md) the environment must be setup.  With the CLI installed please run `mrcli setup` to start the setup process, note there's a video of the setup process in CLI README.
 
 ## What's provided
-Running `mrcli setup` creates a repository in your oganization called `<organization_name>_discovery` for all interactions and objects, creates two intitial companies, and installs two GitHub Actions to control the number of branches and provide some basic out of the box reporting -- see example screenshot below.
+Running `mrcli setup` creates a repository in your oganization called `<organization_name>_discovery` to contain all interactions and companies, creates two intitial companies, and installs two GitHub Actions to control the number of branches and provide some basic out of the box reporting -- see example screenshot below.
 
 ### Warning
 Since Mediumroast for GitHub creates a regular repository you can interact with it as normal, but **doing so is not recommended**. If you interact with the repository, in regular ways, this could result in Mediumroast for GitHub becoming inoperable.  There are cases where it may become necessary to directly work with the repository, but that should be rare.

cli/Company.md

@@ -1,5 +1,5 @@
 ## Companies
-Company objects are central to Mediumroast for GitHub. Interaction sand in the future Studies rely on Companies to function. After setup is run, via `mrcli setup`, two companies are present to work with.  Additional Companies can be added, updated, or removed; essentially, `company` is an `mrcli` sub-command that affords users Create, Read, Update and Delete capabilities.  Each of the major functions for `mrcli company` are described in this document.
+Company objects are central to Mediumroast for GitHub. Interactions and in the future Studies rely on Companies to function. After setup is run, via `mrcli setup`, two companies are present to work with.  Additional Companies can be added, updated, or removed; essentially, `company` is an `mrcli` sub-command that affords users Create, Read, Update and Delete capabilities.  Each of the major functions for `mrcli company` are described in this document.
 
 ### Notice
 Some of the command line options and switches may not yet be implemented; therefore, if a switch or option is not yet implemented the CLI will inform the user and then exit.
@@ -100,6 +100,17 @@ A command line prompt based wizard steps the user through either a semi-automate
 
 <img width="1178" alt="companies_add" src="https://github.com/mediumroast/mediumroast_js/assets/10818650/d948fce2-6c31-4537-983d-9dad4c04c248">
 
+## Report on a company
+Produce a MS Word document report on a company.  The report includes a dashboard with a company similarity report, company firmographics, detail on similar companies, and summaries for all interactions associated to the company reported on.  The report is stored in the `$HOME/Documents` directory as `<company_name>.docx`.
 
+Optionally, if the `--package` switch is used the report is zipped and stored in the $HOME/Documents directory as `<company_name>.zip` including all of the interactions associated to the company and the set of most and least similar companies. 
+
+### Command(s) run
+- `mrcli c --report="Atlassian Corp"`
+- `mrcli c --report="Atlassian Corp" --package`
+
+### Screenshot of the report dashboard
+
+![Screenshot 2024-09-03 at 8 23 29 AM](https://github.com/user-attachments/assets/bd1141cc-53c6-4cac-8e56-ed50601dcbb6)
 
 

cli/Interaction.md

@@ -110,8 +110,17 @@ A command line prompt based wizard steps the user through a semi-automated proce
 
 https://github.com/mediumroast/mediumroast_js/assets/10818650/0b28db90-d6ba-4224-a9ae-4c301c2b9614
 
+## Report on an interaction
+Produce a MS Word document report on an interaction.  The report includes a dashboard with interaction metadata, interaction abstract, and proto-requirements.  The report is stored in the `$HOME/Documents` directory as `<interaction_name>.docx`.
 
+Optionally, if the `--package` switch is used the report is zipped and stored in the $`HOME/Documents` directory as `<interaction_name>.zip` including the interaction content. 
 
+### Command(s) run
+- `mrcli i --report="Atlassian Corp"`
+- `mrcli i --report="Atlassian Corp" --package`
+
+### Screenshot of the report dashboard
+![Screenshot 2024-09-04 at 8 30 25 PM](https://github.com/user-attachments/assets/19c614a5-ed58-4687-aff8-a619ea693398)
 
 
 

cli/README.md

@@ -1,9 +1,44 @@
 # Mediumroast for GitHub CLI (Command Line Interface)
 The CLI is divided into two sets one for administrative interactions with the system and another for interacting with **Mediumroast for GitHub** objects like Companies and Interactions.  This document covers both the administrative CLI and makes reference to the CLI set for **Mediumroast for GitHub** objects.
 
+# Authentication
+**Mediumroast for GitHub** uses either Device Flow or a Personal Access Token for authentication.  The setup CLI will prompt you to choose the type of authentication and then store the necessary information in the `${HOME}/.mediumroast/config.ini` file.  If you need to change the authentication configuration you can run `mrcli setup` to reset the configuration file.
+
+## Required permissions for the Personal Access Token (PAT)
+If you create a PAT before the **Mediumroast for GitHub** repository exists the required scope is for **all repositories** in your organization. At PAT renewal or if you want to reduce the scope to only the **Mediumroast for GitHub** repository this can be done later. The Personal Access Token must have the following permissions on all repositories to perform the necessary actions including setup.
+
+- `Actions`: read/write
+- `Administration`: read/write
+- `Contents`: read/write
+- `Metadata`: read
+- `Pull requests`: read/write
+- `Workflows`: read/write
+
+For background and directions on creating a PAT see the [GitHub documentation](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens).
+
+
 # Administrative CLIs
 To enable setup and operational reporting of **Mediumroast for GitHub** several CLIs are available, each is described below.
 
+## Storage reporting
+Reports storage consumed by **Mediumroast for GitHub**. A screenshot showing the usage information and outputs for major functions is included below.
+### Command(s) run
+- `mrcli t`
+- `mrcli storage`
+
+### Screenshot with ouput
+![Screenshot 2024-09-04 at 8 23 17 PM](https://github.com/user-attachments/assets/dba9738f-e093-4415-9ec7-1031f66cf6d1)
+
+## Actions
+Reports actions minutes consumed by **Mediumroast for GitHub** and enables a user to update their repository as new versions of actions are released. A screenshot showing the usage information and outputs for major functions is included below.
+### Command(s) run
+- `mrcli actions`
+- `mrcli a --update`
+
+### Screenshot with ouput
+![Screenshot 2024-09-04 at 8 23 55 PM](https://github.com/user-attachments/assets/d9ea51fc-7609-4abb-9cbe-6e010baacb50)
+
+
 ## User reporting
 Reports on all users who can access the repository that contains the **Mediumroast for GitHub**. A screenshot showing the usage information and outputs for major functions is included below, and notice, user names and other personally identifiable information has been redacted from the screenshot below.
 ### Command(s) run
@@ -12,15 +47,6 @@ Reports on all users who can access the repository that contains the **Mediumroa
 ### Screenshot with ouput 
 <img width="1178" alt="users_util" src="https://github.com/mediumroast/mediumroast_js/assets/10818650/994787aa-ec26-4cb0-99a1-b670b9d929ff">
 
-## Billing reporting
-Provides reports for consumed actions and repository storage consumed by the organization that has installed and is using **Mediumroast for GitHub**. A screenshot showing the usage information and outputs for major functions is included below.
-### Command(s) run
-- `mrcli b`
-- `mrcli b --storage`
-- `mrcli b --actions`
-### Screenshot with ouput    
-<img width="1178" alt="billings_util" src="https://github.com/mediumroast/mediumroast_js/assets/10818650/4a715d07-b168-41ce-9054-33bf70af8086">
-
 ## Setup
 To help users quickly get on board with **Mediumroast for GitHub** the setup CLI is used.  This CLI creates the `${HOME}/.mediumroast/config.ini` file, creates the repository including key directories, and creates two initial companies.  A screencast video showing the process for setting up the CLI environment and creating two companies is available below.
 
@@ -31,6 +57,18 @@ To help users quickly get on board with **Mediumroast for GitHub** the setup CLI
 
 https://github.com/mediumroast/mediumroast_js/assets/10818650/68c08502-4f59-4981-a001-0d9c9bd1d4d2
 
+# Deprecated commands
+The following commands are deprecated, are disabled and will be removed in a future release of the CLI.
+
+## Billing reporting
+Is replaced by `storage` and `actions` commands in **Mediumroast for GitHub**. If you run this command it will immediately exit stating it is no longer supported.
+
+### Command(s) run
+- `mrcli b`
+- `mrcli billing`
+
+
+
 ---
 
 [[Company Subcommand](https://github.com/mediumroast/mediumroast_js/blob/main/cli/Company.md)] | [[Interaction Subcommand](https://github.com/mediumroast/mediumroast_js/blob/main/cli/Interaction.md)]

cli/actions/actions/basic-reporting/companies.js

@@ -0,0 +1,67 @@
+const mrMarkdownBuilder = require('mr_markdown_builder')
+
+// Globals
+const MAPS_WARNING = `**Notice:** If you are using Safari and had previously disabled \`Prevent cross-site tracking\` feature in the \`Privacy tab\` in Safari's preferences, you can now reenable it since this bug has been fixed by GitHub.${mrMarkdownBuilder.cr()}${mrMarkdownBuilder.cr()}`
+
+function createCompaniesMap (companies) {
+    // Filter out companies with unknown latitude or longitude
+    companies = companies.filter((company) => company.latitude !== 'Unknown' && company.longitude !== 'Unknown')
+    // Create the map
+    let map = mrMarkdownBuilder.h1('Company Locations')
+    map += MAPS_WARNING
+    map += mrMarkdownBuilder.geojson({
+        type: 'FeatureCollection',
+        features: companies.map((company) => {
+            return {
+                type: 'Feature',
+                geometry: {
+                    type: 'Point',
+                    coordinates: [company.longitude, company.latitude]
+                },
+                properties: {
+                    name: company.name,
+                    description: company.description,
+                    role: company.role,
+                    url: company.url
+                }
+            }
+        })
+    })
+    // return the map
+    return mrMarkdownBuilder.cr() + map
+}
+
+function createCompaniesReport (companies) {
+    let readme = `[${mrMarkdownBuilder.link('Back to main README', '../README.md')}]\n`
+    readme += mrMarkdownBuilder.hr()
+    readme += mrMarkdownBuilder.h1('Introduction')
+    readme += `There are currently \`${companies.length}\` companies in the repository. The table below lists all available companies and some of their firmographics. Click on the company name to view the company's profile.  Below the table is a map of all companies in the repository.  Click on a company's marker to view additional company information in context.`
+    readme += mrMarkdownBuilder.h1('Table of Companies')
+    // Create the table header
+    const tableHeader = mrMarkdownBuilder.tableHeader(['Company Name', 'Company Type', 'Company Role', 'Company Region'])
+    // Create the table rows
+    const tableRows = companies.map((company) => {
+        const companyRow = [
+            mrMarkdownBuilder.link(company.name, `./${encodeURI(company.name.replace(/[\s,.\?!]/g, ''))}.md`),
+            company.company_type,
+            company.role,
+            company.region
+        ]
+        return companyRow
+    })
+    // Create the table
+    const companyTable = tableHeader + "\n" + mrMarkdownBuilder.tableRows(tableRows)
+    // Create the README.md file
+    readme += companyTable
+    // Add a line break
+    readme += mrMarkdownBuilder.cr() + mrMarkdownBuilder.hr()
+    // Call the createMap function
+    readme += mrMarkdownBuilder.cr() + createCompaniesMap(companies)
+    // Return the file content
+    return readme
+
+}
+
+module.exports = {
+    createCompaniesReport
+}