litmus-cli 1.4.1 → 1.4.2

package/dist/commands/doctor.d.ts

@@ -0,0 +1,136 @@
+/**
+ * `litmus doctor` — candidate-run recovery for a live assessment.
+ *
+ * The background tracker `litmus init` starts is a detached process nothing
+ * supervises. Over a multi-day assessment the candidate's machine sleeps,
+ * crashes, and drops off Wi-Fi, and a tracker that dies stays dead silently;
+ * editor updates likewise clobber the AI-usage hooks. Doctor is the explicit
+ * repair command we point a candidate at when our monitoring sees their
+ * tracking go quiet: it diagnoses every piece of the local setup with
+ * pass/fail lines the candidate can paste back to us, repairs what it can
+ * through the SAME code paths init uses (tracker spawn, hook installers), and
+ * records what it did both locally (tracker.log, activity.jsonl) and
+ * server-side (a `doctor_run` activity event plus a CLI info event).
+ *
+ * Safety rules, in priority order:
+ *   - Never destructive: activity.jsonl is never truncated or rewritten,
+ *     events are uploaded verbatim, the flush cursor never moves backward,
+ *     and a revived tracker resumes the existing tamper-evidence chain
+ *     (see lib/chain.ts) instead of restarting it at genesis.
+ *   - Idempotent: on a healthy setup every check passes and nothing changes.
+ *   - No blind signals: doctor never SIGTERMs a pid it cannot verify is ours
+ *     (a stale pid may have been recycled by an unrelated process); it asks
+ *     the tracker to exit via the shutdown sentinel the tracker already polls.
+ *
+ * Exit code 0 when everything is healthy or was repaired; 1 when problems
+ * remain that need us (server unreachable, token rejected, restart failed).
+ */
+type CheckStatus = "ok" | "fixed" | "warn" | "fail";
+interface CheckResult {
+    /** Stable machine-readable name (goes into the uploaded doctor_run event). */
+    name: string;
+    status: CheckStatus;
+    /** Candidate-facing one-liner. */
+    detail: string;
+    /** Extra internals shown with --verbose (and always written to tracker.log). */
+    verbose?: string;
+    /**
+     * Don't print this line unless --verbose. For checks whose healthy/repaired
+     * states are our plumbing, not the candidate's business (capture internals,
+     * upload bookkeeping) — doctor should read like status/submit, not like a
+     * boot log. Quiet lines still land everywhere WE look: the doctor_run
+     * event, the diagnostic phone-home, and tracker.log. Never set on a line
+     * that asks the candidate to do something.
+     */
+    quiet?: boolean;
+}
+export declare const MAX_EVENTS_PER_BATCH = 500;
+export declare const MAX_BATCH_BYTES = 2000000;
+export interface ActivityScan {
+    totalBytes: number;
+    eventCount: number;
+    malformedCount: number;
+    aiPromptCount: number;
+    lastEventTs: string | null;
+    lastHeartbeatTs: string | null;
+    /**
+     * Timestamp of the newest LIVE-captured prompt (backfilled events excluded).
+     * This is where the automatic backfill window starts: everything before it
+     * was demonstrably captured by the live path, everything after it is the
+     * potential gap.
+     */
+    lastLiveAiPromptTs: string | null;
+}
+/** One pass over raw activity-log text: counts and latest timestamps. */
+export declare function scanActivityLog(text: string): ActivityScan;
+/**
+ * Byte offset of the first log line whose event timestamp is at or after
+ * `cutoffMs`. Lines without a parseable timestamp don't start the window.
+ * Returns the total byte length (i.e. "flush nothing") when no line qualifies.
+ */
+export declare function offsetForFirstEventAtOrAfter(text: string, cutoffMs: number): number;
+export interface FlushBatch {
+    events: unknown[];
+    /** Byte offset just past the last line included — the next cursor value. */
+    endOffset: number;
+}
+/**
+ * Slice the log from `startOffset` into upload batches. Events are passed
+ * through VERBATIM (chained watcher events stay verifiable); malformed lines
+ * are skipped but still advance the offset so they are never retried forever.
+ * `startOffset` must fall on a line boundary (it always does: every stored
+ * cursor value is a `FlushBatch.endOffset`); a mid-line offset skips the torn
+ * line rather than uploading half an event.
+ */
+export declare function planFlushBatches(text: string, startOffset: number): FlushBatch[];
+export declare function readUploadState(litmusDir: string): number | null;
+export declare function writeUploadState(litmusDir: string, flushFromBytes: number): void;
+/**
+ * Sanity-check the times the server sent before writing a rebuilt config.
+ * Returns a human-readable problem, or null when they are usable.
+ *
+ * The failure this guards against is real: the init route used to answer
+ * every re-fetch with `startedAt: now`, and a config rebuilt from that
+ * mid-session arms the client-side deadline (startedAt + timeLimit) hours
+ * late — the tracker then sleeps through the real cutoff. The route is fixed
+ * to return the candidate's true start, and this check refuses any regression
+ * of that class rather than writing a config that lies about time.
+ *
+ * A deadline already in the past is deliberately NOT refused: the deadline
+ * check reports it, and support flows still need the config on disk.
+ */
+export declare function validateRebuiltTimes(meta: {
+    startedAt: string;
+    deadline: string | null;
+    timeLimit: number | null;
+}, nowMs: number): string | null;
+/**
+ * The forensic snapshot we cannot get server-side (R5). The single most
+ * important bit is `hooks.claudeUserScope`: submit is what uninstalls the
+ * user-scope hook, so on a live assessment it discriminates "hook install
+ * worked, something later deleted the config" (true) from "install failed or
+ * fell back to project scope at init" (false) — the two surviving causes of
+ * a zero-prompts session. The mtimes date the damage; the registry shows what
+ * the shared logger could still resolve.
+ */
+export declare function collectDoctorDiagnostics(projectRoot: string, results: CheckResult[]): Record<string, unknown>;
+export interface DoctorOptions {
+    verbose?: boolean;
+    /** Assessment token, for rebuilding a missing/corrupted config (R1). */
+    token?: string;
+    /**
+     * Force prompt recovery over the whole assessment window (R4). Without it,
+     * recovery still runs automatically — but only when this run proved capture
+     * was broken, and only from the last live-captured prompt onward.
+     */
+    backfillPrompts?: boolean;
+    /** Override the recovery window start. */
+    since?: string;
+    /** Scan every Claude Code session on the machine, not just this folder's. */
+    allSessions?: boolean;
+    /** commander maps --no-backfill to false; default true (opts out of automatic recovery). */
+    backfill?: boolean;
+}
+export declare function runDoctor(opts: DoctorOptions): Promise<void>;
+export {};
+//# sourceMappingURL=doctor.d.ts.map

package/dist/commands/doctor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"doctor.d.ts","sourceRoot":"","sources":["../../src/commands/doctor.ts"],"names":[],"mappings":"AAoBA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAIH,KAAK,WAAW,GAAG,IAAI,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,CAAA;AAEnD,UAAU,WAAW;IACnB,8EAA8E;IAC9E,IAAI,EAAE,MAAM,CAAA;IACZ,MAAM,EAAE,WAAW,CAAA;IACnB,kCAAkC;IAClC,MAAM,EAAE,MAAM,CAAA;IACd,gFAAgF;IAChF,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB;;;;;;;OAOG;IACH,KAAK,CAAC,EAAE,OAAO,CAAA;CAChB;AAgCD,eAAO,MAAM,oBAAoB,MAAM,CAAA;AACvC,eAAO,MAAM,eAAe,UAAY,CAAA;AAKxC,MAAM,WAAW,YAAY;IAC3B,UAAU,EAAE,MAAM,CAAA;IAClB,UAAU,EAAE,MAAM,CAAA;IAClB,cAAc,EAAE,MAAM,CAAA;IACtB,aAAa,EAAE,MAAM,CAAA;IACrB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAA;IAC1B,eAAe,EAAE,MAAM,GAAG,IAAI,CAAA;IAC9B;;;;;OAKG;IACH,kBAAkB,EAAE,MAAM,GAAG,IAAI,CAAA;CAClC;AAED,yEAAyE;AACzE,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,YAAY,CAiC1D;AAED;;;;GAIG;AACH,wBAAgB,4BAA4B,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAgBnF;AAED,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,OAAO,EAAE,CAAA;IACjB,4EAA4E;IAC5E,SAAS,EAAE,MAAM,CAAA;CAClB;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,UAAU,EAAE,CAsChF;AAUD,wBAAgB,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAOhE;AAED,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,GAAG,IAAI,CAShF;AA4CD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,EAAE;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,EAC9E,KAAK,EAAE,MAAM,GACZ,MAAM,GAAG,IAAI,CASf;AA2ID;;;;;;;;GAQG;AACH,wBAAgB,wBAAwB,CACtC,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,WAAW,EAAE,GACrB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAyBzB;AAID,MAAM,WAAW,aAAa;IAC5B,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,wEAAwE;IACxE,KAAK,CAAC,EAAE,MAAM,CAAA;IACd;;;;OAIG;IACH,eAAe,CAAC,EAAE,OAAO,CAAA;IACzB,0CAA0C;IAC1C,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,6EAA6E;IAC7E,WAAW,CAAC,EAAE,OAAO,CAAA;IACrB,4FAA4F;IAC5F,QAAQ,CAAC,EAAE,OAAO,CAAA;CACnB;AAED,wBAAsB,SAAS,CAAC,IAAI,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC,CAqnBlE"}