@tenonhq/dovetail-dashboard 0.0.44 → 0.0.45
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.
- package/README.md +68 -37
- package/package.json +1 -1
- package/public/app.js +270 -66
- package/public/styles.css +22 -0
- package/server.js +567 -215
package/README.md
CHANGED
|
@@ -8,7 +8,7 @@ Web-based UI for managing ServiceNow update sets across scopes, with optional Cl
|
|
|
8
8
|
- Lists in-progress update sets per scope
|
|
9
9
|
- Lets you select, create, close, and clear update sets per scope
|
|
10
10
|
- Persists selections to `.dove-update-sets.json` — **`dove push` and `dove watch` honor these selections** via the `pushWithUpdateSet` REST endpoint
|
|
11
|
-
- Optional ClickUp integration: select a task,
|
|
11
|
+
- Optional ClickUp integration: select a task, then either activate update sets manually per scope or use **Start Task** to move the ClickUp status, create every scope's update set, and cut a working branch in one click
|
|
12
12
|
|
|
13
13
|
## Setup
|
|
14
14
|
|
|
@@ -21,14 +21,14 @@ Web-based UI for managing ServiceNow update sets across scopes, with optional Cl
|
|
|
21
21
|
|
|
22
22
|
Add these to your project's `.env`:
|
|
23
23
|
|
|
24
|
-
| Variable
|
|
25
|
-
|
|
26
|
-
| `SN_INSTANCE`
|
|
27
|
-
| `SN_USER`
|
|
28
|
-
| `SN_PASSWORD`
|
|
29
|
-
| `DASHBOARD_PORT`
|
|
30
|
-
| `CLICKUP_API_TOKEN` | No
|
|
31
|
-
| `CLICKUP_TEAM_ID`
|
|
24
|
+
| Variable | Required | Default | Description |
|
|
25
|
+
| ------------------- | -------- | ------- | ------------------------------------------------- |
|
|
26
|
+
| `SN_INSTANCE` | Yes | — | ServiceNow instance name (e.g. `tenonworkstudio`) |
|
|
27
|
+
| `SN_USER` | Yes | — | ServiceNow username |
|
|
28
|
+
| `SN_PASSWORD` | Yes | — | ServiceNow password |
|
|
29
|
+
| `DASHBOARD_PORT` | No | `3456` | Local server port |
|
|
30
|
+
| `CLICKUP_API_TOKEN` | No | — | ClickUp personal API token (enables task sidebar) |
|
|
31
|
+
| `CLICKUP_TEAM_ID` | No | — | ClickUp team ID (auto-detected if omitted) |
|
|
32
32
|
|
|
33
33
|
### Running
|
|
34
34
|
|
|
@@ -52,7 +52,7 @@ When you select an update set for a scope in the dashboard, it saves the mapping
|
|
|
52
52
|
{
|
|
53
53
|
"x_cadso_core": {
|
|
54
54
|
"sys_id": "abc123def456",
|
|
55
|
-
"name": "
|
|
55
|
+
"name": "DH | DEV-526 | Core | Automation program phase 1"
|
|
56
56
|
}
|
|
57
57
|
}
|
|
58
58
|
```
|
|
@@ -61,46 +61,73 @@ The core Dovetail push logic (`appUtils.ts:pushRec`) reads this file on every pu
|
|
|
61
61
|
|
|
62
62
|
## ClickUp Integration
|
|
63
63
|
|
|
64
|
-
When `CLICKUP_API_TOKEN` is configured, a "Tasks" button appears in the header. Clicking it opens a sidebar where you can:
|
|
64
|
+
When `CLICKUP_API_TOKEN` is configured, a "Tasks" button appears in the header. Clicking it opens a sidebar where you can filter tasks by status (default: "in progress") and click a task card to select it as the active task.
|
|
65
65
|
|
|
66
|
-
|
|
67
|
-
2. Select a task as the active task
|
|
68
|
-
3. Auto-generate update set names in the format `CU-{taskId} — {task name}`
|
|
69
|
-
4. Auto-activate all configured scopes — finds existing update sets or creates new ones
|
|
66
|
+
**Selecting a task is deliberately cheap and reversible.** It only writes local dashboard state (`.dove-active-task.json`) — it does not touch ClickUp, ServiceNow, or git. This lets you browse and pick a task without side effects. On select, the dashboard:
|
|
70
67
|
|
|
71
|
-
|
|
68
|
+
- Fetches your ClickUp profile (`GET /user`) to read your `initials`
|
|
69
|
+
- Reads the task's ClickUp `custom_id` (the `DEV-###` you see in the UI, not ClickUp's internal task ID)
|
|
70
|
+
- Sanitizes the task name into a short description
|
|
71
|
+
- Generates and stores the update-set base name, but does **not** create anything yet
|
|
72
|
+
|
|
73
|
+
### Update-set naming
|
|
74
|
+
|
|
75
|
+
Every update set the dashboard creates on your behalf follows one scope-aware format:
|
|
76
|
+
|
|
77
|
+
```
|
|
78
|
+
{devInitials} | {DEV-ID} | {App} | {shortDesc}
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
Example: `DH | DEV-526 | Core | Automation program phase 1`
|
|
82
|
+
|
|
83
|
+
`{App}` is derived per-scope from a label map (`x_cadso_journey`→Journey, `x_cadso_core`→Core, `x_cadso_automate`→Automate, `x_cadso_text_spoke`→Text, `x_cadso_email_spok`→Email; any other scope is title-cased from its name). Because the App segment is scope-specific, **a task with work spanning multiple scopes gets a differently-named update set per scope** — not one shared name reused everywhere (the old `CU-{taskId} — {task name}` behavior).
|
|
84
|
+
|
|
85
|
+
### Start Task — the one-click "I'm starting this" action
|
|
86
|
+
|
|
87
|
+
Once a task is selected, the active-task banner shows a **Start Task** button. This is the single deliberate action that turns "I'm looking at this ticket" into "I'm working on this ticket." Clicking it runs three steps, in order, and reports the outcome of each in a toast:
|
|
88
|
+
|
|
89
|
+
1. **ClickUp status → `in progress`** — a `PUT` to the ClickUp task, independent of whatever status filter you had selected in the sidebar.
|
|
90
|
+
2. **Per-scope update sets** — for every scope in `dove.config.js`, finds an existing in-progress update set matching the task (searched by the `DEV-ID` substring, not the full name, so a naming-format change doesn't orphan sets created under an older format) or creates one using the naming convention above. Reuses the same logic as the "Activate All" per-scope flow.
|
|
91
|
+
3. **Working branch** — cuts `dev/{git-username}/{DEV-ID}/{shortDesc}` in whatever repo checkout this dashboard process is running from (`git config user.name`, sanitized, supplies the username segment). If that branch already exists — e.g. you click Start Task again on the same ticket later — the dashboard switches to it instead of erroring.
|
|
92
|
+
|
|
93
|
+
**Scope note:** branch creation only happens in the repo the dashboard's `cwd` is inside (wherever you ran `dove dashboard` from). If a task's work spans two repos (e.g. a Mortise component and its ServiceNow-side records), Start Task only branches the one repo — the other still needs a manual branch.
|
|
94
|
+
|
|
95
|
+
If the ClickUp status update fails, Start Task stops there and reports the failure — it does not proceed to create update sets or a branch on an inconsistent state. Update-set and branch failures are reported per-item but don't block each other.
|
|
96
|
+
|
|
97
|
+
Active task state (including the resolved `devInitials`, `customId`, and `shortDesc`) is persisted to `.dove-active-task.json` and survives dashboard restarts.
|
|
72
98
|
|
|
73
99
|
## API Endpoints
|
|
74
100
|
|
|
75
101
|
### Update Set Management
|
|
76
102
|
|
|
77
|
-
| Method
|
|
78
|
-
|
|
79
|
-
| `GET`
|
|
80
|
-
| `GET`
|
|
81
|
-
| `POST`
|
|
82
|
-
| `PATCH` | `/api/update-set/:sysId/close` | Mark an update set as complete
|
|
83
|
-
| `POST`
|
|
84
|
-
| `GET`
|
|
103
|
+
| Method | Path | Description |
|
|
104
|
+
| ------- | ------------------------------ | -------------------------------------------------------------- |
|
|
105
|
+
| `GET` | `/api/scopes` | List configured scopes with display names and saved selections |
|
|
106
|
+
| `GET` | `/api/update-sets/:scope` | List in-progress update sets for a scope |
|
|
107
|
+
| `POST` | `/api/update-set` | Create a new update set |
|
|
108
|
+
| `PATCH` | `/api/update-set/:sysId/close` | Mark an update set as complete |
|
|
109
|
+
| `POST` | `/api/select-update-set` | Save scope-to-update-set mapping |
|
|
110
|
+
| `GET` | `/api/config` | Return saved config and instance name |
|
|
85
111
|
|
|
86
112
|
### ClickUp Integration
|
|
87
113
|
|
|
88
|
-
| Method | Path
|
|
89
|
-
|
|
90
|
-
| `GET`
|
|
91
|
-
| `GET`
|
|
92
|
-
| `GET`
|
|
93
|
-
| `POST` | `/api/clickup/select-task`
|
|
94
|
-
| `POST` | `/api/clickup/activate-scope`
|
|
95
|
-
| `POST` | `/api/clickup/activate-all-scopes` | Find/create update sets for all scopes
|
|
96
|
-
| `POST` | `/api/clickup/
|
|
114
|
+
| Method | Path | Description |
|
|
115
|
+
| ------ | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
|
|
116
|
+
| `GET` | `/api/clickup/status` | Check ClickUp configuration and active task |
|
|
117
|
+
| `GET` | `/api/clickup/tasks` | Fetch tasks (query: `?statuses=in progress,review`) |
|
|
118
|
+
| `GET` | `/api/clickup/task/:taskId` | Fetch single task details |
|
|
119
|
+
| `POST` | `/api/clickup/select-task` | Set the active task (local state only — no ClickUp/ServiceNow/git side effects) |
|
|
120
|
+
| `POST` | `/api/clickup/activate-scope` | Find/create update set for one scope |
|
|
121
|
+
| `POST` | `/api/clickup/activate-all-scopes` | Find/create update sets for all scopes |
|
|
122
|
+
| `POST` | `/api/clickup/start-task` | Set ClickUp status to in progress, find/create update sets for all scopes, and cut/switch the task's working branch |
|
|
123
|
+
| `POST` | `/api/clickup/deselect-task` | Clear the active task |
|
|
97
124
|
|
|
98
125
|
## Persistence Files
|
|
99
126
|
|
|
100
|
-
| File
|
|
101
|
-
|
|
102
|
-
| `.dove-update-sets.json` | Scope-to-update-set mapping
|
|
103
|
-
| `.dove-active-task.json` | Currently selected ClickUp task | Dashboard only
|
|
127
|
+
| File | Purpose | Read By |
|
|
128
|
+
| ------------------------ | ------------------------------- | ------------------------------------ |
|
|
129
|
+
| `.dove-update-sets.json` | Scope-to-update-set mapping | Dashboard, `dove push`, `dove watch` |
|
|
130
|
+
| `.dove-active-task.json` | Currently selected ClickUp task | Dashboard only |
|
|
104
131
|
|
|
105
132
|
Both files are written to the project root (CWD). Add them to `.gitignore`.
|
|
106
133
|
|
|
@@ -114,3 +141,7 @@ The dashboard uses two ServiceNow APIs:
|
|
|
114
141
|
|
|
115
142
|
- **Table API** (`/api/now/table/`) — standard CRUD for update sets and scopes
|
|
116
143
|
- **Dovetail Scripted REST API** (`/api/cadso/dovetail/changeUpdateSet`) — switches the active update set on the instance after activation
|
|
144
|
+
|
|
145
|
+
## Git Dependency (Start Task only)
|
|
146
|
+
|
|
147
|
+
The branch-creation step of Start Task shells out to the `git` CLI (`git config user.name`, `git checkout -b`/`git checkout`) in the dashboard process's `cwd`. Everything else in the dashboard works without git — this dependency only applies if you use Start Task. Run `dove dashboard` from inside the git checkout you want the branch cut in.
|