@knpkv/jira-clockify 1.3.0 → 1.4.1

package/package.json

@@ -1,10 +1,25 @@
 {
   "name": "@knpkv/jira-clockify",
-  "version": "1.3.0",
+  "version": "1.4.1",
   "description": "TUI for Jira-Clockify time tracking, attachable to neovim",
   "license": "MIT",
   "author": "knpkv",
   "type": "module",
+  "main": "dist/src/index.js",
+  "exports": {
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "default": "./dist/src/index.js"
+    },
+    "./testing.js": {
+      "types": "./dist/src/testing/fakeHeadless.d.ts",
+      "default": "./dist/src/testing/fakeHeadless.js"
+    },
+    "./*.js": {
+      "types": "./dist/src/*.d.ts",
+      "default": "./dist/src/*.js"
+    }
+  },
   "bin": {
     "jcf": "dist/src/bin.js"
   },
@@ -18,30 +33,33 @@
     "skills"
   ],
   "dependencies": {
-    "@effect/atom-react": "4.0.0-rc.109",
-    "@effect/platform-node": "4.0.0-rc.109",
-    "@opentui/core": "0.5.1",
-    "@opentui/react": "0.5.1",
-    "effect": "4.0.0-rc.109",
-    "react": "^19.2.8",
-    "@knpkv/agent-skills": "^0.3.1",
-    "@knpkv/atlassian-common": "^1.4.1",
-    "@knpkv/clockify-api-client": "^1.1.1",
-    "@knpkv/jira-api-client": "^1.1.1",
-    "@knpkv/jira-cli": "^1.3.1"
+    "@effect/atom-react": "4.0.0",
+    "@effect/platform-node": "4.0.0",
+    "@opentui/core": "0.5.14",
+    "@opentui/react": "0.5.14",
+    "effect": "4.0.0",
+    "react": "^19.3.0",
+    "@knpkv/agent-skills": "^0.3.2",
+    "@knpkv/ai-claude": "^0.4.0",
+    "@knpkv/atlassian-common": "^1.6.0",
+    "@knpkv/ai-codex": "^0.5.0",
+    "@knpkv/clockify-api-client": "^2.0.0",
+    "@knpkv/jira-api-client": "^2.0.0",
+    "@knpkv/jira-cli": "^1.4.1"
   },
   "devDependencies": {
-    "@effect/vitest": "4.0.0-rc.109",
+    "@effect/vitest": "4.0.0",
     "@types/node": "latest",
-    "@types/react": "^19.2.18",
-    "tsx": "^4.23.12",
-    "vitest": "^4.1.10"
+    "@types/react": "^19.3.0",
+    "tsx": "^4.23.15",
+    "vitest": "^5.0.3"
   },
   "scripts": {
     "start": "tsx src/bin.ts",
     "build": "tsc -b && chmod +x dist/src/bin.js",
-    "check": "tsc -b tsconfig.json",
+    "check": "tsc -b tsconfig.json && tsc --noEmit -p test/tsconfig.json",
     "test": "vitest",
     "lint": "eslint \"{src,test}/**/*.{ts,tsx}\""
-  }
+  },
+  "types": "dist/src/index.d.ts"
 }

package/skills/jcf/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: jcf
-description: Use the @knpkv/jira-clockify CLI to track work across Jira and Clockify. Trigger when the user asks an agent to start, stop, discard, edit, inspect, or manually log time for Jira tickets; configure Jira OAuth or Clockify API access; list current Jira tickets; set default Clockify project, billable flag, or JQL; or launch the jcf TUI.
+description: Use the @knpkv/jira-clockify CLI to track work across Jira and Clockify. Trigger when the user asks an agent to start, stop, discard, edit, inspect, or manually log time for Jira tickets; reconcile Clockify against Jira or recover forgotten time from local Claude Code and Codex sessions; configure Jira OAuth or Clockify API access; list current Jira tickets; set default Clockify project, billable flag, or JQL; or launch the jcf TUI.
 ---
 
 # Jcf
@@ -38,6 +38,15 @@ jcf config set jql 'assignee = currentUser() AND status != Done ORDER BY updated
 jcf config reset
 ```
 
+Configure which directories' Claude Code and Codex sessions may become proposed worklogs:
+
+```bash
+jcf config set session-root ~/dev/work
+jcf config set session-root ~/dev/work --remove
+jcf config set session-ticket ~/dev/work/docs PROJ-42
+jcf config set idle-cap 300
+```
+
 ## Timer Commands
 
 Launch the TUI:
@@ -85,6 +94,87 @@ Edit the running timer:
 jcf timer edit
 ```
 
+## Reconcile Commands
+
+Both forms are remote write commands: they create Clockify entries and Jira worklogs. Never run
+either unattended. Confirm the window and the direction (or the agent) with the user first, and
+prefer the read-only forms below when gathering information.
+
+Compare the two sides and fill whichever is short:
+
+```bash
+jcf sync reconcile clockify-to-jira --day
+jcf sync reconcile jira-to-clockify --week
+jcf sync reconcile clockify-to-jira --since 2026-07-01 --until 2026-07-07
+```
+
+Recover time neither side recorded, using local Claude Code and Codex sessions as evidence:
+
+```bash
+jcf sync reconcile --agent claude --day
+jcf sync reconcile --agent claude --week
+jcf sync reconcile --agent claude --json
+jcf sync reconcile --agent claude --day --calendar
+```
+
+- `--agent` is a mode switch, not a direction. Passing both is a usage error.
+- `claude` is the only supported agent mode; `--agent codex` fails. That mode reads in-scope Claude Code
+  and Codex sessions as evidence.
+- `--agent claude --json` is the read-only form: it writes exactly one JSON value to stdout, sends
+  everything human-facing to stderr, and creates no Clockify entry or Jira worklog. Use it to
+  inspect proposals before asking the user which to accept.
+- Without `--json`, every row needs an interactive confirmation, so this form is unsuitable for
+  unattended use.
+- Nothing is proposed for a directory outside the configured session roots, and a day with a timer
+  still running is reported but never proposed. Stop the timer and re-run to log that day.
+- Every picker row names the issue summary and assignee; `--json` carries both as `summary` and
+  `assignee`. Rows are not listed above the picker — the picker rows _are_ the report.
+- Written entries carry the issue title and an agent-written sentence saying what was done, read off
+  the session prompts. Notes are asked for only about confirmed rows, and only when writing, so
+  `--json` never spends a call on one. A row still writes when no note can be produced.
+- `--calendar` adds an ASCII hour-by-hour grid of when the time was credited. `--json` carries the
+  same information as a `blocks` array per proposal, with `startMs`, `endMs` and credited `seconds`,
+  plus the issue `summary`. Sum `seconds`, not wall-clock bounds, for shared work.
+- In `--json`, `ownershipWithheld` keeps rows assigned to someone else or unassigned, with a
+  `reason`; `withheld` remains the separate confidence-floor list. Neither list is offered to write.
+- `--json` and `--calendar` are agent-mode flags; passing either without `--agent` is a usage error.
+- Only messages the user typed count towards time; the agent's own output, its tool results, and
+  prompts it sends its own subagents do not, so an unattended agent run credits at most the idle cap
+  rather than the hour it ran for.
+- If Jira cannot be read, the run fails rather than proposing time that may already be logged.
+- Time worked on several issues at once is split equally between them, so a row's credited total can
+  be lower than the clock ranges beneath it; the report names the active total and the shared amount.
+- Each proposal shows the attribution signal behind it (`branch`, `path`, `standing`, `agent`).
+  A branch name states intent, not fact: time spent on an unrelated fix while on a ticket branch is
+  credited to that branch's ticket, so review the signal before confirming.
+
+## Watch Command
+
+```bash
+jcf watch claude              # Runs until interrupted; writes as work settles
+jcf watch claude --dry-run    # Prints what it would write, writes nothing
+jcf watch claude --interval 60
+```
+
+- A long-running remote write command. Only start it when the user explicitly asks for live
+  tracking, and say that it will keep writing until they stop it. Do not start it to answer a
+  question — it never terminates on its own, so it cannot be used to gather information.
+- `--dry-run` is the read-only form, but it still runs forever. To inspect unlogged work, use
+  `jcf sync reconcile --agent claude --json` instead.
+- It writes only branch-, path-, and standing-attributed blocks. Time only a coding agent could
+  place is reported and left for `jcf sync reconcile --agent claude`.
+- It writes a block once it has been quiet for one idle cap, so work in progress is never written.
+  Nothing is written twice _on this machine_ — a proposal is always the gap the two sides still have,
+  and the lease keeps a second local watch out. Two machines watching one Clockify account can still
+  duplicate: see ADR-0007.
+- It covers time since it started, plus any stretch a previous watch reached but had not written —
+  it leaves a cursor, so a restart resumes rather than dropping the block. A first run reaches back
+  for nothing. Earlier work in the same day needs `jcf sync reconcile`.
+- Only one watch writes at a time, per machine. Starting a second one prints who holds the lease and
+  exits; do not start one to "check" on a running watch. After an ungraceful process death, verify no
+  watch remains before manually removing `~/.jcf/watch.lease`; the file is never auto-taken-over.
+- It stops itself if Jira rejects the login. Re-authenticate with `jcf auth jira login` and restart.
+
 ## Agent Workflow
 
 1. Run `jcf auth status` and `jcf timer status` before changing timer state.
@@ -92,3 +182,5 @@ jcf timer edit
 3. Verify the active Jira profile when the user names a Jira site/account or before posting worklogs; `atlassian profiles doctor` shows Jira Clockify as a consumer of the `jira-cli` auth store.
 4. Prefer explicit flags for non-interactive work: issue key, duration, date, time, project id, billable flag, and comment.
 5. If no timer is running, `jcf timer stop` may offer an interactive correction interval; use `jcf timer log` for deterministic manual logging.
+6. To find unlogged work, read `jcf sync reconcile --agent claude --json` first and report the
+   proposals to the user; only they should decide which rows to write.