letmecode 0.1.6 → 0.1.8

package/README.md

@@ -4,6 +4,8 @@ Ussage:
 
 ```bash
 npx -y letmecode
+npx -y letmecode -- -h
+npx -y letmecode -- --log-to log.txt
 ```
 
 <img width="2308" height="1491" alt="image" src="https://github.com/user-attachments/assets/f3f52d79-00e3-4ff5-bf2f-65f8be632aaa" />

package/ink-app/dist/cli-options.js

@@ -0,0 +1,89 @@
+import fs from "node:fs";
+import path from "node:path";
+export function parseCliOptions(argv) {
+    let showHelp = false;
+    let verbose = false;
+    let logToPath;
+    for (let index = 0; index < argv.length; index += 1) {
+        const argument = argv[index] ?? "";
+        if (argument === "-h" || argument === "--help") {
+            showHelp = true;
+            continue;
+        }
+        if (argument === "-v" || argument === "--verbose") {
+            verbose = true;
+            continue;
+        }
+        if (argument === "--log-to") {
+            const nextArgument = argv[index + 1];
+            if (!nextArgument) {
+                throw new Error("Expected a file path after --log-to.");
+            }
+            logToPath = nextArgument;
+            index += 1;
+            continue;
+        }
+        if (argument.startsWith("--log-to=")) {
+            const value = argument.slice("--log-to=".length);
+            if (!value) {
+                throw new Error("Expected a file path after --log-to=.");
+            }
+            logToPath = value;
+        }
+    }
+    return { showHelp, verbose, logToPath };
+}
+export function buildProviderStatsOptions(options) {
+    return {
+        verbose: options.verbose,
+        traceLogger: options.logToPath ? createFileTraceLogger(options.logToPath) : undefined
+    };
+}
+export function buildHelpText() {
+    return [
+        "letmecode - provider-based terminal usage dashboard",
+        "",
+        "Usage:",
+        "  letmecode [options]",
+        "",
+        "Options:",
+        "  -h, --help         Show this help and exit",
+        "  -v, --verbose      Show extra provider warnings",
+        "  --log-to PATH      Write trace logs to PATH",
+        "",
+        "Controls:",
+        "  [ ] / Tab          Switch providers",
+        "  Shift+Tab          Switch providers backward",
+        "  j / k              Switch dashboard sections",
+        "  Up / Down          Switch dashboard sections",
+        "  Left / Right       Select the previous or next row",
+        "  1, h / l, Enter    Run Copilot setup actions",
+        "  q or Esc           Quit",
+        "",
+        "Trace logging:",
+        "  --log-to PATH writes Claude CLI SDK and Claude VSCode detection details,",
+        "  every candidate binary path check, the final found/not-found result,",
+        "  and the raw /usage command output."
+    ].join("\n");
+}
+export function createFileTraceLogger(logPath) {
+    const resolvedPath = path.resolve(logPath);
+    fs.mkdirSync(path.dirname(resolvedPath), { recursive: true });
+    fs.writeFileSync(resolvedPath, [
+        "# letmecode trace",
+        `# started_at=${new Date().toISOString()}`,
+        `# cwd=${process.cwd()}`,
+        `# argv=${JSON.stringify(process.argv.slice(2))}`,
+        ""
+    ].join("\n"), "utf8");
+    return {
+        log(message) {
+            const timestamp = new Date().toISOString();
+            const formatted = message
+                .split(/\r?\n/)
+                .map((line, index) => (index === 0 ? `[${timestamp}] ${line}` : `  ${line}`))
+                .join("\n");
+            fs.appendFileSync(resolvedPath, `${formatted}\n`, "utf8");
+        }
+    };
+}

package/ink-app/dist/index.js

@@ -1,6 +1,7 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import React, { useCallback, useEffect, useRef, useState } from "react";
 import { Box, Text, measureElement, useApp, useInput, useStdin, useStdout, render } from "ink";
+import { buildHelpText, buildProviderStatsOptions, parseCliOptions } from "./cli-options.js";
 import { configureCopilotVsCodeLogging, createProviders } from "./providers/index.js";
 import { reportAnonymousUsage } from "./reporting.js";
 const ESC = String.fromCharCode(0x1b);
@@ -769,11 +770,6 @@ function getDayRows(providerState) {
 function getLimitRowKey(row) {
     return `${row.scope}-${row.planType}-${row.limitId}-${row.startTimeUtcIso}-${row.endTimeUtcIso}`;
 }
-function parseStatsOptions(argv) {
-    return {
-        verbose: argv.includes("-v") || argv.includes("--verbose")
-    };
-}
 function useViewportHeight() {
     const { stdout } = useStdout();
     const [viewportHeight, setViewportHeight] = useState(() => resolveViewportHeight(stdout.rows));
@@ -799,6 +795,12 @@ function resolveViewportHeight(rows) {
     return Math.max(1, terminalRows - 1);
 }
 export function main(argv = process.argv.slice(2)) {
+    const cliOptions = parseCliOptions(argv);
+    if (cliOptions.showHelp) {
+        process.stdout.write(`${buildHelpText()}\n`);
+        return;
+    }
+    const statsOptions = buildProviderStatsOptions(cliOptions);
     const restoreFullscreen = enterFullscreenMode(process.stdout);
     const disableMouse = enableMouseReporting(process.stdout);
     const exitHandler = () => {
@@ -806,7 +808,7 @@ export function main(argv = process.argv.slice(2)) {
         restoreFullscreen();
     };
     process.once("exit", exitHandler);
-    const instance = render(_jsx(App, { statsOptions: parseStatsOptions(argv) }), {
+    const instance = render(_jsx(App, { statsOptions: statsOptions }), {
         stdout: process.stdout,
         stdin: process.stdin,
         stderr: process.stderr

package/ink-app/dist/providers/claude.js

@@ -61,7 +61,7 @@ export class ClaudeUsageProvider extends UsageProviderBase {
         const resolvedSessionsRoot = await resolveClaudeSessionsRoot(this.root);
         const sessionsRoot = resolvedSessionsRoot.rootPath;
         const agentName = normalizeAnalyticsAgentName(this.label);
-        const userIdHash = await readClaudeUserIdHash(this.root, this.usageCommandKind, this.readAuthStatusOutput, agentName);
+        const userIdHash = await readClaudeUserIdHash(this.root, this.usageCommandKind, this.readAuthStatusOutput, agentName, options.traceLogger);
         const byModel = new Map();
         const byDay = createDailyUsageAggregates();
         const windows = createLimitWindowAggregates();
@@ -131,6 +131,7 @@ export class ClaudeUsageProvider extends UsageProviderBase {
             usageCommandKind: this.usageCommandKind,
             readUsageCommandOutput: this.readUsageCommandOutput,
             readAuthStatusOutput: this.readAuthStatusOutput,
+            traceLogger: options.traceLogger,
             now: this.now(),
             selectedEvents
         });
@@ -470,12 +471,41 @@ function normalizeTimestamp(value) {
 function extractRateLimits(payloadObject, message) {
     return asRecord(payloadObject.rate_limits) ?? asRecord(message?.rate_limits);
 }
+function traceClaude(traceLogger, usageCommandKind, message) {
+    if (!traceLogger) {
+        return;
+    }
+    const targetLabel = usageCommandKind === "vscode" ? "Claude VSCode" : "Claude";
+    traceLogger.log(`[${targetLabel}] ${message}`);
+}
+function formatErrorMessage(error) {
+    if (!error) {
+        return "Unknown error";
+    }
+    if (error instanceof Error && error.message) {
+        return error.message;
+    }
+    return String(error);
+}
+function describeUsageOutput(output) {
+    if (output == null) {
+        return "<null>";
+    }
+    return output.trim() ? output : "<empty>";
+}
+function buildClaudeCommandEnvironment() {
+    return {
+        ...process.env,
+        TZ: "UTC"
+    };
+}
 async function buildLiveLimitWindows(options) {
     const [usageOutput, subscriptionType] = await Promise.all([
-        readClaudeUsageCommandOutput(options.root, options.usageCommandKind, options.readUsageCommandOutput),
-        readClaudeSubscriptionType(options.root, options.usageCommandKind, options.readAuthStatusOutput)
+        readClaudeUsageCommandOutput(options.root, options.usageCommandKind, options.readUsageCommandOutput, options.traceLogger),
+        readClaudeSubscriptionType(options.root, options.usageCommandKind, options.readAuthStatusOutput, options.traceLogger)
     ]);
     const snapshots = parseLiveUsageWindowSnapshots(usageOutput, options.now);
+    traceClaude(options.traceLogger, options.usageCommandKind, `Parsed ${snapshots.length} live usage snapshot(s) from /usage output.`);
     const resolvedPlanType = subscriptionType || "live";
     return {
         primaryLimitWindows: snapshots
@@ -486,41 +516,52 @@ async function buildLiveLimitWindows(options) {
             .map((snapshot) => buildLiveLimitWindowRow(snapshot, resolvedPlanType, options.selectedEvents, options.now))
     };
 }
-async function readClaudeSubscriptionType(root, usageCommandKind, override) {
-    const output = await readClaudeAuthStatusOutput(root, usageCommandKind, override);
-    return parseClaudeSubscriptionType(output);
+async function readClaudeSubscriptionType(root, usageCommandKind, override, traceLogger) {
+    const output = await readClaudeAuthStatusOutput(root, usageCommandKind, override, traceLogger);
+    const subscriptionType = parseClaudeSubscriptionType(output);
+    traceClaude(traceLogger, usageCommandKind, `Subscription type result: ${subscriptionType ?? "<none>"}.`);
+    return subscriptionType;
 }
-async function readClaudeAuthStatusOutput(root, usageCommandKind, override) {
+async function readClaudeAuthStatusOutput(root, usageCommandKind, override, traceLogger) {
     if (override) {
         try {
-            return await override();
+            const output = await override();
+            traceClaude(traceLogger, usageCommandKind, "Using injected auth status output override.");
+            return output;
         }
         catch {
+            traceClaude(traceLogger, usageCommandKind, "Injected auth status output override failed.");
             return null;
         }
     }
     const cacheKey = `${usageCommandKind}:${path.resolve(root)}`;
     const cached = claudeAuthStatusOutputCache.get(cacheKey);
     if (cached) {
+        traceClaude(traceLogger, usageCommandKind, "Auth status output cache hit.");
         return cached;
     }
     const pending = (async () => {
-        const binaryPath = await resolveClaudeBinaryPath(root, usageCommandKind);
+        const binaryPath = await resolveClaudeBinaryPath(root, usageCommandKind, traceLogger);
         if (!binaryPath) {
+            traceClaude(traceLogger, usageCommandKind, "Skipping auth status command because no Claude binary was found.");
             return null;
         }
         try {
+            traceClaude(traceLogger, usageCommandKind, `Running auth status command with ${binaryPath} (TZ=UTC).`);
             const { stdout, stderr } = await execFileAsync(binaryPath, ["auth", "status"], {
                 encoding: "utf8",
+                env: buildClaudeCommandEnvironment(),
                 maxBuffer: 1024 * 1024,
                 timeout: 15000,
                 windowsHide: true
             });
             const combined = [stdout, stderr].filter(Boolean).join("\n").trim();
+            traceClaude(traceLogger, usageCommandKind, "Auth status command completed successfully.");
             return combined || null;
         }
         catch (error) {
             const combined = extractExecOutput(error);
+            traceClaude(traceLogger, usageCommandKind, `Auth status command failed: ${formatErrorMessage(error)}.`);
             return combined || null;
         }
     })();
@@ -557,45 +598,58 @@ function parseClaudeAuthStatusSnapshot(output) {
         return null;
     }
 }
-async function readClaudeUserIdHash(root, usageCommandKind, override, agentName) {
-    const authStatusOutput = await readClaudeAuthStatusOutput(root, usageCommandKind, override);
+async function readClaudeUserIdHash(root, usageCommandKind, override, agentName, traceLogger) {
+    const authStatusOutput = await readClaudeAuthStatusOutput(root, usageCommandKind, override, traceLogger);
     const snapshot = parseClaudeAuthStatusSnapshot(authStatusOutput);
     if (!snapshot) {
         return null;
     }
     return buildUserIdHash([agentName, snapshot.email, snapshot.orgId, snapshot.orgName]);
 }
-async function readClaudeUsageCommandOutput(root, usageCommandKind, override) {
+async function readClaudeUsageCommandOutput(root, usageCommandKind, override, traceLogger) {
     if (override) {
         try {
-            return await override();
+            const output = await override();
+            traceClaude(traceLogger, usageCommandKind, "Using injected /usage output override.");
+            traceClaude(traceLogger, usageCommandKind, `Usage returned:\n${describeUsageOutput(output)}`);
+            return output;
         }
         catch {
+            traceClaude(traceLogger, usageCommandKind, "Injected /usage output override failed.");
             return null;
         }
     }
     const cacheKey = `${usageCommandKind}:${path.resolve(root)}`;
     const cached = claudeUsageOutputCache.get(cacheKey);
     if (cached) {
+        traceClaude(traceLogger, usageCommandKind, "Usage output cache hit.");
         return cached;
     }
     const pending = (async () => {
-        const binaryPath = await resolveClaudeBinaryPath(root, usageCommandKind);
+        const binaryPath = await resolveClaudeBinaryPath(root, usageCommandKind, traceLogger);
         if (!binaryPath) {
+            traceClaude(traceLogger, usageCommandKind, "Skipping /usage command because no Claude binary was found.");
+            traceClaude(traceLogger, usageCommandKind, "Usage returned:\n<not available>");
             return null;
         }
         try {
+            traceClaude(traceLogger, usageCommandKind, `Running /usage command with ${binaryPath} (TZ=UTC).`);
             const { stdout, stderr } = await execFileAsync(binaryPath, ["-p", "/usage"], {
                 encoding: "utf8",
+                env: buildClaudeCommandEnvironment(),
                 maxBuffer: 1024 * 1024,
                 timeout: 15000,
                 windowsHide: true
             });
             const combined = [stdout, stderr].filter(Boolean).join("\n").trim();
+            traceClaude(traceLogger, usageCommandKind, "Usage command completed successfully.");
+            traceClaude(traceLogger, usageCommandKind, `Usage returned:\n${describeUsageOutput(combined || null)}`);
             return combined || null;
         }
         catch (error) {
             const combined = extractExecOutput(error);
+            traceClaude(traceLogger, usageCommandKind, `Usage command failed: ${formatErrorMessage(error)}.`);
+            traceClaude(traceLogger, usageCommandKind, `Usage returned:\n${describeUsageOutput(combined || null)}`);
             return combined || null;
         }
     })();
@@ -610,51 +664,68 @@ function extractExecOutput(error) {
     const stderr = typeof error.stderr === "string" ? error.stderr : "";
     return [stdout, stderr].filter(Boolean).join("\n").trim();
 }
-async function resolveClaudeBinaryPath(root, usageCommandKind) {
+async function resolveClaudeBinaryPath(root, usageCommandKind, traceLogger) {
     const cacheKey = `${usageCommandKind}:${path.resolve(root)}`;
     const cached = claudeBinaryPathCache.get(cacheKey);
     if (cached) {
-        return cached;
+        const binaryPath = await cached;
+        traceClaude(traceLogger, usageCommandKind, `Binary detection cache hit: ${binaryPath ? `found ${binaryPath}` : "not found"}.`);
+        return binaryPath;
     }
-    const pending = usageCommandKind === "vscode"
-        ? resolveVsCodeClaudeBinaryPath(root)
-        : resolveCliClaudeBinaryPath(root);
+    const pending = (async () => {
+        traceClaude(traceLogger, usageCommandKind, `Starting binary detection under ${root}.`);
+        const binaryPath = usageCommandKind === "vscode"
+            ? await resolveVsCodeClaudeBinaryPath(root, traceLogger)
+            : await resolveCliClaudeBinaryPath(root, traceLogger);
+        traceClaude(traceLogger, usageCommandKind, `Binary detection result: ${binaryPath ? `found ${binaryPath}` : "not found"}.`);
+        return binaryPath;
+    })();
     claudeBinaryPathCache.set(cacheKey, pending);
     return pending;
 }
-async function resolveVsCodeClaudeBinaryPath(root) {
+async function resolveVsCodeClaudeBinaryPath(root, traceLogger) {
     const boosterDirectories = [
         path.join(root, ".vscode", "extensions"),
         path.join(root, ".vscode-server", "extensions"),
         path.join(root, ".vscode-server-insiders", "extensions")
     ];
+    let firstFoundPath = null;
     for (const directory of boosterDirectories) {
-        const binaryPath = await resolveClaudeBinaryFromExtensionDirectory(directory);
-        if (binaryPath) {
-            return binaryPath;
+        const binaryPath = await resolveClaudeBinaryFromExtensionDirectory(directory, traceLogger);
+        if (!firstFoundPath && binaryPath) {
+            firstFoundPath = binaryPath;
         }
     }
-    return null;
+    return firstFoundPath;
 }
-async function resolveClaudeBinaryFromExtensionDirectory(directory) {
+async function resolveClaudeBinaryFromExtensionDirectory(directory, traceLogger) {
     let entries;
+    traceClaude(traceLogger, "vscode", `Scanning extension directory ${directory}.`);
     try {
         entries = await fs.promises.readdir(directory, { withFileTypes: true });
     }
-    catch {
+    catch (error) {
+        traceClaude(traceLogger, "vscode", `Could not read ${directory}: ${formatErrorMessage(error)}.`);
         return null;
     }
     const candidates = entries
         .filter((entry) => entry.isDirectory() && entry.name.startsWith(VSCODE_CLAUDE_EXTENSION_PREFIX))
         .map((entry) => entry.name)
         .sort(compareClaudeExtensionDirectoryNames);
+    if (candidates.length === 0) {
+        traceClaude(traceLogger, "vscode", `No Claude VSCode extension candidates found in ${directory}.`);
+        return null;
+    }
+    let firstFoundPath = null;
     for (const candidate of candidates) {
         const binaryPath = path.join(directory, candidate, "resources", "native-binary", "claude");
-        if (await isReadableExecutableFile(binaryPath)) {
-            return binaryPath;
+        const accessCheck = await checkReadableExecutableFile(binaryPath);
+        traceClaude(traceLogger, "vscode", `Checked ${binaryPath} -> ${accessCheck.ok ? "success" : `failure (${accessCheck.errorMessage ?? "unknown"})`}.`);
+        if (!firstFoundPath && accessCheck.ok) {
+            firstFoundPath = binaryPath;
         }
     }
-    return null;
+    return firstFoundPath;
 }
 function compareClaudeExtensionDirectoryNames(left, right) {
     const leftVersion = extractClaudeExtensionVersion(left);
@@ -678,25 +749,31 @@ function extractClaudeExtensionVersion(directoryName) {
         .map((part) => Number(part))
         .filter((part) => Number.isFinite(part));
 }
-async function resolveCliClaudeBinaryPath(root) {
+async function resolveCliClaudeBinaryPath(root, traceLogger) {
     const directCandidates = [
         path.join(root, ".local", "bin", "claude"),
         path.join(root, "bin", "claude")
     ];
+    let firstFoundPath = null;
     for (const candidate of directCandidates) {
-        if (await isReadableExecutableFile(candidate)) {
-            return candidate;
+        const accessCheck = await checkReadableExecutableFile(candidate);
+        traceClaude(traceLogger, "cli", `Checked ${candidate} -> ${accessCheck.ok ? "success" : `failure (${accessCheck.errorMessage ?? "unknown"})`}.`);
+        if (!firstFoundPath && accessCheck.ok) {
+            firstFoundPath = candidate;
         }
     }
-    return null;
+    return firstFoundPath;
 }
-async function isReadableExecutableFile(filePath) {
+async function checkReadableExecutableFile(filePath) {
     try {
         await fs.promises.access(filePath, fs.constants.R_OK | fs.constants.X_OK);
-        return true;
+        return { ok: true };
     }
-    catch {
-        return false;
+    catch (error) {
+        return {
+            ok: false,
+            errorMessage: formatErrorMessage(error)
+        };
     }
 }
 function parseLiveUsageWindowSnapshots(usageOutput, now) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "letmecode",
-  "version": "0.1.6",
+  "version": "0.1.8",
   "description": "Provider-based terminal usage dashboard for LetMeCode.",
   "author": "devforth.io",
   "license": "MIT",