npm - dspot-trello-gantt - Versions diffs - 0.3.4 → 0.3.5 - Mend

dspot-trello-gantt 0.3.4 → 0.3.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (2) hide show

package/README.md +135 -223
package/package.json +1 -1

package/README.md CHANGED Viewed

@@ -1,311 +1,223 @@
-# dspot-trello-gantt
+# Quick Guide: dspot-trello-gantt
-Generate Gantt chart HTML from a Trello board. Fetches cards via the Trello API, converts them to [Mermaid](https://mermaid.js.org/) Gantt syntax, and produces a standalone interactive HTML file.
-Optionally publishes the result directly to a [Google Apps Script](https://script.google.com) web app so clients can access it via a stable URL.
+This document summarizes the real installation and publishing flow we validated, including common errors and how to fix them.
 ## Index
-- [Quick Start](#quick-start)
-- [Installation](#installation)
+- [1) Install and validate the CLI](#1-install-and-validate-the-cli)
+- [2) Initialize a local project](#2-initialize-a-local-project)
+- [3) Configure Trello in `.env`](#3-configure-trello-in-env)
+- [4) Generate a local report](#4-generate-a-local-report)
+- [5) Configure publishing to Google Apps Script](#5-configure-publishing-to-google-apps-script)
+- [6) Publish](#6-publish)
 - [Commands](#commands)
-- [Configuration](#configuration)
-- [Progress percentage](#progress-percentage)
-- [Progress](#progress)
-- [Milestones](#milestones)
-- [Install + credentials (step by step)](#install--credentials-step-by-step)
-- [Publish flow (Google Apps Script)](#publish-flow-google-apps-script)
-- [MCP server](#mcp-server)
-- [Programmatic usage](#programmatic-usage)
-- [License](#license)
-## Quick Start
+- [Common errors (and fixes)](#common-errors-and-fixes)
+- [Operational recommendation](#operational-recommendation)
-```bash
-npm install -g dspot-trello-gantt
-trello-gantt-js init        # creates a .env template in the current directory
-# fill in .env with your credentials
-trello-gantt-js generate    # generates gantt.html
-trello-gantt-js generate --timestamp-output   # generates gantt-YYYYMMDDTHHMMSSZ.html
-```
+## 1) Install and validate the CLI
-## Installation
+Requirement: Node.js `>=18` (recommended LTS versions: `18`, `20`, or newer).
 ```bash
+node -v
+npm -v
 npm install -g dspot-trello-gantt
+trello-gantt-js --help
 ```
-Requires Node.js 18 or later.
-## Commands
-### `generate` (default)
-Fetches Trello data and generates a standalone HTML file.
-```bash
-trello-gantt-js generate [options]
-```
-| Option | Env variable | Description |
-|---|---|---|
-| `--board-id <id>` | `GANTT_BOARD_ID` | Trello board ID or URL |
-| `--title <title>` | `GANTT_TITLE` | Chart title (default: `Project Gantt Chart`) |
-| `--lists <names>` | `GANTT_LISTS` | Comma-separated list names to include. Empty = all lists |
-| `--milestone-list <names>` | `GANTT_MILESTONE_LISTS` | Lists to group as milestones |
-| `--output <path>` | `GANTT_OUTPUT` | Output file path (default: `gantt.html`) |
-| `--timestamp-output` | `GANTT_TIMESTAMP_OUTPUT` | Appends UTC timestamp to output filename |
+If `trello-gantt-js --help` returns output, the global installation is correct.
-### `publish`
-Generates the HTML and uploads it to a Google Apps Script web app. Clients access a stable URL that always shows the latest version.
-```bash
-trello-gantt-js publish [options]
-```
-Accepts the same options as `generate` (except `--output`). Requires additional environment variables:
-| Env variable | Description |
-|---|---|
-| `GAPPS_SCRIPT_ID` | Apps Script project ID |
-| `GAPPS_DEPLOYMENT_ID` | Deployment ID (stable URL) |
-| `GAPPS_ALLOWED_EMAILS` | Comma-separated email allowlist. Empty = public access |
-On first run, a browser window opens for Google OAuth authorization. The token is cached in `credentials/token.json` for subsequent runs.
-### `init`
-Creates a `.env` template in the current directory.
+## 2) Initialize a local project
 ```bash
+mkdir trello-gantt-report
+cd trello-gantt-report
 trello-gantt-js init
 ```
-## Configuration
+This creates the base `.env` file.
-All options can be set via a `.env` file in the working directory:
+## 3) Configure Trello in `.env`
+In `.env`:
 ```env
-# Trello
-TRELLO_API_KEY=your_api_key
-TRELLO_API_TOKEN=your_api_token
+TRELLO_API_KEY=...
+TRELLO_API_TOKEN=...
 GANTT_BOARD_ID=https://trello.com/b/abc123/board-name
 GANTT_LISTS=Backlog,To Do,Doing,Done
+GANTT_MILESTONE_LISTS=Milestone 1,Milestone 2
+GANTT_TITLE=Project Gantt Chart
 GANTT_OUTPUT=output/gantt.html
 GANTT_TIMESTAMP_OUTPUT=false
-GANTT_TITLE=Project Gantt Chart
-GANTT_MILESTONE_LISTS=Milestone 1,Milestone 2
-# Google Apps Script (only needed for publish)
-GAPPS_SCRIPT_ID=
-GAPPS_DEPLOYMENT_ID=
-GAPPS_ALLOWED_EMAILS=
 ```
-**Trello credentials:** get your API key and token at [trello.com/app-key](https://trello.com/app-key).
-**Google credentials:** download an OAuth 2.0 client JSON from [Google Cloud Console](https://console.cloud.google.com) and save it as `credentials/google_oauth_client.json`.
-> **Important:** the `credentials/` folder is listed in `.gitignore` and must never be committed. It contains OAuth secrets and cached tokens.
+How to get Trello credentials:
-## Progress percentage
+1. Open `https://trello.com/app-key` while logged into the Trello account that has access to your board.
+2. Copy your **API Key** and use it as `TRELLO_API_KEY`.
+3. On the same page, click the token link/button (usually "Token") to generate a user token.
+4. Authorize access and copy the generated token.
+5. Use that value as `TRELLO_API_TOKEN`.
+6. Use your board URL (or board ID) as `GANTT_BOARD_ID`.
-Add a `## Progress` section to a card's description to set completion:
+How to get `GANTT_MILESTONE_LISTS`:
-```
-## Progress
-72
-```
+1. Open your Trello board.
+2. Identify the exact list names you want to treat as milestones (for example `Milestone 1`, `Milestone 2`).
+3. Add them as a comma-separated value in `.env`, preserving the same spelling as in Trello.
+4. Leave it empty if you prefer default milestone detection behavior.
-Values 0–100. The `%` symbol is optional. No section = 0%.
+How to get `GANTT_LISTS`:
-## Milestones
+1. Open your Trello board and review the list names.
+2. Choose which lists should be included in the Gantt output.
+3. Add those list names in `.env` as a comma-separated value (for example `Backlog,To Do,Doing,Done`).
+4. Leave it empty to include all lists.
-`GANTT_MILESTONE_LISTS` uses **list names**, not labels.
+Progress percentage from Trello cards:
-- If a card is in one of those lists, that list name is used as the Gantt section.
-- If `GANTT_MILESTONE_LISTS` is set, label-based milestones are also restricted to that same list (for example, if only `Milestone 1,Milestone 2` are configured, `Milestone 3` labels are ignored).
-- If `GANTT_MILESTONE_LISTS` is empty, the tool falls back to any label that starts with `Milestone` (for example: `Milestone 1`, `Milestone Design`).
-- If no valid milestone is found, the card is grouped under `No Milestone`.
+- The chart reads each card progress from a `## Progress` section in the card description.
+- Example:
+  - `## Progress`
+  - `72`
+- Accepted values are `0` to `100` (the `%` symbol is optional). If the section is missing, progress defaults to `0%`.
-Example:
+What `GANTT_TIMESTAMP_OUTPUT` is for:
-```env
-GANTT_MILESTONE_LISTS=Milestone 1,Milestone 2
-```
+- Controls whether each generated file uses a unique timestamped name.
+- `false` (default): writes to a stable filename (for example `gantt.html`) and replaces it on each run.
+- `true`: creates versioned files (for example `gantt-YYYYMMDDTHHMMSSZ.html`), useful for keeping history and avoiding overwrites.
-## Install + credentials (step by step)
+What `GANTT_TITLE` is for:
-### 1) Install Node.js and the CLI
+- Sets the title shown in the generated Gantt chart.
+- Use it to display a project/client-specific name (for example `Website Migration - Q2`).
+- If not set, the tool uses its default chart title.
-1. Install Node.js 18+ from [nodejs.org](https://nodejs.org/).
-2. Verify:
+What `GANTT_OUTPUT` is for:
-```bash
-node -v
-npm -v
-```
+- Defines where the generated HTML file is saved.
+- Use it when you want the report in a specific folder or filename (for example `output/gantt.html`).
+- If not set, the tool uses its default output path.
-3. Install:
+## 4) Generate a local report
 ```bash
-npm install -g dspot-trello-gantt
+trello-gantt-js generate
 ```
-### 2) Create local config
+Optional with timestamp:
 ```bash
-mkdir trello-gantt-report
-cd trello-gantt-report
-trello-gantt-js init
+trello-gantt-js generate --timestamp-output
 ```
-This creates `.env` in the current folder.
-### 3) Get Trello API key/token
+## 5) Configure publishing to Google Apps Script
-1. Open [trello.com/app-key](https://trello.com/app-key)
-2. Copy API key.
-3. Generate/copy token.
-4. Save both in `.env`:
+In `.env`:
 ```env
-TRELLO_API_KEY=...
-TRELLO_API_TOKEN=...
-GANTT_BOARD_ID=https://trello.com/b/abc123/board-name
-```
-### 4) Generate your first report
-```bash
-trello-gantt-js generate
-```
-Optional versioned filename:
-```bash
-trello-gantt-js generate --timestamp-output
+GAPPS_SCRIPT_ID=...
+GAPPS_DEPLOYMENT_ID=...
+GAPPS_ALLOWED_EMAILS=
 ```
-Or keep it enabled in `.env`:
+`GAPPS_ALLOWED_EMAILS` is the comma-separated list of email addresses allowed to access the published Gantt web app.
+If left empty, access is public (based on your web app deployment settings).
-```env
-GANTT_TIMESTAMP_OUTPUT=true
-```
+How to find `GAPPS_SCRIPT_ID`:
-## Publish flow (Google Apps Script)
+- Open your Apps Script project.
+- Go to **Project Settings** (gear icon).
+- Copy the value shown as **Script ID**.
+- Paste it into `.env` as `GAPPS_SCRIPT_ID`.
-This flow generates HTML and updates a stable live URL.
+How to find `GAPPS_DEPLOYMENT_ID`:
-### Required values
+- Open your Apps Script project.
+- Click **Deploy** -> **Manage deployments**.
+- If no deployment exists yet, create one first:
+  - Click **New deployment**.
+  - Select type **Web app**.
+  - Configure access as needed and click **Deploy**.
+- After deployment is created/updated, copy the value shown as **Deployment ID**.
+- Paste it into `.env` as `GAPPS_DEPLOYMENT_ID`.
-- `GAPPS_SCRIPT_ID`: Apps Script project ID
-- `GAPPS_DEPLOYMENT_ID`: deployment ID of the web app
-- `credentials/google_oauth_client.json`: OAuth client from Google Cloud
+Also:
-### First-time setup
+1. Create a credentials folder:
+   ```bash
+   mkdir -p credentials
+   ```
+2. Download the OAuth Client JSON from Google Cloud and save it as:
+   `credentials/google_oauth_client.json`
-1. Create folder:
+## 6) Publish
 ```bash
-mkdir -p credentials
+trello-gantt-js publish
 ```
-2. Download OAuth client JSON from Google Cloud Console and save as:
-`credentials/google_oauth_client.json`
-3. Set variables in `.env`:
+On the first run, Google OAuth opens and `credentials/token.json` is saved.
-```env
-GAPPS_SCRIPT_ID=...
-GAPPS_DEPLOYMENT_ID=...
-GAPPS_ALLOWED_EMAILS=
-```
+## Commands
-### Run publish
+- `trello-gantt-js init`: creates a base `.env` template in the current folder.
+- `trello-gantt-js generate`: generates a local HTML Gantt report.
+- `trello-gantt-js generate --timestamp-output`: generates a versioned output filename with UTC timestamp.
+- `trello-gantt-js publish`: generates and uploads the report to Google Apps Script.
+- `trello-gantt-js --help`: shows CLI help and available options.
-```bash
-trello-gantt-js publish
-```
+## Common errors (and fixes)
-On first run, browser OAuth opens and stores token at `credentials/token.json`.
+### Error 403: `access_denied` on Google screen
-### Multi-user setup for Google credentials
+Typical message: _"only be accessed by developer-approved testers"_.
-You can reuse the same `credentials/google_oauth_client.json` across multiple users, but each user must authenticate with their own Google account on their machine.
+Most likely cause:
-- Shareable: `credentials/google_oauth_client.json` (OAuth client configuration).
-- Not shareable: `credentials/token.json` (user session token, generated per user).
+- The OAuth app is in **Testing** mode and the email is not in **Test users**.
-For this to work, each user must be allowed to use the OAuth app in Google Cloud:
+Fix:
-1. Open Google Cloud Console for the project that owns the OAuth client.
-2. Go to **OAuth consent screen**.
-3. If app status is **Testing**, add each user under **Test users**.
-4. Ensure users also have access to the Apps Script project/deployment they will publish to.
+1. Go to Google Cloud Console -> OAuth consent screen -> Test users.
+2. Add the user email (for example `ymesa88@gmail.com`).
+3. Verify `google_oauth_client.json` belongs to that same OAuth project.
+4. Delete `credentials/token.json` and retry `trello-gantt-js publish`.
-If a user is not allowed, OAuth authentication can fail even if `google_oauth_client.json` is correct.
+> Important: Giving IAM "Editor" in Google Cloud does **not replace** the Test users list in OAuth consent screen.
-## MCP server
+### Error: `The caller does not have permission`
-Run as an [MCP](https://modelcontextprotocol.io) server so Claude Desktop, Claude Code, or any MCP client can generate Gantt charts directly.
+If this appears during Apps Script upload:
-```bash
-trello-gantt-js mcp
-```
+- Check that `GAPPS_SCRIPT_ID` and `GAPPS_DEPLOYMENT_ID` are correct and from the same project.
+- Share the Apps Script project with the user as **Editor**.
+- Delete `credentials/token.json` to re-authenticate with the correct account.
-### Claude Desktop / Claude Code configuration
-Add to your `claude_desktop_config.json` or Claude Code settings:
-```json
-{
-  "mcpServers": {
-    "trello-gantt": {
-      "command": "npx",
-      "args": ["-y", "dspot-trello-gantt", "mcp"],
-      "env": {
-        "TRELLO_API_KEY": "your_api_key",
-        "TRELLO_API_TOKEN": "your_api_token",
-        "GANTT_BOARD_ID": "https://trello.com/b/abc123/board-name"
-      }
-    }
-  }
-}
-```
+### Error: `Only users in the same domain as the script owner may deploy this script`
-Setting `GANTT_BOARD_ID` is recommended — without it the agent will ask for the board ID on every call.
+Cause:
-### Available tools
+- Google Apps Script/Workspace domain restriction for deployments.
-| Tool | Description |
-|---|---|
-| `generate_gantt` | Fetches a Trello board and generates a standalone Gantt HTML file |
-| `publish_gantt` | Generates the Gantt HTML and publishes it to Google Apps Script |
+What this means:
-`publish_gantt` requires `GAPPS_SCRIPT_ID` and `GAPPS_DEPLOYMENT_ID` in the environment.
+- Users outside the owner's domain may edit, but cannot necessarily deploy.
-## Programmatic usage
+Options:
-```typescript
-import {
-  parseBoardId,
-  getCardsForLists,
-  mapCardsToGanttTasks,
-  validateTasks,
-  generateMermaidGantt,
-  renderHtml,
-  publishToAppsScript,
-} from 'dspot-trello-gantt';
+- Always publish with the script owner account.
+- Create/transfer the script to an account in the same domain as the user who will publish.
+- Ask the Google Workspace admin to review deployment/sharing policies.
-const boardId = parseBoardId('https://trello.com/b/abc123/my-board');
-const fetchResult = await getCardsForLists(boardId);
-const { tasks, warnings, stats, assigneeLegend } = mapCardsToGanttTasks(fetchResult.cardsByList);
-const report = validateTasks(tasks, warnings, stats);
-const mermaid = generateMermaidGantt(tasks, 'My Project');
-const html = renderHtml(mermaid, report, { title: 'My Project', assigneeLegend });
-```
+## Operational recommendation
+If you have external users (for example `@gmail.com` accounts) and your script is corporate-owned, use this flow:
+1. External users generate locally (`generate`).
+2. Only the owner account (or same-domain account) runs `publish`.
-## License
+This avoids domain policy deployment blocks.
-MIT

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "dspot-trello-gantt",
-  "version": "0.3.4",
+  "version": "0.3.5",
   "description": "Generate Gantt chart HTML from Trello board data",
   "keywords": [
     "trello",