dspot-trello-gantt 0.2.0 → 0.2.2

package/README.md

@@ -0,0 +1,128 @@
+# 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.
+
+## Quick Start
+
+```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
+```
+
+## Installation
+
+```bash
+npm install -g dspot-trello-gantt
+```
+
+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`) |
+
+### `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.
+
+```bash
+trello-gantt-js init
+```
+
+## Configuration
+
+All options can be set via a `.env` file in the working directory:
+
+```env
+# Trello
+TRELLO_API_KEY=your_api_key
+TRELLO_API_TOKEN=your_api_token
+GANTT_BOARD_ID=https://trello.com/b/abc123/board-name
+GANTT_LISTS=Backlog,To Do,Doing,Done
+GANTT_OUTPUT=output/gantt.html
+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.
+
+## Progress percentage
+
+Add a `## Progress` section to a card's description to set completion:
+
+```
+## Progress
+72
+```
+
+Values 0–100. The `%` symbol is optional. No section = 0%.
+
+## Programmatic usage
+
+```typescript
+import {
+  parseBoardId,
+  getCardsForLists,
+  mapCardsToGanttTasks,
+  validateTasks,
+  generateMermaidGantt,
+  renderHtml,
+  publishToAppsScript,
+} from 'dspot-trello-gantt';
+
+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 });
+```
+
+## License
+
+MIT

package/package.json

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