Skip to content

stevenjwest/projectmanagr

BranchesTags

Repository files navigation

projectmanagr

projectmanagr : A library for organising project documentation in R Markdown.

This package facilitates the management of project documentation in R Markdown files, including:

  • forming Project Documents,

  • creating Project Notes to meet Goals, Deliverables and Tasks in Project Documents,

  • and allowing the efficient storage and analysis of data within this structure.

It comprises several modules:

Filesystem Management

  • Filesystem Organisation & Management

    • Organisation :

      • Standardise file & filesystem layout

    • Management :

      • Form and Maintain Cross-Referenced information
      • to SUMMARISE & ORGANISE

    • For comprehensive summary of functions See :

Sample Management

  • Sample Management

    • Plain-text Datatables & Databases

      • for data logging & processing/analysis in R

Resource Management

  • Resource Management

    • Inventory Rmd Files for managing resources

    • Protocol Rmd Files for managing processes

Data Management

  • Data Management

    • Volumes Rmd File to manage external data storage

    • Data Storage Log in Project Note Rmd

Installation

You can install the development version of projectmanagr from GitHub with:

# install.packages("pak")
pak::pak("stevenjwest/projectmanagr")

Usage

The first step in using ProjectManagr is generating an Organisation - comprising an organisation root directory & index file, and containing one or more:

  • Programmes : Collections of Projects with a defined scope

  • Project Doc : Projects that consist of Goals, Deliverable, Tasks - linked to Project Notes

  • Project Notes : Documentation of work to primarily achieve Project Goals/Deliverables/Tasks

Adding Google OAuth Client: Quick overview

Projectmanagr lets you pull Today’s Google-Calendar events straight into your daily R Markdown journal, alongside extracted “TODO:” comments from your project files, for daily planning & journaling.

Because Google Calendar is private data, each user must authorise their own Google account.

The safest way is for every user to create a tiny “Desktop-app” OAuth client in Google Cloud Console, then let projectmanagr read the Client’s generated JSON file when it authenticates.

Why? What you do
Give projectmanagr read-only access to your calendars—nothing is shared with the package author; you stay in full control. 1 Create (or reset) a Desktop-app OAuth client in Google Cloud Console.
Keep secrets out of the repo—the JSON lives only on your computer, not inside the package. 2 Download the JSON; it contains a public client_id and a non-confidential client_secret that Google still requires for desktop apps.
Let projectmanagr find the file automatically every session—no hard-coding paths in scripts. 3 Drop the file into your personal config folder shown by rappdirs::user_config_dir("projectmanagr") (e.g. ~/Library/Application Support/projectmanagr/).

Once setup, the first call to extract_google_calendar_events() opens a browser for consent; a refresh-token is cached and future calls are silent.

1 Create a Desktop-app OAuth client in Google Cloud Console

step what you click why it matters
1 Navigate to https://console.cloud.google.com/ and login with your google account Google Cloud Console allows you to generate an OAuth Client App.
2 Open Console → APIs & Services → Credentials (Configure a Google API Console Project for the Google Ads API) The Credentials page lists every OAuth client you have.
3 Choose your existing Desktop-app client and click the “Reset secret” icon (two arrows) – or click ➕ Create credentials → OAuth client ID → Desktop app to make a new one (Configure a Google API Console Project for the Google Ads API) Resetting generates a fresh client_secret; creating a new client gives you a clean ID/secret pair.
4 In the dialog that appears, click Download JSON ([OAuth Desktop and Web Application Flows Google Ads API](https://developers.google.com/google-ads/api/docs/client-libs/java/oauth-web))
5 Optional: under OAuth consent screen make sure Publishing status = In production so any Google account can authorise your app (Configure the OAuth consent screen and choose scopes) Prevents “This app is in testing” warnings for your users.

Creating your Google Calendar OAuth client (step-by-step)

First you need to generate a fresh Desktop-app OAuth credential that projectmanagr will use to read your calendar.

What you’ll end up with
a file named gcal_oauth_client.json containing a client_id + client_secret.
Place it in the folder shown by
rappdirs::user_config_dir("projectmanagr")
and projectmanagr will pick it up automatically.

Sign in and create (or select) a Cloud project

  1. Open https://console.cloud.google.com/ and sign in with the Google account whose calendars you’ll read.

  2. At the very top, click the project drop-down ▾ → “New project”. Give it any name (e.g. projectmanagr-calendar) and click Create.
    Why? Every OAuth credential lives inside a Cloud project.

Enable the Google Calendar API

  1. In the left sidebar choose APIs & Services ▸ Library. In the search box type Google Calendar API → click the tile → Enable.
    Why? You must turn on the actual Calendar service before an OAuth token can call it.

Configure the OAuth consent screen (one-time)

  1. Still under APIs & Services, click OAuth consent screen.
    • Select Get started
    • Fill : App name (e.g. ProjectManagr GCal Project), User-support [your] email → Next
    • Audience : External → Next
    • Contact Information : Developer [your] email → Next
    • Select : I agree to the Google API services user data policy. → Continue → Create Why? Creating an initial OAuth Client App in testing mode is sufficient for accessing your own calendar

Create the Desktop-app OAuth Client

  1. Go to APIs & Services ▸ Credentials.

    • Click + Create credentials ▸ OAuth client ID
    • Choose Application type → Desktop app.
    • Give it a name (ProjectMaangr GCal Client), click Create.
      Why? Desktop-app clients are what R uses; they are allowed to bundle a public secret.

  2. In the popup dialog that appears click Download JSON and save the file. Why? This JSON contains the OAuth client metadata required by projectmanagr - including: client_id, client_secret, token & auth endpoints, redirect URI list.

  3. Rename the downloaded JSON file as: gcal_oauth_client.json Why? ProjectManagr expects to find the OAuth Client credentials in a file with this name.

Add Test User to OAuth Client

  1. In the left sidebar choose APIs & Services ▸ Credentials. Under OAuth 2.0 Client IDs select the OAuth Client name link (ProjectMaangr GCal Client) In the left sidebar, select Audience Under Test Users → click the button → Add users.
    Add your email → Save.
    Why? As the App is under Testing it can only be accessed by developer- approved testers, so authentication is only possible to emails added to Test users.

2 Store the JSON in the user config folder

# to show the exact directory on this machine, execute this function:
rappdirs::user_config_dir("projectmanagr")

Typically the config directory is in these location on:

  • macOS ~/Library/Application Support/projectmanagr/
    • to see the ~/Library directory you will need to view hidden files in Finder
    • Press CMD + SHIFT + . in Finder window to show/hid hideen files.
  • Windows %APPDATA%\\projectmanagr\\
  • Linux ~/.config/projectmanagr/
  1. Create that folder if it doesn’t exist.
  2. Move the file gcal_oauth_client.json from Downloads into the folder.

projectmanagr looks for exactly that path; nothing is stored inside the package, so secrets never live in version control.

Why this folder? rappdirs::user_config_dir() is the cross-platform location recommended for end-user config files.

# to confirm the file has the correct path, execute this function:
fs::file_exists(
  fs::path(rappdirs::user_config_dir("projectmanagr"),
  "gcal_oauth_client.json"))
  #> should return: TRUE

3 Confirm projectmanagr Google Calendar access

To test that projectmanagr can now access Google Calendar, run the following from an R console

# attempt to extract google calendar events
projectmanagr::extract_google_calendar_events()
 # default args include:
  # day A date (defaults to today) to fetch events for
  # settings An optional list, can include `googleCalendars` for calendar filtering

  • If setup correctly, when first run:

    • a Google Login screen will open in the Default browser

      • Choose an account: Login with your credentials

      • Google hasn’t verified this app: Continue

        • The app is still in Testing, but you have given your google account permission to use this OAuth Client App

      • Sign in to ProjectManagr Calendar: Continue

        • By continuing, Google will share your name, email address and profile picture with ProjectManagr Calendar

      • ProjectManagr Calendar wants access to your Google Account:

        • See and download any calendar that you can access using your Google Calendar.

      • Authentication complete. Please close this page and return to R.

      • If Gargle “Out-of-Band” authentication fails:

        • Make sure that you trust ProjectManagr Calendar:

        • Copy the authorisation code from the authorisation code section.

        • Paste the authorisation code on the ProjectManagr console:

          • Enter authorization code:

      • This browser tab can now be safely closed

    • The R console should return a list of your Google Calendar Events from today

Once complete a cache of this token is stored in the projectmanagr cache dir:

rappdirs::user_cache_dir("projectmanagr")

  • The file typically has a hash prefix then user email suffix:

    • HASH_CODE_user@email.com

  • This authorisation token typically lasts 1 hour

    • After this time, a refresh token must be generated

    • This is automated by the code within projectmanagr

    • The refresh tokens issued to a Testing app expire after 7 days

      • If this limit expires you’ll be prompted to log in again

4 What each field in the OAuth Client App JSON does

The gcal_oauth_client.json file contains the following contents:

key purpose safe to expose?
client_id Identifies your app to Google’s auth server. Yes – public.
client_secret Confirms the app in the token-exchange step. Required for Desktop clients ([Using OAuth 2.0 for Server to Server Applications Authorization](https://developers.google.com/identity/protocols/oauth2/service-account)).
auth_uri Browser end-point where the user signs in. Public.
token_uri HTTPS end-point where R exchanges the auth code for tokens. Public.
redirect_uris Must include http://localhost so the local R session can receive the auth code. Public.

5 Troubleshooting checklist

symptom fix
“client_secret is missing” Ensure you used a Desktop app client and the JSON still contains "client_secret": "GOCSPX-…"
Browser opens twice Delete the stale token cache: unlink(rappdirs::user_cache_dir("projectmanagr"), recursive = TRUE) and retry.
invalid_scope error Make sure the Calendar API is enabled in the same Cloud project.
“App isn’t verified” banner Publish the OAuth consent screen, or restrict scopes to read-only.

6 Security note

Projectmanagr needs an OAuth credential (client-ID + client-secret) because Google still requires both fields for Desktop-app authentication.

However, Google classifies Desktop secrets as public-information: they can be embedded in every end-user machine and cannot be kept confidential . Anyone who gets your JSON could call Google APIs as your application, but never as your Google account — end-users must still grant consent and tokens are short-lived.

Why generate your own credential?

  • Keeps your calendars under your own Google Cloud project and quota.
  • Prevents other Projectmanagr users from “impersonating” your application brand.
  • Lets you reset or revoke the secret at any time.

If you suspect the JSON leaked (committed, e-mailed, etc.) simply reset the client-secret; previously issued refresh-tokens stop working and a new JSON replaces the old one.

How to reset the client-secret (and download the new JSON)

  1. Open Credentials page
    https://console.cloud.google.com/apis/credentials
    This lists every OAuth client in the current project.

  2. Select your Desktop-app client
    Click its name to open the details panel.

  3. Reset secret
    In the top-right, click “Reset Secret” (two-arrow icon).
    Google immediately generates a new secret and invalidates the old one.
    Console path: Credentials ▸ OAuth 2.0 Client IDs ▸ 〈your-client〉 ▸ Reset Secret

— or — Reset an existing client

  • On the Credentials page click the name of your Desktop-app client.
  • On the detail screen click Reset secret / Add secret (two-arrow icon). Confirm.
  • Click Download JSON to grab the updated file.
    Why? Rotating the secret immediately invalidates the old one if you ever leaked it.

  1. Download JSON
    After the reset, click Download JSON.
    Save the file as
    rappdirs::user_config_dir("projectmanagr")/gcal_oauth_client.json.
    (On macOS that’s ~/Library/Application Support/projectmanagr/.)

  2. Restart R / rerun projectmanagr
    The next extract_google_calendar_events() call will pick up the new JSON, open a browser once for consent, and cache a fresh token.

Tip: deleting the cached token directory
unlink(rappdirs::user_cache_dir("projectmanagr"), recursive = TRUE)
forces a brand-new OAuth dance with the new secret.

Now you—and only you—can authorise Projectmanagr to read your calendars, and you can rotate or revoke that access whenever you like.

Example

This is a basic example which shows you how to solve a common problem:

library(projectmanagr)
## basic example code

What is special about using README.Rmd instead of just README.md? You can include R chunks like so:

summary(cars)
#>      speed           dist       
#>  Min.   : 4.0   Min.   :  2.00  
#>  1st Qu.:12.0   1st Qu.: 26.00  
#>  Median :15.0   Median : 36.00  
#>  Mean   :15.4   Mean   : 42.98  
#>  3rd Qu.:19.0   3rd Qu.: 56.00  
#>  Max.   :25.0   Max.   :120.00

You’ll still need to render README.Rmd regularly, to keep README.md up-to-date.

devtools::build_readme() is handy for this.

You can also embed plots, for example:

In that case, don’t forget to commit and push the resulting figure files, so they display on GitHub and CRAN.

About

A library for organising project documentation in R Markdown.

Resources

Readme
GPL-3.0 license
Activity

Stars

1 star

Watchers

1 watching

Forks

1 fork
Report repository

Releases

Packages

Used by

Contributors

Languages