@blastin-dev/clocktopus-cli 0.2.0 → 0.3.0

package/dist/src/commands/agent/doctor.js

@@ -3,81 +3,140 @@ import { isAfter, parseISO } from "date-fns";
 import { findShadowedExports, maskToken, resolveAgentCredentials, } from "../../lib/agent-config.js";
 import { readLastRun } from "../../lib/agent-hook-state.js";
 import { verifyReceiver } from "../../lib/agent-receiver.js";
-import { readInstalledTelemetry, SettingsParseError, TELEMETRY_ENV_KEYS, } from "../../lib/claude-settings.js";
+import { isConfigParseError, surveyAgents } from "../../lib/agents.js";
 import { isLoggedIn } from "../../lib/config.js";
 import { formatAgo } from "../../lib/format.js";
 import { fetchRepoStatus, repoChecks } from "../../lib/repo-guidance.js";
 export async function doctorCommand() {
+    const sections = [];
+    sections.push({
+        title: "This machine",
+        checks: [
+            {
+                label: "Logged in",
+                ok: isLoggedIn(),
+                detail: isLoggedIn() ? "yes" : "no",
+                fix: "clocktopus login",
+            },
+        ],
+    });
+    const survey = surveyAgents();
+    const relevant = survey.filter((entry) => entry.installed || entry.configured || entry.unreadable);
+    if (relevant.length === 0) {
+        sections[0].checks.push({
+            label: "Agents",
+            ok: false,
+            detail: `none of ${survey.map((e) => e.agent.binary).join(", ")} found on PATH`,
+            fix: "Install a supported agent, then run 'clocktopus agent setup'",
+        });
+    }
+    for (const entry of relevant) {
+        sections.push({
+            title: `${entry.agent.label}${entry.version ? ` ${entry.version}` : ""}`,
+            checks: await agentChecks(entry),
+        });
+    }
+    // Past this point the pipeline works; these decide whether what it carries can be turned
+    // into a number. Both are server-side facts about the repository, not about any one agent.
+    const tail = [];
+    const repoStatus = await fetchRepoStatus();
+    if (repoStatus)
+        tail.push(...repoChecks(repoStatus));
+    tail.push(checkLastHookRun());
+    sections.push({ title: "Repository and delivery", checks: tail });
+    report(sections);
+}
+async function agentChecks(entry) {
     const checks = [];
+    if (entry.unreadable) {
+        return [
+            {
+                label: "Config",
+                ok: false,
+                detail: "could not be parsed",
+                fix: entry.unreadable,
+            },
+        ];
+    }
     checks.push({
-        label: "Logged in",
-        ok: isLoggedIn(),
-        detail: isLoggedIn() ? "yes" : "no",
-        fix: "clocktopus login",
+        label: "Installed",
+        ok: entry.installed ? true : "warn",
+        detail: entry.installed
+            ? `${entry.agent.binary} ${entry.version ?? ""}`.trim()
+            : `${entry.agent.binary} is not on PATH`,
+        fix: "Config here is harmless, but nothing will report until it is installed",
     });
-    let installed = null;
+    let state;
     try {
-        installed = readInstalledTelemetry();
-        checks.push({
-            label: "settings.json",
-            ok: installed.exists,
-            detail: installed.exists
-                ? `${installed.path} (modified ${formatAgo(installed.modifiedAt?.toISOString() ?? null)})`
-                : `${installed.path} does not exist`,
-            fix: "clocktopus agent setup",
-        });
+        state = entry.agent.read();
     }
     catch (error) {
-        if (error instanceof SettingsParseError) {
-            checks.push({
-                label: "settings.json",
+        if (!isConfigParseError(error))
+            throw error;
+        return [
+            {
+                label: "Config",
                 ok: false,
-                detail: "is not valid JSON",
-                fix: "Fix or move the file, then run 'clocktopus agent setup'",
-            });
-            report(checks);
-            return;
-        }
-        throw error;
+                detail: "could not be parsed",
+                fix: error.message,
+            },
+        ];
     }
-    const missingEnv = TELEMETRY_ENV_KEYS.filter((key) => !installed?.env[key]);
     checks.push({
-        label: "Exporter config",
-        ok: missingEnv.length === 0,
-        detail: missingEnv.length === 0
-            ? `all ${TELEMETRY_ENV_KEYS.length} variables set`
-            : // Listing nine names when none are set is noise; the useful
-                // signal there is simply "nothing is configured".
-                missingEnv.length === TELEMETRY_ENV_KEYS.length
-                    ? "not configured in settings.json"
-                    : `missing ${missingEnv.join(", ")}`,
-        fix: "clocktopus agent setup",
+        label: "Config",
+        ok: state.token !== null,
+        detail: state.token !== null
+            ? `${state.paths.join(", ")} (modified ${formatAgo(state.modifiedAt?.toISOString() ?? null)})`
+            : `not configured in ${state.paths.join(", ")}`,
+        fix: `clocktopus agent setup --agent ${entry.agent.id}`,
     });
-    // Both events are required, and for different reasons: SessionStart is the
-    // only source of the *before* SHA and of `cwd`, SessionEnd is the only
-    // source of the exact commit list. One without the other silently
-    // degrades what can be attributed.
-    const hookStart = installed.hookCommands.SessionStart;
-    const hookEnd = installed.hookCommands.SessionEnd;
+    // Both events are required, for different reasons: SessionStart is the only source of the
+    // *before* SHA and of `cwd`, SessionEnd the only source of the exact commit list. One
+    // without the other silently degrades what can be attributed.
+    const hookStart = state.hookCommands.SessionStart;
+    const hookEnd = state.hookCommands.SessionEnd;
     checks.push({
         label: "Hooks installed",
         ok: Boolean(hookStart && hookEnd),
         detail: hookStart && hookEnd
             ? `SessionStart, SessionEnd → ${hookStart}`
-            : `missing ${[!hookStart && "SessionStart", !hookEnd && "SessionEnd"].filter(Boolean).join(", ")}`,
-        fix: "clocktopus agent setup",
+            : `missing ${[!hookStart && "SessionStart", !hookEnd && "SessionEnd"]
+                .filter(Boolean)
+                .join(", ")}`,
+        fix: `clocktopus agent setup --agent ${entry.agent.id}`,
     });
-    if (hookStart) {
+    if (hookStart)
         checks.push(checkHookRuns(hookStart));
+    // A warning, not a failure: a plugin from an older generation still reports. What it does
+    // not have is whatever the newer one fixed, and nothing else in this report would say so
+    // — the token is valid, the hook resolves, the receiver answers.
+    const stale = entry.agent.staleReason?.() ?? null;
+    if (stale) {
+        checks.push({
+            label: "Generated config",
+            ok: "warn",
+            detail: stale,
+            fix: `clocktopus agent setup --agent ${entry.agent.id}`,
+        });
     }
-    const credentials = resolveAgentCredentials();
+    for (const action of entry.agent.pendingActions()) {
+        checks.push({
+            label: "Hooks enabled",
+            ok: "warn",
+            detail: "installed but not yet approved by the agent",
+            fix: action,
+        });
+    }
+    const credentials = resolveAgentCredentials(entry.agent.id);
     checks.push({
         label: "Token in force",
         ok: credentials.token !== null,
         detail: credentials.token
-            ? `${maskToken(credentials.token)} (from ${credentials.tokenSource})`
+            ? `${maskToken(credentials.token)} (from ${credentials.tokenSource === "settings"
+                ? credentials.sourcePath
+                : credentials.tokenSource})`
             : "none resolved",
-        fix: "clocktopus agent setup",
+        fix: `clocktopus agent setup --agent ${entry.agent.id}`,
     });
     if (credentials.token && credentials.endpoint) {
         const check = await verifyReceiver(credentials.endpoint, credentials.token);
@@ -96,27 +155,20 @@ export async function doctorCommand() {
                 : "clocktopus agent setup --force  (mints a replacement token)",
         });
     }
-    // Past this point the pipeline works; these two decide whether what it
-    // carries can be turned into a number. Both are server-side facts about
-    // the repository, not about this machine.
-    const repoStatus = await fetchRepoStatus();
-    if (repoStatus)
-        checks.push(...repoChecks(repoStatus));
-    checks.push(checkShadowedExports());
-    checks.push(checkRestartNeeded(installed.modifiedAt));
-    checks.push(checkLastHookRun());
-    report(checks);
+    // Only Claude Code applies config `env` over the inherited environment, so only it can be
+    // shadowed by a shell export.
+    if (entry.agent.id === "claude")
+        checks.push(checkShadowedExports());
+    checks.push(checkRestartNeeded(entry, state.modifiedAt));
+    return checks;
 }
-/**
- * Runs the installed hook command with empty stdin.
- *
- * This is a genuine no-op — the hook returns immediately when stdin carries
- * no payload — so it sends nothing and records nothing, while still proving
- * the exact command line in settings.json resolves and executes. Worth
- * checking directly: hooks run under a shell whose PATH may differ from the
- * interactive one, and a command that fails to resolve there fails
- * silently, costing every session its repository context.
- */
+// Runs the installed hook command with empty stdin.
+//
+// A genuine no-op — the hook returns immediately when stdin carries no payload — so it
+// sends and records nothing while still proving the exact command line in the agent's
+// config resolves and executes. Worth checking directly: hooks run under a shell whose
+// PATH may differ from the interactive one, and a command that fails to resolve there
+// fails silently, costing every session its repository context.
 function checkHookRuns(command) {
     try {
         execSync(command, {
@@ -159,31 +211,34 @@ function checkShadowedExports() {
             "      disagree is how spend lands on the wrong account.",
     };
 }
-/**
- * Did the configuration change after the last session used it?
- *
- * The exporter and the hook both read their configuration once, at process
- * start, so a session already open when setup ran is still using the old
- * values. This is the most common reason a correct configuration looks dead.
- */
-function checkRestartNeeded(settingsModifiedAt) {
+// Did the configuration change after the last session used it?
+//
+// The exporter and the hook both read their configuration once, at process start, so a
+// session already open when setup ran is still using the old values. This is the most
+// common reason a correct configuration looks dead.
+//
+// Scoped to the agent whose hook last ran: one receipt file is shared by all of them, and
+// comparing Claude Code's last run against Codex's config mtime would report a restart
+// that has already happened, or miss one that has not.
+function checkRestartNeeded(entry, configModifiedAt) {
     const lastRun = readLastRun();
-    if (!settingsModifiedAt || !lastRun?.at) {
+    const ranThisAgent = lastRun?.provider === entry.agent.provider;
+    if (!configModifiedAt || !lastRun?.at || !ranThisAgent) {
         return {
             label: "Restart",
             ok: "warn",
-            detail: "the hook has not run since this configuration was written",
-            fix: "Restart Claude Code, then run 'clocktopus agent status'",
+            detail: `${entry.agent.label} has not run a hook since this configuration was written`,
+            fix: `Restart ${entry.agent.label}, then run 'clocktopus agent status'`,
         };
     }
-    const ranAfterConfig = isAfter(parseISO(lastRun.at), settingsModifiedAt);
+    const ranAfterConfig = isAfter(parseISO(lastRun.at), configModifiedAt);
     return {
         label: "Restart",
         ok: ranAfterConfig ? true : "warn",
         detail: ranAfterConfig
             ? "a session has run since the last configuration change"
-            : "settings.json changed after the last session started",
-        fix: "Restart Claude Code so the exporter and hook pick up the new values",
+            : "the config changed after the last session started",
+        fix: `Restart ${entry.agent.label} so the exporter and hook pick up the new values`,
     };
 }
 function checkLastHookRun() {
@@ -192,36 +247,43 @@ function checkLastHookRun() {
         return {
             label: "Last hook run",
             ok: "warn",
-            detail: "no record — the hook has not run on this machine",
-            fix: "Restart Claude Code and start a session",
+            detail: "no record — no hook has run on this machine",
+            fix: "Restart your agent and start a session",
         };
     }
     const failed = lastRun.status === null ||
         lastRun.status === undefined ||
         lastRun.status < 200 ||
         lastRun.status >= 300;
+    const who = lastRun.provider ? ` (${lastRun.provider})` : "";
     return {
         label: "Last hook run",
         ok: !failed,
         detail: failed
-            ? `${formatAgo(lastRun.at)} — ${lastRun.status ? `HTTP ${lastRun.status}` : (lastRun.error ?? "no response")}`
-            : `${formatAgo(lastRun.at)} — HTTP ${lastRun.status}`,
+            ? `${formatAgo(lastRun.at)}${who} — ${lastRun.status ? `HTTP ${lastRun.status}` : (lastRun.error ?? "no response")}`
+            : `${formatAgo(lastRun.at)}${who} — HTTP ${lastRun.status}`,
         fix: lastRun.status === 401
             ? "clocktopus agent setup --force  (the token was rejected)"
             : "Check network access to the receiver",
     };
 }
-function report(checks) {
-    console.log("\nAgent telemetry diagnosis\n");
-    for (const check of checks) {
-        const symbol = check.ok === true ? "✓" : check.ok === "warn" ? "⚠" : "✗";
-        console.log(`  ${symbol} ${check.label.padEnd(18)}${check.detail}`);
-        if (check.ok !== true && check.fix) {
-            console.log(`    → ${check.fix}`);
+function report(sections) {
+    console.log("\nAgent telemetry diagnosis");
+    for (const section of sections) {
+        if (section.checks.length === 0)
+            continue;
+        console.log(`\n${section.title}\n`);
+        for (const check of section.checks) {
+            const symbol = check.ok === true ? "✓" : check.ok === "warn" ? "⚠" : "✗";
+            console.log(`  ${symbol} ${check.label.padEnd(18)}${check.detail}`);
+            if (check.ok !== true && check.fix) {
+                console.log(`    → ${check.fix}`);
+            }
         }
     }
-    const failures = checks.filter((check) => check.ok === false).length;
-    const warnings = checks.filter((check) => check.ok === "warn").length;
+    const all = sections.flatMap((section) => section.checks);
+    const failures = all.filter((check) => check.ok === false).length;
+    const warnings = all.filter((check) => check.ok === "warn").length;
     console.log("");
     if (failures === 0 && warnings === 0) {
         console.log("Everything checks out. 'clocktopus agent status' shows what has arrived.");

package/dist/src/commands/agent/hook.d.ts

@@ -1,2 +1,5 @@
-export declare function hookCommand(): Promise<void>;
+export declare function hookCommand(options: {
+    provider?: string;
+    detached?: boolean;
+}): Promise<void>;
 //# sourceMappingURL=hook.d.ts.map

package/dist/src/commands/agent/hook.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"hook.d.ts","sourceRoot":"","sources":["../../../../src/commands/agent/hook.ts"],"names":[],"mappings":"AAuRA,wBAAsB,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC,CAMjD"}
+{"version":3,"file":"hook.d.ts","sourceRoot":"","sources":["../../../../src/commands/agent/hook.ts"],"names":[],"mappings":"AAmcA,wBAAsB,WAAW,CAAC,OAAO,EAAE;IACzC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB,GAAG,OAAO,CAAC,IAAI,CAAC,CAYhB"}