@geneverse/workctl 0.2.5 → 0.2.10

package/README.md

@@ -1,339 +1,87 @@
 # workctl
 
-Deterministic internal developer workflows in one CLI. The Time Sync capability
-is available through `workctl jira`.
-
-```bash
-workctl jira sync
-workctl update
-workctl setup
-workctl jenkins job create --help
-workctl assistant status
-```
-
-The npm package contains the compiled CLI, this README, and the MIT license.
-Project planning and architecture notes live in the source repository and are
-not included in the published package.
-
-## jira capability
-
-Deterministic local CLI for synchronizing Kawari timesheets to Jira Cloud.
-No double-entry — scrape your timesheet, review what will be created, and
-approve once.
+`workctl` syncs Kawari timesheets to Jira Cloud worklogs.
 
 ## Quick Start
 
-**Prerequisites:** Node.js ≥22, a Jira Cloud API token, and access to your
+**Prerequisites:** Node.js >=22, a Jira Cloud API token, and access to your
 Kawari timesheet.
 
 ```bash
 npm install -g @geneverse/workctl
 workctl browsers install
 workctl setup
+workctl jira preview
+workctl jira sync
 ```
 
-The onboarding hub always lets you select setup-capable capabilities and
-requires at least one selection. jira is selected by default; compact
-onboarding asks only for Jira email and API token, supplies the company
-defaults, verifies the result, and writes a private user-global configuration
-file. Re-running setup skips configuration that is already valid and verifies
-it again.
+`preview` is read-only. Use it first to confirm what will be created in Jira.
+`sync` asks for approval before writing worklogs.
 
 ## Configuration
 
-Run `workctl jira configure` to review the current configuration and select
-only the sections you want to edit: Jira credentials, service defaults, or
-Link Status Audit. On macOS and Linux, configuration is stored at
-`~/.config/workctl/config.json`; on Windows, it is stored under
-`%APPDATA%\workctl\config.json`. POSIX directories and files use private
-permissions. The Jira token is stored as plain text in that file, so use
-workctl only on a trusted personal workstation.
+Run `workctl setup` for the normal first-time setup. It configures Jira sync,
+verifies the result, and writes a private user configuration file.
 
-| Config field | Environment override | Description |
-|---|---|---|
-| `jiraBaseUrl` | `JIRA_BASE_URL` | Jira Cloud HTTPS origin |
-| `jiraEmail` | `JIRA_EMAIL` | Your Jira account email |
-| `jiraApiToken` | `JIRA_API_TOKEN` | Jira Cloud API token ([create one here](https://id.atlassian.com/manage-profile/security/api-tokens)) |
-| `timesheetUrl` | `TIMESHEET_URL` | Full URL to the Kawari timesheet |
-| `timezone` | `TZ` | Must be `Asia/Bangkok` |
-| `linkAudit.projects` | — | Optional Jira project map with `doneStatuses` for `audit-links` |
+Use `workctl jira configure` later if you need to edit Jira credentials, service
+defaults, or other Jira sync settings.
 
-Real process environment variables override the config file field by field.
-workctl does not load `.env` files. `NO_COLOR=1` disables colored output.
+On macOS and Linux, configuration is stored at:
 
-Use `workctl jira config show` to inspect effective values and their source. The token
-is always redacted. Use `workctl jira doctor` to check permissions, Jira credentials,
-and the Playwright Chromium installation.
-
-## Commands
-
-```
-workctl jira sync    [--from YYYY-MM-DD] [--to YYYY-MM-DD] [--export csv|json]
-workctl jira preview [--from YYYY-MM-DD] [--to YYYY-MM-DD] [--export csv|json]
-workctl jira verify  [--from YYYY-MM-DD] [--to YYYY-MM-DD] [--export csv|json]
-workctl jira rollback [--from YYYY-MM-DD] [--to YYYY-MM-DD] [--issue KEY] [--dry-run]
-workctl jira audit-links [--from YYYY-MM-DD] [--to YYYY-MM-DD] [--export csv|json]
-workctl jira configure
-workctl jira config show
-workctl jira doctor
-workctl browsers install
-workctl update
+```text
+~/.config/workctl/config.json
 ```
 
-`workctl setup` selects, compactly configures, and verifies capabilities.
-`workctl jira configure` is the full editor for Jira-specific settings.
-
-| Command | Writes to Jira? | Purpose |
-|---|---|---|
-| `sync` | Yes (with approval) | Full pipeline: scrape, preview, approve, create, verify |
-| `preview` | No | Read-only: scrape and show what would happen |
-| `verify` | No | Compare eligible entries against existing tool-managed Jira worklogs |
-| `rollback` | Yes (typed approval) | Delete matching tool-managed worklogs and restore their time to Remaining Estimate |
-| `audit-links` | No | Audit linked issue statuses for Jira issues found in Kawari |
-| `browsers install` | No | Install the Playwright Chromium browser required by Kawari scraping |
-| `update` | No | Install the latest stable `@geneverse/workctl` release from npm after approval |
-
-### Rolling back a sync
-
-`workctl jira rollback` reads the selected Kawari entries and previews only Jira
-worklogs carrying matching `jlog:v1` Source Identities. The worklog must belong
-to the current Jira account. Type the displayed `delete N` phrase to proceed,
-or use `--dry-run` for a read-only check.
-
-Each deletion sends `adjustEstimate=auto`, so deleting a 2h worklog from an
-issue with 3h remaining restores Remaining Estimate to 5h. The Jira capability does not set
-Original Estimate or an absolute remaining value. Use repeatable
-`--issue OLD-1` options if a source entry's Jira key changed before rollback.
-Once deletion begins, the Jira capability writes a private JSON receipt under
-the local workctl data directory.
+On Windows, it is stored under:
 
-**Date range:** interactive `workctl jira sync`, `workctl jira rollback`, and `workctl jira audit-links`
-ask whether to use
-the current calendar month in `Asia/Bangkok` (showing its inclusive dates) or
-enter custom `From` and `To` dates. The current month is selected by default.
-`preview`, `verify`, and non-interactive commands continue to use the current
-month when dates are omitted. Explicit ranges bypass the prompt and must fall
-within one calendar month.
-
-### Auditing linked issue statuses
-
-`workctl jira audit-links` reads Jira keys from Kawari for the selected date range. It
-checks links only for source issues whose current status is configured as done
-for that Jira project. Every unique linked pair is reported as `Mismatch` or
-`Aligned`; completed source issues without links are reported as `No Links`.
-Link type and direction are displayed exactly as Jira returns them.
-
-Configure the Link Audit Scope with `workctl jira configure`. The wizard reads
-accessible projects and their statuses from Jira, then lets you select the
-Done Statuses for each project:
-
-```json
-{
-  "version": 1,
-  "capabilities": {
-    "jira": {
-      "linkAudit": {
-        "projects": {
-          "ABC": {
-            "doneStatuses": ["DONE", "READY TO DEPLOY"]
-          }
-        }
-      }
-    }
-  }
-}
+```text
+%APPDATA%\workctl\config.json
 ```
 
-Status comparison ignores surrounding whitespace and letter case. This scope
-does not restrict worklog sync, preview, or verification. Source issues outside
-the scope are skipped and summarized. Cross-project targets use their own
-configured Done Statuses; targets outside the scope are reported as
-`Not Configured`. Invalid Kawari entries and incomplete Jira responses still
-block the audit. Mismatches do not produce a failing exit code, and the command
-never changes Jira. Use `--export csv|json` to retain the complete report,
-including skipped sources and unconfigured targets.
-
-Interactive command output uses one guided terminal presentation for prompts,
-progress, results, and errors. `--help`, `--version`, and non-interactive output
-remain plain text for piping and automation.
-
-**Audit export** (`--export`): writes a timestamped CSV or JSON file to the
-local workctl data directory for your records.
-
-### Updating workctl
-
-Run `workctl update` to check the npm registry for `@geneverse/workctl`. If a
-newer stable version exists, workctl shows the target package, requires you to
-type `yes`, and runs `npm install --global @geneverse/workctl@<version>` without
-`sudo`. This command does not require Jira or Kawari configuration.
-
-You can also update directly with npm:
-
-```bash
-npm update -g @geneverse/workctl
-```
-
-## How It Works
-
-### Pipeline
-
-Each `sync` runs these steps:
-
-1. **Resolve date range** — interactive `sync` offers the displayed current
-   month or a custom range before opening Kawari
-2. **Scrape Kawari** — launches a browser; prompts for manual login if the
-   session expired
-3. **Classify** — each hours cell becomes a Timesheet Entry and is classified as:
-   - **Eligible** — exactly one Jira issue key, ready to sync
-   - **Unmapped** — no Jira key (e.g. internal meetings), skipped with a warning
-   - **Invalid** — bad data, multiple keys, or ambiguous identity
-4. **Read Jira and repair keys** — fetches existing worklogs to check for prior
-   syncs. If a Jira issue does not exist, an interactive run can replace that
-   key for the current batch and validate the replacement immediately.
-5. **Preview** — shows what will be created, skipped, or flagged as a conflict
-6. **Approve** — interactive confirmation before any writes
-7. **Create worklogs** — each new worklog gets a `jlog:v1:` marker in its
-   comment
-8. **Verify** — re-reads Jira to confirm every expected worklog exists
-
-`audit-links` shares date selection, Kawari classification, and temporary
-missing-key repair, but reads Jira link metadata through a separate read-only
-pipeline and never creates or transitions issues.
+The Jira API token is stored as plain text in that user config file. Use
+`workctl` only on a trusted personal workstation.
 
-### Safety Gates
+Environment variables override config file values field by field:
 
-- **Invalid entries** and **sync conflicts** (a previously-synced entry whose
-  values changed) block the entire batch. Nothing is written until all issues
-  are resolved.
-- A Jira key correction is a **Batch Override**. It applies to every affected
-  entry in the current command only; it does not edit Kawari or persist a local
-  mapping. Non-interactive runs fail with repair guidance instead.
-- The approval prompt shows exact counts and hours before you commit.
+| Config field | Environment override |
+|---|---|
+| `jiraBaseUrl` | `JIRA_BASE_URL` |
+| `jiraEmail` | `JIRA_EMAIL` |
+| `jiraApiToken` | `JIRA_API_TOKEN` |
+| `timesheetUrl` | `TIMESHEET_URL` |
+| `timezone` | `TZ` |
 
-### Idempotency
+`workctl` does not load `.env` files. Use `workctl jira config show` to inspect
+effective values and where they came from. The token is always redacted.
 
-Every worklog created by the Jira capability contains a legacy `jlog:v1:` marker — a base64url-encoded
-snapshot of the source entry. On re-runs, entries with a matching marker are
-skipped automatically. The marker survives local state loss and prevents
-duplicates across machines.
-
-## Example
-
-```
-$ workctl jira sync --from 2026-01-05 --to 2026-01-09
-
-──────────────────────────────────────────────────
-  Sync Batch:  2026-01-05 → 2026-01-09
-──────────────────────────────────────────────────
-
-╔═══════════════════════════════════════════════════════╗
-║                     PREVIEW                           ║
-╠═══════════════════════════════════════════════════════╣
-║  Create    3 worklog(s)                    12.0h      ║
-║  Skip      1 worklog(s)                     2.0h      ║
-╠═══════════════════════════════════════════════════════╣
-║  Total eligible                            14.0h      ║
-╚═══════════════════════════════════════════════════════╝
-
-Create 3 Jira worklog(s) totaling 12h? Yes
-
-◇ Ownership rechecked
-│ ╭───────────────────────────────────────────────────╮
-│ │ PROGRESS   DATE         ISSUE      TIME   STATUS  │
-│ ├───────────────────────────────────────────────────┤
-✓ │ 1/3        2026-01-07   PROJ-123   4h     Created │
-✓ │ 2/3        2026-01-08   PROJ-456   4h     Created │
-✓ │ 3/3        2026-01-09   PROJ-789   4h     Created │
-│ ╰───────────────────────────────────────────────────╯
-● Created 3 (12h) · Failed 0 (0h)
-
-Verified: 3 of 3 expected worklogs found on Jira.
-```
-
-## Development
-
-**Prerequisites:** Node.js ≥22, npm, a Jira Cloud API token, and access to the
-Kawari timesheet.
-
-For a fresh clone, bootstrap the project once. This installs npm dependencies
-and Playwright Chromium, then opens the onboarding hub:
-
-```bash
-npm run bootstrap
-```
-
-Run the CLI directly from TypeScript without building or linking it:
-
-```bash
-npm run dev -- jira sync
-npm run dev -- jira preview --from 2026-07-01 --to 2026-07-04
-```
+## Commands
 
-The compiled workflow remains available when testing the packaged executable:
+| Command | Purpose |
+|---|---|
+| `workctl setup` | Configure and verify Jira sync |
+| `workctl browsers install` | Install the Playwright Chromium browser used for Kawari scraping |
+| `workctl jira preview [--from YYYY-MM-DD] [--to YYYY-MM-DD]` | Show what would be synced without writing to Jira |
+| `workctl jira sync [--from YYYY-MM-DD] [--to YYYY-MM-DD]` | Scrape Kawari, preview, ask for approval, create Jira worklogs, and verify them |
+| `workctl jira doctor` | Check config, Jira credentials, permissions, and browser installation |
+| `workctl jira rollback [--from YYYY-MM-DD] [--to YYYY-MM-DD] [--issue KEY] [--dry-run]` | Delete matching tool-managed worklogs after typed approval |
+| `workctl update` | Update the global `@geneverse/workctl` install after approval |
 
-```bash
-npm ci
-npm run build
-npm link
-workctl jira sync
-```
+When dates are omitted, Jira sync uses the current calendar month in
+`Asia/Bangkok`. Explicit date ranges must stay within one calendar month.
 
-Development checks:
+## Updating
 
 ```bash
-npm test            # run tests (vitest)
-npm run typecheck   # type-check only, no emit
-npm run build       # compile TypeScript → dist/
-npm run test:package # pack and install the CLI in a temporary npm prefix
+workctl update
 ```
 
-### Releasing
-
-Start from a clean `main` branch, then run the development checks before
-creating a patch release:
+You can also update directly with npm:
 
 ```bash
-npm test
-npm run typecheck
-npm run build
-npm run test:package
-npm version patch -m "chore(release): %s"
-git push origin main --follow-tags
-```
-
-`npm version` updates `package.json` and `package-lock.json`, creates the
-release commit, and tags it as `v<version>`. The tag workflow publishes
-`@geneverse/workctl` to the npm registry with public access.
-
-### Project Structure
-
-```
-packages/
-├── cli/                    workctl composition root and binary
-└── capabilities/
-    ├── jira/               Kawari-to-Jira time synchronization
-    ├── jenkins/            Git-backed Jenkins definitions
-    └── assistant/          vendor CLI installation status
+npm update -g @geneverse/workctl
 ```
 
-Each capability owns its commands, dependencies, implementation, tests, and
-domain glossary. Capabilities are built into one release and cannot import one
-another. The CLI imports only their public entrypoints.
-
-### Local State
-
-Runtime data is user-global. On macOS and Linux it lives under
-`~/.local/share/workctl/jira/`; on Windows it lives under
-`%LOCALAPPDATA%\workctl\jira\`:
-
-- `browser-profile/` — persistent Playwright Chromium session
-- `audit-exports/` — timestamped CSV/JSON exports
-- `state/` — sync state
-
-Run `workctl setup` after installation; the first sync will require Kawari
-login.
-
-Uninstall the CLI with npm:
+## Uninstall
 
 ```bash
 npm uninstall -g @geneverse/workctl

package/dist/packages/cli/src/release-version.js

@@ -1,2 +1,2 @@
 // Generated from the root package.json by scripts/build.mjs.
-export const RELEASE_VERSION = "0.2.4";
+export const RELEASE_VERSION = "0.2.10";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@geneverse/workctl",
-  "version": "0.2.5",
+  "version": "0.2.10",
   "description": "Deterministic internal developer-workflow CLI",
   "type": "module",
   "license": "MIT",
@@ -34,7 +34,8 @@
     "node": ">=22"
   },
   "scripts": {
-    "bootstrap": "npm ci && playwright install chromium && npm run dev -- setup",
+    "bootstrap": "npm ci && npm run browsers:install && npm run dev -- setup",
+    "browsers:install": "playwright install --with-deps chromium",
     "build": "node scripts/build.mjs",
     "dev": "tsx packages/cli/src/bin.ts",
     "test": "vitest run",