dspot-trello-gantt 0.3.4 → 0.3.6

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
  1. package/README.md +137 -219
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -1,311 +1,229 @@
1
- # dspot-trello-gantt
1
+ # Quick Guide: dspot-trello-gantt
2
2
 
3
- 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.
4
-
5
- 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.
3
+ This document summarizes the real installation and publishing flow we validated, including common errors and how to fix them.
6
4
 
7
5
  ## Index
8
6
 
9
- - [Quick Start](#quick-start)
10
- - [Installation](#installation)
7
+ - [1) Install and validate the CLI](#1-install-and-validate-the-cli)
8
+ - [2) Initialize a local project](#2-initialize-a-local-project)
9
+ - [3) Configure Trello in `.env`](#3-configure-trello-in-env)
10
+ - [4) Generate a local report](#4-generate-a-local-report)
11
+ - [5) Configure publishing to Google Apps Script](#5-configure-publishing-to-google-apps-script)
12
+ - [6) Publish](#6-publish)
11
13
  - [Commands](#commands)
12
- - [Configuration](#configuration)
13
- - [Progress percentage](#progress-percentage)
14
- - [Progress](#progress)
15
- - [Milestones](#milestones)
16
- - [Install + credentials (step by step)](#install--credentials-step-by-step)
17
- - [Publish flow (Google Apps Script)](#publish-flow-google-apps-script)
18
- - [MCP server](#mcp-server)
19
- - [Programmatic usage](#programmatic-usage)
20
- - [License](#license)
21
-
22
- ## Quick Start
14
+ - [Common errors (and fixes)](#common-errors-and-fixes)
15
+ - [Operational recommendation](#operational-recommendation)
23
16
 
24
- ```bash
25
- npm install -g dspot-trello-gantt
26
- trello-gantt-js init # creates a .env template in the current directory
27
- # fill in .env with your credentials
28
- trello-gantt-js generate # generates gantt.html
29
- trello-gantt-js generate --timestamp-output # generates gantt-YYYYMMDDTHHMMSSZ.html
30
- ```
17
+ ## 1) Install and validate the CLI
31
18
 
32
- ## Installation
19
+ Requirement: Node.js `>=18` (recommended LTS versions: `18`, `20`, or newer).
33
20
 
34
21
  ```bash
22
+ node -v
23
+ npm -v
35
24
  npm install -g dspot-trello-gantt
25
+ trello-gantt-js --help
36
26
  ```
37
27
 
38
- Requires Node.js 18 or later.
28
+ If `trello-gantt-js --help` returns output, the global installation is correct.
39
29
 
40
- ## Commands
41
-
42
- ### `generate` (default)
43
-
44
- Fetches Trello data and generates a standalone HTML file.
30
+ To update the CLI later, run:
45
31
 
46
32
  ```bash
47
- trello-gantt-js generate [options]
33
+ npm install -g dspot-trello-gantt@latest
48
34
  ```
49
35
 
50
- | Option | Env variable | Description |
51
- |---|---|---|
52
- | `--board-id <id>` | `GANTT_BOARD_ID` | Trello board ID or URL |
53
- | `--title <title>` | `GANTT_TITLE` | Chart title (default: `Project Gantt Chart`) |
54
- | `--lists <names>` | `GANTT_LISTS` | Comma-separated list names to include. Empty = all lists |
55
- | `--milestone-list <names>` | `GANTT_MILESTONE_LISTS` | Lists to group as milestones |
56
- | `--output <path>` | `GANTT_OUTPUT` | Output file path (default: `gantt.html`) |
57
- | `--timestamp-output` | `GANTT_TIMESTAMP_OUTPUT` | Appends UTC timestamp to output filename |
58
-
59
- ### `publish`
60
-
61
- Generates the HTML and uploads it to a Google Apps Script web app. Clients access a stable URL that always shows the latest version.
62
-
63
- ```bash
64
- trello-gantt-js publish [options]
65
- ```
66
-
67
- Accepts the same options as `generate` (except `--output`). Requires additional environment variables:
68
-
69
- | Env variable | Description |
70
- |---|---|
71
- | `GAPPS_SCRIPT_ID` | Apps Script project ID |
72
- | `GAPPS_DEPLOYMENT_ID` | Deployment ID (stable URL) |
73
- | `GAPPS_ALLOWED_EMAILS` | Comma-separated email allowlist. Empty = public access |
74
-
75
- On first run, a browser window opens for Google OAuth authorization. The token is cached in `credentials/token.json` for subsequent runs.
76
-
77
- ### `init`
78
-
79
- Creates a `.env` template in the current directory.
36
+ ## 2) Initialize a local project
80
37
 
81
38
  ```bash
39
+ mkdir trello-gantt-report
40
+ cd trello-gantt-report
82
41
  trello-gantt-js init
83
42
  ```
84
43
 
85
- ## Configuration
44
+ This creates the base `.env` file.
86
45
 
87
- All options can be set via a `.env` file in the working directory:
46
+ ## 3) Configure Trello in `.env`
47
+
48
+ In `.env`:
88
49
 
89
50
  ```env
90
- # Trello
91
- TRELLO_API_KEY=your_api_key
92
- TRELLO_API_TOKEN=your_api_token
51
+ TRELLO_API_KEY=...
52
+ TRELLO_API_TOKEN=...
93
53
  GANTT_BOARD_ID=https://trello.com/b/abc123/board-name
94
54
  GANTT_LISTS=Backlog,To Do,Doing,Done
55
+ GANTT_MILESTONE_LISTS=Milestone 1,Milestone 2
56
+ GANTT_TITLE=Project Gantt Chart
95
57
  GANTT_OUTPUT=output/gantt.html
96
58
  GANTT_TIMESTAMP_OUTPUT=false
97
- GANTT_TITLE=Project Gantt Chart
98
- GANTT_MILESTONE_LISTS=Milestone 1,Milestone 2
99
-
100
- # Google Apps Script (only needed for publish)
101
- GAPPS_SCRIPT_ID=
102
- GAPPS_DEPLOYMENT_ID=
103
- GAPPS_ALLOWED_EMAILS=
104
59
  ```
105
60
 
106
- **Trello credentials:** get your API key and token at [trello.com/app-key](https://trello.com/app-key).
107
-
108
- **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`.
61
+ How to get Trello credentials:
109
62
 
110
- > **Important:** the `credentials/` folder is listed in `.gitignore` and must never be committed. It contains OAuth secrets and cached tokens.
63
+ 1. Open `https://trello.com/app-key` while logged into the Trello account that has access to your board.
64
+ 2. Copy your **API Key** and use it as `TRELLO_API_KEY`.
65
+ 3. On the same page, click the token link/button (usually "Token") to generate a user token.
66
+ 4. Authorize access and copy the generated token.
67
+ 5. Use that value as `TRELLO_API_TOKEN`.
68
+ 6. Use your board URL (or board ID) as `GANTT_BOARD_ID`.
111
69
 
112
- ## Progress percentage
70
+ How to get `GANTT_MILESTONE_LISTS`:
113
71
 
114
- Add a `## Progress` section to a card's description to set completion:
72
+ 1. Open your Trello board.
73
+ 2. Identify the exact list names you want to treat as milestones (for example `Milestone 1`, `Milestone 2`).
74
+ 3. Add them as a comma-separated value in `.env`, preserving the same spelling as in Trello.
75
+ 4. Leave it empty if you prefer default milestone detection behavior.
115
76
 
116
- ```
117
- ## Progress
118
- 72
119
- ```
120
-
121
- Values 0–100. The `%` symbol is optional. No section = 0%.
77
+ How to get `GANTT_LISTS`:
122
78
 
123
- ## Milestones
79
+ 1. Open your Trello board and review the list names.
80
+ 2. Choose which lists should be included in the Gantt output.
81
+ 3. Add those list names in `.env` as a comma-separated value (for example `Backlog,To Do,Doing,Done`).
82
+ 4. Leave it empty to include all lists.
124
83
 
125
- `GANTT_MILESTONE_LISTS` uses **list names**, not labels.
84
+ Progress percentage from Trello cards:
126
85
 
127
- - If a card is in one of those lists, that list name is used as the Gantt section.
128
- - 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).
129
- - If `GANTT_MILESTONE_LISTS` is empty, the tool falls back to any label that starts with `Milestone` (for example: `Milestone 1`, `Milestone Design`).
130
- - If no valid milestone is found, the card is grouped under `No Milestone`.
86
+ - The chart reads each card progress from a `## Progress` section in the card description.
87
+ - Example:
88
+ - `## Progress`
89
+ - `72`
90
+ - Accepted values are `0` to `100` (the `%` symbol is optional). If the section is missing, progress defaults to `0%`.
131
91
 
132
- Example:
92
+ What `GANTT_TIMESTAMP_OUTPUT` is for:
133
93
 
134
- ```env
135
- GANTT_MILESTONE_LISTS=Milestone 1,Milestone 2
136
- ```
94
+ - Controls whether each generated file uses a unique timestamped name.
95
+ - `false` (default): writes to a stable filename (for example `gantt.html`) and replaces it on each run.
96
+ - `true`: creates versioned files (for example `gantt-YYYYMMDDTHHMMSSZ.html`), useful for keeping history and avoiding overwrites.
137
97
 
138
- ## Install + credentials (step by step)
98
+ What `GANTT_TITLE` is for:
139
99
 
140
- ### 1) Install Node.js and the CLI
100
+ - Sets the title shown in the generated Gantt chart.
101
+ - Use it to display a project/client-specific name (for example `Website Migration - Q2`).
102
+ - If not set, the tool uses its default chart title.
141
103
 
142
- 1. Install Node.js 18+ from [nodejs.org](https://nodejs.org/).
143
- 2. Verify:
104
+ What `GANTT_OUTPUT` is for:
144
105
 
145
- ```bash
146
- node -v
147
- npm -v
148
- ```
106
+ - Defines where the generated HTML file is saved.
107
+ - Use it when you want the report in a specific folder or filename (for example `output/gantt.html`).
108
+ - If not set, the tool uses its default output path.
149
109
 
150
- 3. Install:
110
+ ## 4) Generate a local report
151
111
 
152
112
  ```bash
153
- npm install -g dspot-trello-gantt
113
+ trello-gantt-js generate
154
114
  ```
155
115
 
156
- ### 2) Create local config
116
+ Optional with timestamp:
157
117
 
158
118
  ```bash
159
- mkdir trello-gantt-report
160
- cd trello-gantt-report
161
- trello-gantt-js init
119
+ trello-gantt-js generate --timestamp-output
162
120
  ```
163
121
 
164
- This creates `.env` in the current folder.
122
+ ## 5) Configure publishing to Google Apps Script
165
123
 
166
- ### 3) Get Trello API key/token
167
-
168
- 1. Open [trello.com/app-key](https://trello.com/app-key)
169
- 2. Copy API key.
170
- 3. Generate/copy token.
171
- 4. Save both in `.env`:
124
+ In `.env`:
172
125
 
173
126
  ```env
174
- TRELLO_API_KEY=...
175
- TRELLO_API_TOKEN=...
176
- GANTT_BOARD_ID=https://trello.com/b/abc123/board-name
177
- ```
178
-
179
- ### 4) Generate your first report
180
-
181
- ```bash
182
- trello-gantt-js generate
183
- ```
184
-
185
- Optional versioned filename:
186
-
187
- ```bash
188
- trello-gantt-js generate --timestamp-output
127
+ GAPPS_SCRIPT_ID=...
128
+ GAPPS_DEPLOYMENT_ID=...
129
+ GAPPS_ALLOWED_EMAILS=
189
130
  ```
190
131
 
191
- Or keep it enabled in `.env`:
132
+ `GAPPS_ALLOWED_EMAILS` is the comma-separated list of email addresses allowed to access the published Gantt web app.
133
+ If left empty, access is public (based on your web app deployment settings).
192
134
 
193
- ```env
194
- GANTT_TIMESTAMP_OUTPUT=true
195
- ```
135
+ How to find `GAPPS_SCRIPT_ID`:
196
136
 
197
- ## Publish flow (Google Apps Script)
137
+ - Open your Apps Script project.
138
+ - Go to **Project Settings** (gear icon).
139
+ - Copy the value shown as **Script ID**.
140
+ - Paste it into `.env` as `GAPPS_SCRIPT_ID`.
198
141
 
199
- This flow generates HTML and updates a stable live URL.
142
+ How to find `GAPPS_DEPLOYMENT_ID`:
200
143
 
201
- ### Required values
144
+ - Open your Apps Script project.
145
+ - Click **Deploy** -> **Manage deployments**.
146
+ - If no deployment exists yet, create one first:
147
+ - Click **New deployment**.
148
+ - Select type **Web app**.
149
+ - Configure access as needed and click **Deploy**.
150
+ - After deployment is created/updated, copy the value shown as **Deployment ID**.
151
+ - Paste it into `.env` as `GAPPS_DEPLOYMENT_ID`.
202
152
 
203
- - `GAPPS_SCRIPT_ID`: Apps Script project ID
204
- - `GAPPS_DEPLOYMENT_ID`: deployment ID of the web app
205
- - `credentials/google_oauth_client.json`: OAuth client from Google Cloud
153
+ Also:
206
154
 
207
- ### First-time setup
155
+ 1. Create a credentials folder:
156
+ ```bash
157
+ mkdir -p credentials
158
+ ```
159
+ 2. Download the OAuth Client JSON from Google Cloud and save it as:
160
+ `credentials/google_oauth_client.json`
208
161
 
209
- 1. Create folder:
162
+ ## 6) Publish
210
163
 
211
164
  ```bash
212
- mkdir -p credentials
165
+ trello-gantt-js publish
213
166
  ```
214
167
 
215
- 2. Download OAuth client JSON from Google Cloud Console and save as:
216
- `credentials/google_oauth_client.json`
217
- 3. Set variables in `.env`:
168
+ On the first run, Google OAuth opens and `credentials/token.json` is saved.
218
169
 
219
- ```env
220
- GAPPS_SCRIPT_ID=...
221
- GAPPS_DEPLOYMENT_ID=...
222
- GAPPS_ALLOWED_EMAILS=
223
- ```
170
+ ## Commands
224
171
 
225
- ### Run publish
172
+ - `trello-gantt-js init`: creates a base `.env` template in the current folder.
173
+ - `trello-gantt-js generate`: generates a local HTML Gantt report.
174
+ - `trello-gantt-js generate --timestamp-output`: generates a versioned output filename with UTC timestamp.
175
+ - `trello-gantt-js publish`: generates and uploads the report to Google Apps Script.
176
+ - `trello-gantt-js --help`: shows CLI help and available options.
226
177
 
227
- ```bash
228
- trello-gantt-js publish
229
- ```
178
+ ## Common errors (and fixes)
230
179
 
231
- On first run, browser OAuth opens and stores token at `credentials/token.json`.
180
+ ### Error 403: `access_denied` on Google screen
232
181
 
233
- ### Multi-user setup for Google credentials
182
+ Typical message: _"only be accessed by developer-approved testers"_.
234
183
 
235
- 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.
184
+ Most likely cause:
236
185
 
237
- - Shareable: `credentials/google_oauth_client.json` (OAuth client configuration).
238
- - Not shareable: `credentials/token.json` (user session token, generated per user).
186
+ - The OAuth app is in **Testing** mode and the email is not in **Test users**.
239
187
 
240
- For this to work, each user must be allowed to use the OAuth app in Google Cloud:
188
+ Fix:
241
189
 
242
- 1. Open Google Cloud Console for the project that owns the OAuth client.
243
- 2. Go to **OAuth consent screen**.
244
- 3. If app status is **Testing**, add each user under **Test users**.
245
- 4. Ensure users also have access to the Apps Script project/deployment they will publish to.
190
+ 1. Go to Google Cloud Console -> OAuth consent screen -> Test users.
191
+ 2. Add the user email (for example `ymesa88@gmail.com`).
192
+ 3. Verify `google_oauth_client.json` belongs to that same OAuth project.
193
+ 4. Delete `credentials/token.json` and retry `trello-gantt-js publish`.
246
194
 
247
- If a user is not allowed, OAuth authentication can fail even if `google_oauth_client.json` is correct.
195
+ > Important: Giving IAM "Editor" in Google Cloud does **not replace** the Test users list in OAuth consent screen.
248
196
 
249
- ## MCP server
197
+ ### Error: `The caller does not have permission`
250
198
 
251
- Run as an [MCP](https://modelcontextprotocol.io) server so Claude Desktop, Claude Code, or any MCP client can generate Gantt charts directly.
199
+ If this appears during Apps Script upload:
252
200
 
253
- ```bash
254
- trello-gantt-js mcp
255
- ```
201
+ - Check that `GAPPS_SCRIPT_ID` and `GAPPS_DEPLOYMENT_ID` are correct and from the same project.
202
+ - Share the Apps Script project with the user as **Editor**.
203
+ - Delete `credentials/token.json` to re-authenticate with the correct account.
256
204
 
257
- ### Claude Desktop / Claude Code configuration
258
-
259
- Add to your `claude_desktop_config.json` or Claude Code settings:
260
-
261
- ```json
262
- {
263
- "mcpServers": {
264
- "trello-gantt": {
265
- "command": "npx",
266
- "args": ["-y", "dspot-trello-gantt", "mcp"],
267
- "env": {
268
- "TRELLO_API_KEY": "your_api_key",
269
- "TRELLO_API_TOKEN": "your_api_token",
270
- "GANTT_BOARD_ID": "https://trello.com/b/abc123/board-name"
271
- }
272
- }
273
- }
274
- }
275
- ```
205
+ ### Error: `Only users in the same domain as the script owner may deploy this script`
276
206
 
277
- Setting `GANTT_BOARD_ID` is recommended — without it the agent will ask for the board ID on every call.
207
+ Cause:
278
208
 
279
- ### Available tools
209
+ - Google Apps Script/Workspace domain restriction for deployments.
280
210
 
281
- | Tool | Description |
282
- |---|---|
283
- | `generate_gantt` | Fetches a Trello board and generates a standalone Gantt HTML file |
284
- | `publish_gantt` | Generates the Gantt HTML and publishes it to Google Apps Script |
211
+ What this means:
285
212
 
286
- `publish_gantt` requires `GAPPS_SCRIPT_ID` and `GAPPS_DEPLOYMENT_ID` in the environment.
213
+ - Users outside the owner's domain may edit, but cannot necessarily deploy.
287
214
 
288
- ## Programmatic usage
215
+ Options:
289
216
 
290
- ```typescript
291
- import {
292
- parseBoardId,
293
- getCardsForLists,
294
- mapCardsToGanttTasks,
295
- validateTasks,
296
- generateMermaidGantt,
297
- renderHtml,
298
- publishToAppsScript,
299
- } from 'dspot-trello-gantt';
217
+ - Always publish with the script owner account.
218
+ - Create/transfer the script to an account in the same domain as the user who will publish.
219
+ - Ask the Google Workspace admin to review deployment/sharing policies.
300
220
 
301
- const boardId = parseBoardId('https://trello.com/b/abc123/my-board');
302
- const fetchResult = await getCardsForLists(boardId);
303
- const { tasks, warnings, stats, assigneeLegend } = mapCardsToGanttTasks(fetchResult.cardsByList);
304
- const report = validateTasks(tasks, warnings, stats);
305
- const mermaid = generateMermaidGantt(tasks, 'My Project');
306
- const html = renderHtml(mermaid, report, { title: 'My Project', assigneeLegend });
307
- ```
221
+ ## Operational recommendation
222
+
223
+ If you have external users (for example `@gmail.com` accounts) and your script is corporate-owned, use this flow:
224
+
225
+ 1. External users generate locally (`generate`).
226
+ 2. Only the owner account (or same-domain account) runs `publish`.
308
227
 
309
- ## License
228
+ This avoids domain policy deployment blocks.
310
229
 
311
- MIT
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "dspot-trello-gantt",
3
- "version": "0.3.4",
3
+ "version": "0.3.6",
4
4
  "description": "Generate Gantt chart HTML from Trello board data",
5
5
  "keywords": [
6
6
  "trello",