kankaku-claude 0.2.1 → 0.2.2

package/CHANGELOG.md

@@ -8,6 +8,10 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ### 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

@@ -90,10 +90,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.2.2",
   "description": "Claude Code plugin that records how long the agent works on each user prompt, in kankaku's worklog format.",
   "type": "module",
   "files": [

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");
+}