logwork-cli 0.0.0-stage → 1.0.0

package/LICENSE

@@ -0,0 +1,11 @@
+Proprietary License
+
+Copyright (c) 2026 Truc Tran and contributors.
+All rights reserved.
+
+This project is proprietary and is not open source. Use, copying,
+modification, distribution, publication, sublicensing, or sale of this
+software or its documentation is permitted only with prior written permission
+from the copyright holder or under a separate written agreement.
+
+No license is granted by implication, estoppel, or otherwise.

package/README.md

@@ -1,3 +1,288 @@
-# Temporary Holding Version
+# logwork-cli
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[npm version](https://www.npmjs.com/package/logwork-cli)
+[license](LICENSE)
+
+Log work to Resource Optimiser (RO) and self-hosted Jira from the terminal, from an MCP server for AI IDEs, or from a terminal UI.
+
+One command, `logwork`, covers everything:
+
+- `logwork`: the terminal UI.
+- `logwork <command>`: one-shot commands such as `logwork query this-week` or `logwork edit 304032 --task "Bug Fix"`.
+- `logwork mcp`: the MCP server that Cursor, Codex, Google Antigravity, GitHub Copilot / VS Code and Claude Code connect to.
+
+Credentials stay local. Resource Optimiser passwords and 2FA codes, and Jira Personal Access Tokens, are entered in the terminal only. They never go into MCP config or AI chat.
+
+## Install
+
+Requirements: macOS or Windows 10/11, Node.js 22+, npm.
+
+```bash
+npm install -g logwork-cli
+logwork setup
+```
+
+`logwork setup` does the following:
+- installs the runtime to `~/.logwork-cli` (`%USERPROFILE%\.logwork-cli` on Windows),
+- links the `logwork` command,
+- offers to log in,
+- prints copy-ready MCP configs that use your real local path.
+
+## Upgrading from logwork-helper
+
+The package was renamed from `logwork-helper` to `logwork-cli`, and the `logwork-helper` command no longer exists. To upgrade:
+
+```bash
+npm install -g logwork-cli
+logwork setup
+```
+
+Most of the move is automatic:
+
+- **Old global package:** `logwork setup` removes the global `logwork-helper` package, so its `logwork` command does not conflict with the new one.
+- **Local state:** on the first run, settings, project mappings, drafts, apply history and the reminder config are copied from `~/.logwork-helper` to `~/.logwork-cli`. The old directory is left in place.
+- **Login sessions:** your RO and Jira sessions are copied from the old Keychain / Credential Manager entry (`logwork-helper`) to the new one (`logwork-cli`), so you do not need to log in again.
+- **Repo mappings:** a repo that has `.logwork-helper.json` keeps using it until a `.logwork.json` exists.
+- **Reminder:** an enabled reminder is re-registered by `logwork setup`, and the old OS schedule is removed.
+
+Two things you need to do yourself:
+
+- **IDE config:** replace the old `logwork-helper` MCP entry with the new `logwork` entry printed by `logwork setup` or `/mcp`.
+- **MCP tool names:** the tool names changed. See the [old → new tool name table](docs/mcp-setup.md#tool-name-changes-from-logwork-helper).
+
+## Log In
+
+```bash
+logwork login              # Resource Optimiser: email, password, 2FA in this terminal
+logwork login jira         # Jira Personal Access Token
+logwork login jira --base-url https://jira.example.com
+logwork status             # RO and Jira status, never prints tokens
+logwork logout [ro|jira]
+```
+
+Sessions are stored in macOS Keychain or Windows Credential Manager. The default Jira URL is `https://jira-vnv.vinova.sg`.
+
+## Commands
+
+```text
+logwork                 Open the terminal UI
+logwork query [period]  Booked vs logged hours with entry ids (today, yesterday, this-week, last-week, this-month, last-month)
+logwork quick [-m text] Log one entry for today with guided prompts
+logwork edit <id> ...   Change an existing RO entry (replaces it)
+logwork delete <id>     Delete a submitted or approved RO entry
+logwork reconcile       Compare RO and Jira hours by day (read-only)
+logwork history         Local apply history
+logwork login|logout|status [ro|jira]
+logwork setup           Install the runtime and print MCP configs
+logwork mcp             Run the MCP stdio server (used by IDE configs)
+logwork reminder ...    Weekday logwork reminder
+logwork update ...      Check for or install a new version
+logwork doctor          Write a sanitized diagnostics report
+```
+
+Add `--help` to any command for its options.
+
+## Logwork Line Format
+
+Every Resource Optimiser entry has a **worklog task** and a free-text **description**. The worklog task is an RO catalog item such as `Feature Development` or `Code Review & Refactoring`. Write each line as:
+
+```text
+Monday, 01 Jun 2026
++2 Feature Development | Implement maintenance mode management and status UI (SCB-213)
++1 Code Review & Refactoring | Review system page PR (SCB-214)
+```
+
+- **Before `|`:** the RO worklog task name, or `#<id>`. MCP clients can list valid names with `list_tasks`.
+- **After `|`:** the description saved on the RO entry. Jira uses it as the worklog comment.
+- **Lines without `|`:** these still work in two cases. If the whole text is a catalog task name, the entry is saved with no description and a warning. If the assistant passes `defaultWorklogTask`, that task is used and the text becomes the description.
+
+The default tasks shared by all projects are:
+
+| id | Task | type_of_work |
+|---|---|---|
+| 71 | Feature Development | create |
+| 74 | Bug Fix | correct |
+| 182 | Code Review & Refactoring | improve |
+| 79 | Deployment & Release | create |
+| 181 | Requirements & Design | create |
+| 183 | Testing Activities | create |
+| 111 | Other Activities | other |
+
+## API Notes
+
+- Read bookings: `GET /member-logtime/timesheet`
+- Read worklog tasks: `GET /logwork/tasks?project_id=<id>` and `GET /logwork/tasks/defaults?project_id=<id>`
+- Write an entry: `POST /logwork/entries`
+- Delete an entry: `DELETE /logwork/entries/:id`
+- Resubmit a rejected entry: `PATCH /logwork/entries/:id/resubmit`
+
+```json
+{
+  "worklog_task_id": 71,
+  "type_of_work": "create",
+  "effort_hours": 2,
+  "logdate": "2026-06-01",
+  "project_id": 720,
+  "description": "Implement maintenance mode management and status UI (SCB-213)"
+}
+```
+
+`project_id` is sent only when the worklog task is a shared default task.
+
+## Set Up MCP
+
+`logwork setup` prints the configs. You can also open the terminal UI with `logwork` and type `/mcp` (or `/mcp cursor`, `/mcp antigravity`, `/mcp copilot`, `/mcp claude-code`, `/mcp codex`).
+
+Every client runs the same thing, `node ~/.logwork-cli/bin/logwork.mjs mcp`, under the server name `logwork`:
+
+```json
+{
+  "mcpServers": {
+    "logwork": {
+      "command": "node",
+      "args": ["/Users/you/.logwork-cli/bin/logwork.mjs", "mcp"]
+    }
+  }
+}
+```
+
+For Claude Code, run:
+
+```bash
+claude mcp add --transport stdio logwork -- node ~/.logwork-cli/bin/logwork.mjs mcp
+```
+
+Restart or reload the IDE's MCP tools after saving.
+
+The server exposes 15 tools. It also sends `instructions` covering the approval rules, the line format and the recommended call order. Every write is **two calls to the same tool**:
+1. Call the tool without `confirm`. It returns a preview with a `batchId` or `previewId` and a summary.
+2. After the user approves, call the same tool again with only that id and `confirm: true`.
+
+See [docs/mcp-setup.md](docs/mcp-setup.md#exposed-tools) for the tool table.
+
+Verify from your assistant:
+
+```text
+Check my logwork for this week.
+```
+
+## Edit Existing RO Logwork
+
+Get the entry id from `logwork query` (or `get_logwork` in MCP), then:
+
+```bash
+logwork edit 304032 --hours 0.5
+logwork edit 304032 --desc "Fix date picker timezone (SAP-42)"
+logwork edit 304032 --task "Bug Fix" --desc "Fix date picker timezone (SAP-42)"
+logwork edit 304032 --task "#74" --type correct
+```
+
+Options:
+- `--hours`
+- `--task`: a worklog task from the project catalog, or `#<id>`.
+- `--desc`
+- `--type`: `create`, `correct`, `improve` or `other`. When the task changes and `--type` is omitted, the new task's catalog type is used.
+
+The long forms `--task-name` and `--description` also work. Project and date are always preserved.
+
+Resource Optimiser has no staff API for editing an entry; the edit endpoint is PM-only. So apply **replaces** the entry:
+
+1. It re-reads the entry and stops if the entry changed after the preview.
+2. It creates the corrected entry with `POST /logwork/entries`.
+3. It deletes the original with `DELETE /logwork/entries/:id`.
+4. It verifies the new entry.
+
+If the create fails, the original is untouched. If the delete fails, the new entry is deleted again, so nothing changes.
+
+Deleting on RO needs no approval, and a correctly formatted new entry is approved immediately, so the edit takes effect at once. The new entry gets a **new logwork id**.
+
+Some entries cannot be edited this way:
+- Only `submitted` or `approved` entries can be edited.
+- Rejected entries are fixed with `resubmit_entry`.
+- Entries on locked days, entries created by Jira, and entries owned by another user are blocked.
+
+The CLI previews the diff and asks for confirmation. Use `--yes` for an already reviewed non-interactive command.
+
+In the terminal UI: `/edit-logwork 304032 --task Bug Fix --desc Fix date picker timezone (SAP-42)`.
+
+In MCP, call `edit_entry` with `logworkId` and the changes, show the summary, then call `edit_entry` with `previewId` and `confirm: true`. The result returns `originalLogworkId` and `newLogworkId`.
+
+## Daily Use
+
+Ask your assistant:
+
+```text
+Check whether I have logged anything today.
+```
+
+```text
+Preview this logwork and ask for my approval before submitting:
+Monday, 01 Jun 2026
++2 Feature Development | Maintenance mode management and status UI (SCB-213)
+```
+
+```text
+Set up the SCB ticket mapping to project 2621A-SIT-HTML BUILDER-PRJ.
+```
+
+From the terminal:
+
+```bash
+logwork quick -m "Fix login bug (SCB-12)"   # one entry for today
+logwork                                      # terminal UI
+```
+
+In the terminal UI, `/logwork` opens a target picker. `/logwork ro` writes Resource Optimiser entries, `/logwork jira` writes Jira worklogs, and `/logwork both` previews and applies both with separate approvals. Type `/` to see every command, for example:
+- `/query this-week`
+- `/reconcile`
+- `/projects`
+- `/map SCB 5234`
+- `/history`
+- `/diagnostics`
+
+## Reminder
+
+```bash
+logwork reminder enable                 # 17:00 Monday-Friday, RO and Jira
+logwork reminder enable --time 18:00 --target ro
+logwork reminder test
+logwork reminder status
+logwork reminder disable
+```
+
+For Resource Optimiser, the reminder compares today's logged and booked hours. For Jira, it checks whether you have any worklog today. Complete days stay silent.
+
+macOS uses a user `launchd` agent (`sg.vinova.logwork-cli.reminder`) and Windows uses Task Scheduler (`Logwork Reminder`). Neither schedule stores credentials.
+
+## Reconcile RO And Jira
+
+```bash
+logwork reconcile this-week
+logwork reconcile last-month --json
+```
+
+This is read-only. It shows booked, RO and Jira hours by day and flags mismatches. A correction suggestion is included only when an RO entry contains exactly one Jira issue key. Applying a suggestion still goes through the normal preview and approval flow. MCP clients use the `reconcile` tool.
+
+## Update
+
+```bash
+logwork update check
+logwork update install
+```
+
+The terminal UI shows a short notice when a newer release is available. Checks are cached for 24 hours, and network errors never block logwork.
+
+Updating keeps OS credentials, project mappings, drafts and apply history. Reconnect MCP clients after an update.
+
+## More Docs
+
+- [Operations guide](docs/operations-guide.md): CLI/MCP feature map, RO/Jira/Both processing, mapping, reconciliation, history, reminders, updates and OS validation.
+- [MCP setup](docs/mcp-setup.md): client configs, the tool table, the old → new tool names, and common workflows.
+- [Security and auth](docs/security.md): Keycloak flow, Jira PAT flow, OS credential storage, stored files and the safety model.
+- [Advanced usage](docs/advanced.md): environment overrides, terminal UI details, troubleshooting and release checks.
+- [Quick recipes](docs/recipes.md): copy-ready workflows.
+- [Release checklist](RELEASE.md).
+
+## License
+
+This project is proprietary and not open source. See [LICENSE](LICENSE).

package/RELEASE.md

@@ -0,0 +1,89 @@
+# Release Checklist
+
+Use this checklist before publishing or tagging a production release.
+
+The complete end-user update and maintainer publish flows are documented in the [integrated operations guide](docs/operations-guide.md).
+
+## Version And Publish Sequence
+
+Publishing is automated. Pushing a version bump to `main` is the release:
+
+```bash
+# 1. Add "## [<version>] - <date>" with a ### Summary to CHANGELOG.md
+npm version <version> --no-git-tag-version
+npm run release:check
+git add -A
+git commit -m "release v<version>"
+git push origin main
+```
+
+After CI passes on `main`, `.github/workflows/release.yml`:
+
+1. reads the version from `package.json`;
+2. publishes `logwork-cli@<version>` to npm with provenance, using the `NPM_TOKEN` repository secret (skipped if already published);
+3. creates tag `v<version>` and a GitHub Release whose description is the `CHANGELOG.md` section (skipped if the tag exists).
+
+Check the result:
+
+```bash
+gh run list --workflow Release --limit 3
+npm view logwork-cli version
+gh release view v<version>
+```
+
+To retry a failed release, re-run the Release workflow (or `gh workflow run Release`). Use `minor` or `major` instead of `patch` when required by SemVer. Never reuse an already published version.
+
+### npm token
+
+The workflow uses the `NPM_TOKEN` repository secret (an npm automation or granular token with publish rights to `logwork-cli`). Set or rotate it with `gh secret set NPM_TOKEN --repo malcohelper/logwork-cli` and paste the token at the prompt. Never put the token in files, commits or command arguments. Preferred long term: configure npm Trusted Publishing for this repo and workflow on npmjs.com, then delete the secret; `npm publish --provenance` in the workflow already runs with `id-token: write`.
+
+## Required Gates
+
+Run the local release gate:
+
+```bash
+npm run release:check
+```
+
+Before publishing, run the release preflight doctor:
+
+```bash
+logwork release doctor --full
+```
+
+This checks version consistency, git cleanliness, npm auth, npm latest version, GitHub auth, tag/release state, local tarball artifacts, tests, audit, pack dry-run, and diff whitespace.
+
+The gate must pass all of the following:
+
+- `npm test`
+- `npm audit --omit=dev --audit-level=moderate`
+- `npm pack --dry-run`
+- `git diff --check`
+
+## Manual Verification
+
+- Install from the packed tarball in a temporary directory.
+- Run `logwork setup --no-login`.
+- Confirm the printed MCP config uses server name `logwork` and `node ~/.logwork-cli/bin/logwork.mjs mcp`.
+- Run `logwork --help` and `logwork --version`.
+- Run `logwork update check --force` against the published npm version.
+- Run `logwork mcp` through an MCP client smoke test and confirm it lists the 15 tools (`get_logwork`, `list_projects`, `list_tasks`, `log_work`, `edit_entry`, `resubmit_entry`, `delete_entry`, `log_jira_work`, `get_jira_issue`, `reconcile`, `get_history`, `map_project`, `login`, `reminder`, `update`).
+- Confirm the `update` tool requires `confirm: true` for `action: "install"`, and `reconcile` takes preset periods only with no credential or confirmation fields.
+- Run `logwork reconcile this-week` and confirm it reports RO/Jira daily totals without writing either system.
+- On a machine with an older `logwork-helper` install, confirm the first run copies state to `~/.logwork-cli` and `logwork status` shows the existing session without a new login.
+- Confirm the Windows CI job passes the dedicated `Verify Windows Credential Manager integration` step.
+- Run `logwork reminder test`, confirm a native notification appears, then verify `logwork reminder status` and clean up with `logwork reminder disable`.
+- Run `logwork status` and confirm no token is printed.
+
+## Safety Checks
+
+- Do not include Resource Optimiser tokens, `.env` files, diagnostics reports, or machine-specific MCP configs in the package.
+- Confirm `logwork --version` and the MCP server version match `package.json`.
+- Confirm `README.md` and onboarding output describe the same primary setup flow.
+- Confirm no untracked release artifacts are included except intentional documentation.
+
+## Rollback
+
+- Keep the previous npm package version available.
+- If a release introduces auth, MCP, or apply-path regressions, roll back by instructing users to install the previous known-good npm version.
+- Do not publish a replacement with the same version; publish a new patch version after the fix is verified.

package/bin/logwork.mjs

@@ -0,0 +1,101 @@
+#!/usr/bin/env node
+
+import { isMainModule } from '../lib/entrypoint.mjs';
+import { migrateLegacyHome } from '../lib/legacy-migration.mjs';
+import { readPackageVersion } from '../lib/package-info.mjs';
+
+// One entry point for every surface:
+//   logwork               -> terminal UI
+//   logwork <command> ... -> CLI command (loaded on demand, run in-process)
+//   logwork mcp           -> MCP stdio server for IDEs and agent CLIs
+export const COMMANDS = [
+  { name: 'query', usage: 'query [today|yesterday|this-week|last-week|this-month|last-month] [--json]', summary: 'Show booked vs logged hours with entry ids', load: () => import('../commands/query.mjs'), fn: 'run' },
+  { name: 'quick', usage: 'quick [-m "what you did"]', summary: 'Log one entry for today with guided prompts', load: () => import('../commands/quick.mjs'), fn: 'run' },
+  { name: 'edit', usage: 'edit <id> [--hours h] [--task name|#id] [--desc text] [--type type]', summary: 'Change an existing RO entry (replaces it)', load: () => import('../commands/edit.mjs'), fn: 'runRoEditCommand' },
+  { name: 'delete', usage: 'delete <id>', summary: 'Delete a submitted or approved RO entry', load: () => import('../commands/delete.mjs'), fn: 'runRoDeleteCommand' },
+  { name: 'reconcile', usage: 'reconcile [period] [--json]', summary: 'Compare RO and Jira hours by day', load: () => import('../commands/reconcile.mjs'), fn: 'runReconcileCommand' },
+  { name: 'history', usage: 'history [--target ro|jira|both] [--limit n] [--json]', summary: 'Show the local apply history', load: () => import('../commands/history.mjs'), fn: 'runHistoryCommand' },
+  { name: 'login', usage: 'login [ro|jira] [--base-url url]', summary: 'Log in to Resource Optimiser (default) or Jira', load: () => import('../commands/auth.mjs'), fn: 'runLogin' },
+  { name: 'logout', usage: 'logout [ro|jira]', summary: 'Remove the stored RO (default) or Jira session', load: () => import('../commands/auth.mjs'), fn: 'runLogout' },
+  { name: 'status', usage: 'status', summary: 'Show RO and Jira login status', load: () => import('../commands/auth.mjs'), fn: 'runStatus' },
+  { name: 'setup', usage: 'setup [--login|--no-login]', summary: 'Install the runtime and print MCP configs', load: () => import('../commands/setup.mjs'), fn: 'run' },
+  { name: 'mcp', usage: 'mcp', summary: 'Run the MCP stdio server (used by IDE configs)', load: () => import('../lib/mcp-server.mjs'), fn: 'startMcpServer' },
+  { name: 'reminder', usage: 'reminder enable|disable|status|test', summary: 'Manage the weekday logwork reminder', load: () => import('../commands/reminder.mjs'), fn: 'runReminderCli' },
+  { name: 'update', usage: 'update [check|install]', summary: 'Check for or install a new version', load: () => import('../commands/update.mjs'), fn: 'runUpdateCli' },
+  { name: 'doctor', usage: 'doctor', summary: 'Write a sanitized diagnostics report', load: () => import('../commands/doctor.mjs'), fn: 'run' },
+  { name: 'release', usage: 'release doctor [--full]', summary: 'Maintainers: check release readiness', load: () => import('../commands/release.mjs'), fn: 'run' }
+];
+
+export async function run(argv = process.argv.slice(2)) {
+  const [first, ...rest] = argv;
+
+  if (first === '--version' || first === '-v') {
+    console.log(readPackageVersion());
+    return 0;
+  }
+  if (first === '--help' || first === '-h' || first === 'help') {
+    console.log(formatHelp());
+    return 0;
+  }
+
+  if (first !== 'mcp') {
+    reportMigration(migrateLegacyHome());
+  }
+
+  if (!first || first.startsWith('-')) {
+    const tui = await import('../commands/tui.mjs');
+    return tui.run(argv);
+  }
+
+  const command = COMMANDS.find((item) => item.name === first);
+  if (!command) {
+    console.error(`Unknown command: ${first}\n`);
+    console.error(formatHelp());
+    return 1;
+  }
+
+  if (command.name === 'mcp') {
+    migrateLegacyHome();
+  }
+  const module = await command.load();
+  const result = await module[command.fn](rest);
+  return typeof result === 'number' ? result : undefined;
+}
+
+export function formatHelp() {
+  const width = Math.max(...COMMANDS.map((command) => command.name.length));
+  return `Usage:
+  logwork                 Open the terminal UI
+  logwork <command>       Run one command (add --help for its options)
+
+Commands:
+${COMMANDS.map((command) => `  ${command.name.padEnd(width)}  ${command.summary}`).join('\n')}
+
+Examples:
+  logwork setup
+  logwork login
+  logwork query this-week
+  logwork quick -m "Fix login bug (SCB-12)"
+  logwork edit 304032 --task "Bug Fix" --desc "Fix date picker timezone (SAP-42)"
+
+Options:
+  -h, --help     Show help
+  -v, --version  Show version`;
+}
+
+function reportMigration(result) {
+  if (result?.migrated) {
+    console.error(`Moved local settings from ${result.from} to ${result.to}.`);
+  }
+}
+
+if (isMainModule(import.meta.url)) {
+  run().then((code) => {
+    if (typeof code === 'number') {
+      process.exitCode = code;
+    }
+  }).catch((error) => {
+    console.error(error.message);
+    process.exitCode = 1;
+  });
+}