kankaku-claude 0.2.1 → 0.9.0

package/.claude-plugin/plugin.json

@@ -1,11 +1,11 @@
 {
   "name": "kankaku",
   "description": "Records how long Claude Code works on each of your prompts: wall time, waiting time, work time and cost, per prompt, in kankaku's worklog format.",
-  "version": "0.1.0",
+  "version": "0.9.0",
   "author": {
     "name": "soyunninja"
   },
   "homepage": "https://kankaku.io",
-  "repository": "https://github.com/soyunninja/kankaku-claude",
+  "repository": "https://github.com/soyunninja/kankaku",
   "license": "MIT"
 }

package/CHANGELOG.md

@@ -4,10 +4,23 @@ All notable changes to this project are documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
+## 0.9.0 — 2026-09-28
+
+### Changed
+
+- Moved into the kankaku monorepo (`github.com/soyunninja/kankaku`,
+  `packages/claude`); versions are now lockstep with the other client
+  packages (`kankaku`, `kankaku-tui`). Depends on `kankaku ^0.9.0` (was
+  `^0.6.0`). No behaviour change.
+
 ## [Unreleased]
 
 ### Added
 
+- `/kankaku:doctor` and `node src/cli.ts doctor` provide a read-only local
+  diagnostic of plugin files, sessions, cost visibility and hub sync state,
+  without network requests or credential output.
+
 - `/kankaku:sync-status` and `/kankaku:sync-all` slash commands for local
   sync state inspection and full hub sync, respectively.
 

package/README.md

@@ -4,6 +4,9 @@ A [Claude Code](https://claude.com/claude-code) plugin that records how long
 Claude Code works on each of your prompts, in the same worklog format as the
 [kankaku](https://kankaku.io) pi extension.
 
+This package lives in the [kankaku monorepo](https://github.com/soyunninja/kankaku),
+under `packages/claude`.
+
 ## What it measures
 
 One record per user prompt, appended to `<KANKAKU_DIR>/worklog.jsonl`:
@@ -90,10 +93,15 @@ anything behind in whatever project happens to be open.
 - `/kankaku:sync-status` — inspects local pending counts and sync state
   (wraps `node src/cli.ts sync status`; no hub request or credentials required).
 - `/kankaku:sync-all` — requests a full sync (wraps `node src/cli.ts sync all`).
-
-The report, status, and setup subcommands are also available directly via
-`node src/cli.ts <report|status|setup>`; `report` accepts `--days N` and
-defaults to the last 7 days.
+- `/kankaku:doctor` — a read-only local diagnostic of plugin files, session and
+  cost visibility, and hub sync state (wraps `node src/cli.ts doctor`).
+
+The report, status, setup, and doctor subcommands are also available directly via
+`node src/cli.ts <report|status|setup|doctor>`; `report` accepts `--days N` and
+defaults to the last 7 days. Doctor reads only local data; it never contacts the
+hub or prints credentials. A missing cost file means cost has not been observed
+under the current `HOME` (it does not prove the statusline is misconfigured).
+Stored sync error details are withheld because they may contain sensitive data.
 
 ### Manual hub sync
 

package/commands/doctor.md

@@ -0,0 +1,9 @@
+---
+description: Show a read-only local kankaku installation and sync diagnostic
+allowed-tools: Bash(node:*)
+---
+
+Run the kankaku CLI doctor command and show its output to the user verbatim,
+inside a code block, with no summarizing or reformatting:
+
+!node "${CLAUDE_PLUGIN_ROOT}/src/cli.ts" doctor

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kankaku-claude",
-  "version": "0.2.1",
+  "version": "0.9.0",
   "description": "Claude Code plugin that records how long the agent works on each user prompt, in kankaku's worklog format.",
   "type": "module",
   "files": [
@@ -17,7 +17,8 @@
   "author": "soyunninja",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/soyunninja/kankaku-claude.git"
+    "url": "git+https://github.com/soyunninja/kankaku.git",
+    "directory": "packages/claude"
   },
   "scripts": {
     "test": "node --test tests/*.test.ts",
@@ -25,7 +26,7 @@
     "check": "npm run typecheck && npm test"
   },
   "dependencies": {
-    "kankaku": "^0.6.0"
+    "kankaku": "^0.9.0"
   },
   "devDependencies": {
     "@types/node": "^24.13.4",

package/src/cli-core.ts

@@ -5,6 +5,7 @@ import { readState } from "./session-state.ts";
 import { readCost } from "./cost-store.ts";
 import { formatReport } from "./report.ts";
 import { runSyncCli } from "./sync-cli.ts";
+import { runDoctor } from "./doctor.ts";
 
 export interface CliDeps {
   env: NodeJS.ProcessEnv;
@@ -22,7 +23,7 @@ export interface CliResult {
   stderr?: string;
 }
 
-const USAGE = "usage: node src/cli.ts <report|status|setup|sync> [--days N]\n";
+const USAGE = "usage: node src/cli.ts <report|status|setup|sync|doctor> [--days N]\n";
 
 /** CLI commands, resolved from `deps.cwd`. */
 export async function runCli(argv: string[], deps: CliDeps): Promise<CliResult> {
@@ -36,6 +37,8 @@ export async function runCli(argv: string[], deps: CliDeps): Promise<CliResult>
       return runSetup(deps);
     case "sync":
       return runSyncCli(rest, deps);
+    case "doctor":
+      return { stdout: runDoctor(deps), exitCode: 0 };
     default:
       return { stdout: "", exitCode: 1, stderr: USAGE };
   }

package/src/doctor.ts

@@ -0,0 +1,89 @@
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { JsonlWorkLog, SyncStateStore, computeSyncStatus, resolveHubCredentials } from "kankaku/hub";
+import type { CliDeps } from "./cli-core.ts";
+import { costDir } from "./cost-store.ts";
+import { listStateFiles, resolveKankakuDir } from "./paths.ts";
+import { readState } from "./session-state.ts";
+
+function metadata(file: string): Record<string, unknown> | undefined {
+  try {
+    const value: unknown = JSON.parse(readFileSync(file, "utf8"));
+    return value && typeof value === "object" && !Array.isArray(value) ? value as Record<string, unknown> : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function label(value: unknown): string {
+  // Metadata is local but not trusted: never echo arbitrary object or secret-looking fields.
+  return typeof value === "string" && /^[\w.-]+$/.test(value) ? value : "unavailable";
+}
+
+function syncWindowHours(env: NodeJS.ProcessEnv): number {
+  const hours = Number(env.KANKAKU_SYNC_WINDOW_HOURS);
+  return env.KANKAKU_SYNC_WINDOW_HOURS && Number.isFinite(hours) && hours > 0 ? hours : 24;
+}
+
+/** Read-only, local diagnostic. No sync runner or network client is reachable from this path. */
+export function runDoctor(deps: CliDeps): string {
+  const dir = resolveKankakuDir(deps.env.KANKAKU_DIR ?? ".kankaku", deps.cwd);
+  const pkg = metadata(join(deps.pluginRoot, "package.json"));
+  const plugin = metadata(join(deps.pluginRoot, ".claude-plugin", "plugin.json"));
+  const worklogPath = join(dir, "worklog.jsonl");
+  const log = new JsonlWorkLog(dir);
+  let recordCount: string;
+  try { recordCount = String(log.readAll().length); } catch { recordCount = "unreadable"; }
+  const states = listStateFiles(join(dir, "claude"));
+  let alive = 0;
+  let dead = 0;
+  let open = 0;
+  let unreadable = 0;
+  for (const file of states) {
+    const state = readState(file);
+    if (!state) { unreadable++; continue; }
+    if (state.pid > 0 && Number.isInteger(state.pid) && deps.isAlive(state.pid)) alive++;
+    else dead++;
+    if (state.promptOpen) open++;
+  }
+  let costsVisible = false;
+  try { costsVisible = readdirSync(costDir(deps.env)).some((file) => file.endsWith(".json")); } catch { /* missing or inaccessible */ }
+
+  const hub = resolveHubCredentials({ env: deps.env, homeDir: () => deps.env.HOME || homedir() });
+  const store = new SyncStateStore({ dir, pid: process.pid, now: deps.now });
+  const target = hub.credentials?.url ?? store.read()?.target ?? "";
+  const { state, pending, staleOutsideWindow } = computeSyncStatus(log, store, target, syncWindowHours(deps.env));
+  const hubState = hub.invalidReason ? "invalid URL" : hub.credentials ? "configured" : "unconfigured";
+  const commands = ["report", "status", "setup", "sync", "sync-status", "sync-all", "doctor"];
+  const present = commands.filter((name) => existsSync(join(deps.pluginRoot, "commands", `${name}.md`))).length;
+  const actions = ["/kankaku:status", "/kankaku:sync-status"];
+  if (!costsVisible) actions.unshift("/kankaku:setup (configure the statusline for cost)");
+  if (hubState === "invalid URL") actions.push("Check KANKAKU_PB_URL (HTTPS required)");
+  else if (hubState === "unconfigured") actions.push("Configure hub credentials to enable sync");
+
+  return [
+    "# kankaku doctor", "", "## Package / plugin",
+    `package version: ${label(pkg?.version)}`,
+    `plugin name: ${label(plugin?.name)}`,
+    `plugin version: ${label(plugin?.version)}`,
+    `pluginRoot: ${deps.pluginRoot}`,
+    "", "## Local files",
+    `KANKAKU_DIR: ${dir}`,
+    `worklog: ${existsSync(worklogPath) ? "present" : "absent"} (${recordCount} records)`,
+    `command files present: ${present}/${commands.length}`,
+    `hooks file present: ${existsSync(join(deps.pluginRoot, "hooks", "hooks.json")) ? "yes" : "no"}`,
+    "", "## Sessions / cost",
+    `active sessions: ${states.length}`,
+    `alive: ${alive}; dead: ${dead}; open prompts: ${open}; unreadable: ${unreadable}`,
+    `cost files visible: ${costsVisible ? "yes" : "no"} (current HOME)`,
+    "", "## Hub / sync",
+    `hub: ${hubState}`,
+    `pending: ${pending}`,
+    `staleOutsideWindow: ${staleOutsideWindow}`,
+    `syncedThrough: ${typeof state?.syncedThrough === "string" && /^\d{4}-\d\d-\d\dT\d\d:\d\d:\d\d\.\d{3}Z$/.test(state.syncedThrough) ? state.syncedThrough : "none"}`,
+    // Stored error messages can contain server responses or credentials; only show presence.
+    `last sync error: ${state?.lastError ? "present" : "none"}`,
+    "", "## Next actions", ...actions.map((action) => `- ${action}`), "",
+  ].join("\n");
+}

package/src/sync-cli.ts

@@ -106,7 +106,7 @@ export async function syncConfigured(
       await catalog.refresh();
       const snapshot = catalog.read();
       return new PocketBaseSink({
-        client, clients: snapshot?.clients ?? [], projects: snapshot?.projects ?? [],
+        client, clients: snapshot?.clients ?? [], projects: snapshot?.projects ?? [], tasks: snapshot?.tasks ?? [],
         machine: deps.env.KANKAKU_MACHINE || (deps.hostname ?? hostname)(),
         promptMode: promptMode(deps.env), syncRecords: deps.env.KANKAKU_SYNC_RECORDS !== "0",
         agent: "claude-code", plugin: "kankaku-claude", pluginVersion: packageVersion(),