logwork-cli 0.0.0-stage → 1.0.0

package/docs/recipes.md

@@ -0,0 +1,259 @@
+# Quick Recipes
+
+These recipes cover the common end-user paths. Credentials are entered only in Terminal, never in MCP prompts or AI chat.
+
+## Log Resource Optimiser Only
+
+Terminal:
+
+```bash
+logwork
+```
+
+Then run `/logwork ro`, choose a date and project, and enter tasks as `+<hours> <worklog task> | <description>`. The part before `|` must be a Resource Optimiser worklog task (for example `Feature Development`); the part after `|` is the description saved on the entry:
+
+```text
++2 Feature Development | Maintenance mode management (SCB-213)
++1 Feature Development | Update system page
+```
+
+Review the preview and approve the Resource Optimiser apply.
+
+MCP prompt:
+
+```text
+Preview this Resource Optimiser logwork. Show the project and totals, then ask before applying:
+Monday, 01 Jun 2026
++2 Feature Development | Maintenance mode management (SCB-213)
+```
+
+The assistant calls `log_work` with the text to preview. Only after you approve does it call `log_work` again with the returned `batchId` and `confirm: true`.
+
+For a single entry today from the terminal, you can also run `logwork quick -m "Maintenance mode management (SCB-213)"`.
+
+If you do not know the worklog task names, ask:
+
+```text
+List the Resource Optimiser worklog tasks for my booked project today, then log 2h for SCB-213 "maintenance mode management" with a proper description. Preview first.
+```
+
+The assistant uses `list_projects` and `list_tasks`, writes `+2 <task> | <description>`, and previews. If you write lines without `|`, the assistant can pass `defaultWorklogTask` (for example `Feature Development`) so each line becomes the description.
+
+## Edit Existing Resource Optimiser Logwork
+
+Find the RO logwork ID with `logwork query this-week`, `/query this-week`, or by asking the assistant to call `get_logwork`. Then use Terminal:
+
+```bash
+logwork edit 304032 --hours 0.5
+logwork edit 304032 --desc "Fix date picker timezone (SAP-42)"
+logwork edit 304032 --task "Bug Fix" --type correct
+```
+
+Or ask MCP:
+
+```text
+Preview changing RO logwork 304032 to 0.5 hours with description "Fix date picker timezone (SAP-42)". Keep project, date, and worklog task unchanged, then ask before applying.
+```
+
+The assistant calls `edit_entry` to preview and presents the diff. Only after you approve does it call `edit_entry` again with the `previewId` and `confirm: true`.
+
+Apply replaces the entry: it creates the corrected entry, then deletes the original, so the entry gets a new id. If the delete fails, the new entry is rolled back.
+
+The edit is blocked when the original entry:
+- changed after the preview,
+- is rejected (use `resubmit_entry` instead),
+- is on a locked day, or
+- was created by Jira.
+
+## Log Jira Only
+
+Authenticate once:
+
+```bash
+logwork login jira
+```
+
+Run `logwork`, then `/logwork jira`. Every task needs exactly one Jira issue key:
+
+```text
++2 Feature Development | Maintenance mode management (SCB-213)
++1 Bug Fix | Fix deployment regression (SCB-214)
+```
+
+The preview shows issue summary/status, duplicate state, configured started time, duration, and final comment. The assistant equivalent is `log_jira_work`: a preview call, then a call with `batchId` and `confirm: true` after approval.
+
+## Log Both
+
+Run `logwork`, then `/logwork both`. Use the same date and tasks for both targets:
+
+```text
++2 Feature Development | Maintenance mode management (SCB-213)
++1 Bug Fix | Fix deployment regression (SCB-214)
+```
+
+Resource Optimiser and Jira previews remain separate. Approve Resource Optimiser first and Jira second. The flow is not atomic, so a failure on one target does not roll back the other target.
+
+If RO cannot resolve a project, the terminal flow can rank RO memberships using the Jira project key/name and show a command such as:
+
+```text
+/map SCB 5234
+```
+
+Review the proposed project before confirming. Suggestions never write mappings automatically.
+
+## Change Jira Started Time
+
+macOS/Linux shell:
+
+```bash
+export LOGWORK_JIRA_STARTED_TIME=08:30
+export LOGWORK_TIMEZONE=Asia/Singapore
+logwork
+```
+
+Windows PowerShell:
+
+```powershell
+$env:LOGWORK_JIRA_STARTED_TIME = "08:30"
+$env:LOGWORK_TIMEZONE = "Asia/Singapore"
+logwork
+```
+
+Time must use 24-hour `HH:mm`; timezone must be an IANA name. The exact `started` value appears in Jira preview before approval.
+
+## Recover From Missing Jira Auth
+
+If preview says Jira auth is required:
+
+```bash
+logwork login jira
+logwork status jira
+```
+
+Paste the PAT only into the Terminal prompt, then rerun preview. Do not paste the PAT into MCP input or chat.
+
+## Handle Duplicate Jira Worklog
+
+Duplicate Jira worklogs block the entire Jira apply. Preview identifies duplicates by the `#lh:<hash>` marker or matching issue/date/duration/normalized task comment.
+
+Check Jira and the preview before continuing. If the work already exists, do not apply it again. If the task is genuinely different, change the task/date/duration as appropriate and rerun preview. There is no duplicate override.
+
+## Recover From npm E401
+
+An `E401` from `npm whoami` means the local npm login is missing, expired, or invalid:
+
+```bash
+npm logout --registry=https://registry.npmjs.org/
+npm login --registry=https://registry.npmjs.org/
+npm whoami
+```
+
+Before publishing, run:
+
+```bash
+logwork release doctor --full
+```
+
+Do not paste npm passwords, tokens, or OTP values into chat.
+
+## Inspect Apply History
+
+All recent targets:
+
+```bash
+logwork history
+```
+
+Jira only, last 10:
+
+```bash
+logwork history --target jira --limit 10
+```
+
+Combined Both sessions:
+
+```bash
+logwork history --target both
+```
+
+Inside the terminal UI, use `/history`, `/history ro`, `/history jira`, or `/history both`. With MCP, ask the assistant to use `get_history`.
+
+## Check And Install An Update
+
+Terminal check:
+
+```bash
+logwork update check
+```
+
+Terminal install with confirmation:
+
+```bash
+logwork update install
+```
+
+MCP prompt:
+
+```text
+Check whether logwork-cli has an update. Show me the current and latest versions, and ask before installing anything.
+```
+
+The assistant calls `update` with `action: "check"`. After approval, it calls `update` with `action: "install"`, the exact version, and `confirm: true`. Restart or reload the IDE MCP connection after the update completes.
+
+## Enable A Native Weekday Reminder
+
+Default Both reminder at 17:00:
+
+```bash
+logwork reminder enable
+```
+
+RO-only reminder at 18:00:
+
+```bash
+logwork reminder enable --time 18:00 --target ro
+```
+
+Send a sample notification and inspect scheduler status:
+
+```bash
+logwork reminder test
+logwork reminder status
+```
+
+MCP prompt:
+
+```text
+Enable a Both logwork reminder at 17:00 on weekdays. Explain the OS schedule and ask for approval before changing anything.
+```
+
+The assistant calls `reminder` with `action: "enable"` and `confirm: true` after approval. The notification remains silent when enabled checks are complete. Disable and remove the OS schedule with `logwork reminder disable`.
+
+## Reconcile RO And Jira
+
+Terminal summary:
+
+```bash
+logwork reconcile this-week
+```
+
+Machine-readable output:
+
+```bash
+logwork reconcile last-month --json
+```
+
+Inside `logwork`:
+
+```text
+/reconcile
+/reconcile this-week
+```
+
+MCP prompt:
+
+```text
+Compare my RO and Jira worklogs for this week. Explain each mismatch and do not apply corrections.
+```
+
+The assistant calls `reconcile`. When a correction is needed, it previews with `log_work`, `edit_entry` or `log_jira_work` and asks for target-specific approval before applying.

package/docs/security.md

@@ -0,0 +1,151 @@
+# Security And Auth
+
+logwork-cli does not accept or store Bearer tokens in config files. Resource Optimiser login and Jira PAT login both run in Terminal.
+
+## Auth Setup
+
+Start login:
+
+```bash
+logwork login
+```
+
+What happens:
+
+1. The helper creates a fresh Keycloak authorization request.
+2. You enter Resource Optimiser email and password in Terminal.
+3. You choose the 2FA device in Terminal.
+4. You enter the 2FA code in Terminal.
+5. The helper exchanges the Keycloak authorization code.
+6. The helper calls Resource Optimiser `signinKeyCloak`.
+7. The helper stores the Resource Optimiser access/refresh token session in the OS credential store.
+
+Check auth status without printing the token:
+
+```bash
+logwork status
+```
+
+Delete the stored token:
+
+```bash
+logwork logout
+```
+
+## Auth Notes
+
+- Password and 2FA are never accepted through MCP tool inputs or AI chat.
+- Password and 2FA are never stored.
+- Keycloak URLs contain dynamic `state`, `nonce`, `execution`, and `tab_id` values. Do not hardcode or paste them into config.
+- Keycloak access tokens are intermediate only and are not stored.
+- Only the final Resource Optimiser access/refresh token session is stored in the OS credential store: macOS Keychain on macOS, or Windows Credential Manager on Windows.
+- Auth does not open or read any browser profile.
+
+## Jira PAT Setup
+
+Jira self-hosted worklogs use a Jira Personal Access Token. The default Jira base URL is:
+
+```text
+https://jira-vnv.vinova.sg
+```
+
+Start Jira auth:
+
+```bash
+logwork login jira
+```
+
+Use a different Jira URL only when needed:
+
+```bash
+logwork login jira --base-url https://jira.example.com
+```
+
+What happens:
+
+1. You paste the Jira Personal Access Token in Terminal.
+2. The helper validates the token with `GET /rest/api/2/myself`.
+3. The helper stores `{ baseUrl, token, user }` in the OS credential store under service `logwork-cli`, account `jira`.
+
+Check or delete Jira auth without printing the token:
+
+```bash
+logwork status jira
+logwork logout jira
+```
+
+Sessions saved by `logwork-helper` (service `logwork-helper`) are read once and copied to service `logwork-cli`, so an upgrade does not require a new login. `logwork logout` removes both entries.
+
+Jira username/password login is not supported in MCP. Do not paste Jira passwords, PATs, cookies, or raw Jira auth logs into AI chat.
+
+## Auth Security Flow
+
+```mermaid
+flowchart TD
+  A["User runs logwork login"] --> B["Helper creates fresh Keycloak authorize request"]
+  B --> C["User enters email/password/device/2FA in terminal"]
+  C --> D["Helper exchanges Keycloak authorization code"]
+  D --> E["Helper calls Resource Optimiser signinKeyCloak"]
+  E --> F["Helper validates JWT expiry and user id"]
+  F --> G["Final RO access/refresh session saved to OS credential store"]
+  G --> H["MCP tools call Resource Optimiser APIs with the local credential session"]
+  L["User runs logwork login jira"] --> M["User pastes Jira PAT in terminal"]
+  M --> N["Helper validates GET /rest/api/2/myself"]
+  N --> O["Jira PAT session saved to OS credential store account jira"]
+  O --> P["MCP Jira tools call Jira REST APIs with the local PAT"]
+
+  I["MCP config"] -. "no token" .-> H
+  I -. "no Jira PAT" .-> P
+  J[".logwork.json"] -. "project mapping only" .-> H
+  K["AI chat / MCP args"] -. "no password or 2FA" .-> C
+  K -. "no Jira username/password/PAT" .-> M
+```
+
+## Stored Files
+
+The runtime and local state live in `~/.logwork-cli` (`%USERPROFILE%\.logwork-cli` on Windows). `LOGWORK_HOME` overrides this location, and the older `LOGWORK_HELPER_HOME` is still honored. When upgrading from `logwork-helper`, the state files below are copied once from `~/.logwork-helper`, which is left in place.
+
+| File | Content |
+| --- | --- |
+| `.logwork.json` | Project mappings: ticket prefixes and keywords. A repo-level `.logwork.json` (or a legacy `.logwork-helper.json`) holds project-scope mappings. |
+| `manual-drafts.json` | Terminal UI drafts. |
+| `apply-ledger.json` | Sanitized apply history. |
+| `update-state.json` | Update check cache: package name, latest SemVer, and check timestamp. Expires after 24 hours and contains no npm credentials. |
+| `reminder.json`, `reminder-state.json` | Reminder config: enabled state, local time, target and weekdays. Last-run state: sanitized timestamps and status summaries. |
+| `diagnostics/` | Sanitized diagnostics reports from `logwork doctor`. |
+
+The apply ledger stores the target, flow target, batch ID, timestamp, workspace path, entry metadata, and submitted/failed/blocked status. It does not store credentials, cookies, or raw API responses, and token-like error text is redacted before writing.
+
+The macOS launch agent and Windows scheduled task contain only fixed Node and script paths (`bin/logwork.mjs reminder run`). They never contain RO tokens, Jira PATs, passwords, or API responses.
+
+## Safety Model
+
+**Where secrets are never stored**
+- Tokens are not stored in MCP config or in `.logwork.json`.
+- The email address may be remembered in the OS credential store to prefill the next login.
+
+**How MCP writes are gated**
+- Every MCP write is two calls to the same tool. The first call, without `confirm`, returns a cached preview with a `batchId` or `previewId`. The second call must pass that id with `confirm: true`, which the assistant sends only after explicit approval.
+- The apply call writes the cached preview as-is. It rejects content fields such as `text` or `hours`, so nothing can be changed after approval without a new preview.
+- `edit_entry` preserves the project and date. It rejects entries that are Jira-created, rejected, or on a locked day, and stale-checks the original entry.
+- `edit_entry` apply replaces the entry: it creates the corrected entry first, then deletes the original, and rolls back the new entry if the delete fails. It then verifies the new entry.
+- `log_work` (Resource Optimiser) and `log_jira_work` (Jira) are separate flows. Applying Resource Optimiser logwork does not write Jira worklogs.
+- Jira duplicate detection is blocking and has no override option.
+
+**Read-only tools**
+- `get_logwork`, `list_projects`, `list_tasks`, `get_jira_issue`, `reconcile`, and `get_history` are read-only.
+- Reconciliation accepts preset periods only, filters Jira worklogs to the stored Jira user, and never applies its correction suggestions directly.
+
+**Updates**
+- `update` with `action: "check"` is read-only.
+- `update` with `action: "install"` requires `confirm: true`, re-checks npm latest, accepts only an exact SemVer, and cannot receive an arbitrary registry or shell command.
+- Installation preserves local files and OS credential-store entries. The current MCP process must be reconnected after a successful update.
+
+**Reminder**
+- `reminder` with `action: "status"` is read-only.
+- `enable`, `disable` and `test` require `confirm: true`. They never accept arbitrary scheduler commands, paths, JQL, or credentials.
+- The background reminder reads RO and Jira sessions from the OS credential store only when it runs. Notification and state text are sanitized and never include raw API responses.
+
+**Login and diagnostics**
+- `login` never accepts credentials. It only opens or explains a terminal login.
+- Diagnostics reports redact tokens, cookies, passwords, OTPs, auth codes, and raw HTML.

package/examples/mcp/antigravity.mcp_config.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "logwork": {
+      "command": "node",
+      "args": ["<home>/.logwork-cli/bin/logwork.mjs", "mcp"]
+    }
+  }
+}

package/examples/mcp/codex.config.toml

@@ -0,0 +1,5 @@
+[mcp_servers.logwork]
+command = "node"
+args = ["<home>/.logwork-cli/bin/logwork.mjs", "mcp"]
+startup_timeout_sec = 20
+tool_timeout_sec = 120

package/examples/mcp/copilot.mcp.json

@@ -0,0 +1,9 @@
+{
+  "servers": {
+    "logwork": {
+      "type": "stdio",
+      "command": "node",
+      "args": ["<home>/.logwork-cli/bin/logwork.mjs", "mcp"]
+    }
+  }
+}