myshell-tools 2.0.0-alpha.0 → 2.1.0

package/dist/infra/insights.d.ts

@@ -0,0 +1,66 @@
+/**
+ * src/infra/insights.ts — Pure reducers over LedgerEntry[] for spend and provider health.
+ *
+ * No I/O. All functions are deterministic given the same inputs.
+ * Safe to call in tests with hand-built arrays.
+ *
+ * Honesty Contract:
+ *   - No hardcoded percentages — success rates are always computed from data.
+ *   - No digit-% literals in source — percent strings are built by concatenation.
+ *   - No fabricated values — all outputs derive strictly from the input entries.
+ */
+import type { LedgerEntry } from '../core/types.js';
+/** Aggregated spend data suitable for display in the control panel header. */
+export interface SpendSummary {
+    /** Total USD spent in the current calendar day (UTC). */
+    readonly todayUsd: number;
+    /** Total USD spent across all time. */
+    readonly totalUsd: number;
+    /** Total number of ledger entries (calls). */
+    readonly calls: number;
+    /** Per-provider breakdown keyed by ProviderId string. */
+    readonly byProvider: Record<string, {
+        readonly usd: number;
+        readonly calls: number;
+    }>;
+}
+/**
+ * Pure reduction over LedgerEntry[] that produces a SpendSummary.
+ *
+ * "Today" is defined as entries whose `timestamp` ISO string has the same
+ * YYYY-MM-DD date prefix as `nowIso`. Both are treated as UTC.
+ *
+ * @param entries - Array of LedgerEntry objects (may be empty).
+ * @param nowIso  - ISO-8601 timestamp representing "now" (e.g. from Clock.isoNow()).
+ */
+export declare function summarizeSpend(entries: LedgerEntry[], nowIso: string): SpendSummary;
+/** Health summary for a single provider derived from its ledger entries. */
+export interface ProviderHealth {
+    readonly provider: string;
+    readonly calls: number;
+    /** Fraction of successful calls in [0, 1]. 0 when calls === 0. */
+    readonly successRate: number;
+    /** Arithmetic mean of durationMs. 0 when calls === 0. */
+    readonly avgDurationMs: number;
+    readonly status: 'healthy' | 'degraded' | 'unknown';
+}
+/**
+ * Compute per-provider health from a LedgerEntry array.
+ *
+ * Status thresholds:
+ *   - `unknown`  — 0 calls
+ *   - `degraded` — successRate < 0.7
+ *   - `healthy`  — successRate >= 0.7
+ *
+ * @param entries - Array of LedgerEntry objects (may be empty).
+ */
+export declare function providerHealth(entries: LedgerEntry[]): ProviderHealth[];
+/**
+ * Format a USD amount as a string with a `$` prefix and 4 decimal places.
+ *
+ * The result never contains a digit immediately before `%` — this is a dollar
+ * amount, not a percentage.
+ *
+ * @param n - Amount in US dollars (may be 0).
+ */
+export declare function formatUsd(n: number): string;

package/dist/infra/insights.js

@@ -0,0 +1,105 @@
+/**
+ * src/infra/insights.ts — Pure reducers over LedgerEntry[] for spend and provider health.
+ *
+ * No I/O. All functions are deterministic given the same inputs.
+ * Safe to call in tests with hand-built arrays.
+ *
+ * Honesty Contract:
+ *   - No hardcoded percentages — success rates are always computed from data.
+ *   - No digit-% literals in source — percent strings are built by concatenation.
+ *   - No fabricated values — all outputs derive strictly from the input entries.
+ */
+/**
+ * Pure reduction over LedgerEntry[] that produces a SpendSummary.
+ *
+ * "Today" is defined as entries whose `timestamp` ISO string has the same
+ * YYYY-MM-DD date prefix as `nowIso`. Both are treated as UTC.
+ *
+ * @param entries - Array of LedgerEntry objects (may be empty).
+ * @param nowIso  - ISO-8601 timestamp representing "now" (e.g. from Clock.isoNow()).
+ */
+export function summarizeSpend(entries, nowIso) {
+    const todayDate = nowIso.slice(0, 10); // 'YYYY-MM-DD'
+    let todayUsd = 0;
+    let totalUsd = 0;
+    const byProvider = {};
+    for (const entry of entries) {
+        totalUsd += entry.usd;
+        if (entry.timestamp.slice(0, 10) === todayDate) {
+            todayUsd += entry.usd;
+        }
+        const existing = byProvider[entry.provider];
+        if (existing !== undefined) {
+            existing.usd += entry.usd;
+            existing.calls += 1;
+        }
+        else {
+            byProvider[entry.provider] = { usd: entry.usd, calls: 1 };
+        }
+    }
+    return {
+        todayUsd,
+        totalUsd,
+        calls: entries.length,
+        byProvider,
+    };
+}
+/**
+ * Compute per-provider health from a LedgerEntry array.
+ *
+ * Status thresholds:
+ *   - `unknown`  — 0 calls
+ *   - `degraded` — successRate < 0.7
+ *   - `healthy`  — successRate >= 0.7
+ *
+ * @param entries - Array of LedgerEntry objects (may be empty).
+ */
+export function providerHealth(entries) {
+    const byProvider = {};
+    for (const entry of entries) {
+        const existing = byProvider[entry.provider];
+        if (existing !== undefined) {
+            existing.calls += 1;
+            existing.successes += entry.success ? 1 : 0;
+            existing.durationMs += entry.durationMs;
+        }
+        else {
+            byProvider[entry.provider] = {
+                calls: 1,
+                successes: entry.success ? 1 : 0,
+                durationMs: entry.durationMs,
+            };
+        }
+    }
+    return Object.entries(byProvider).map(([provider, agg]) => {
+        const { calls, successes, durationMs } = agg;
+        const successRate = calls === 0 ? 0 : successes / calls;
+        const avgDurationMs = calls === 0 ? 0 : durationMs / calls;
+        let status;
+        if (calls === 0) {
+            status = 'unknown';
+        }
+        else if (successRate < 0.7) {
+            status = 'degraded';
+        }
+        else {
+            status = 'healthy';
+        }
+        return { provider, calls, successRate, avgDurationMs, status };
+    });
+}
+// ---------------------------------------------------------------------------
+// formatUsd
+// ---------------------------------------------------------------------------
+/**
+ * Format a USD amount as a string with a `$` prefix and 4 decimal places.
+ *
+ * The result never contains a digit immediately before `%` — this is a dollar
+ * amount, not a percentage.
+ *
+ * @param n - Amount in US dollars (may be 0).
+ */
+export function formatUsd(n) {
+    return '$' + n.toFixed(4);
+}
+//# sourceMappingURL=insights.js.map

package/dist/infra/insights.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"insights.js","sourceRoot":"","sources":["../../src/infra/insights.ts"],"names":[],"mappings":"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"}

package/dist/infra/ledger.d.ts

@@ -23,16 +23,14 @@ export declare function createLedger(opts: {
  * @param cwd - The project working directory.
  */
 export declare function readLedger(cwd: string): Promise<LedgerEntry[]>;
-/** Per-model aggregation used in the summary. */
-export interface ModelSummary {
-    readonly calls: number;
-    readonly usd: number;
-}
 /** Aggregate summary returned by `summarizeLedger`. */
 export interface LedgerSummary {
     readonly totalUsd: number;
     readonly calls: number;
-    readonly byModel: Record<string, ModelSummary>;
+    readonly byModel: Record<string, {
+        readonly calls: number;
+        readonly usd: number;
+    }>;
 }
 /**
  * Pure reduction over a ledger entry array.

package/dist/infra/ledger.js.map

@@ -1 +1 @@
-{"version":3,"file":"ledger.js","sourceRoot":"","sources":["../../src/infra/ledger.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAEnD,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAExD;;;;GAIG;AACH,MAAM,UAAU,YAAY,CAAC,IAAqB;IAChD,MAAM,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;IAErB,OAAO;QACL,KAAK,CAAC,MAAM,CAAC,KAAkB;YAC7B,MAAM,KAAK,CAAC,WAAW,CAAC,GAAG,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;YACnD,MAAM,iBAAiB,CAAC,aAAa,CAAC,GAAG,CAAC,EAAE,KAAK,CAAC,CAAC;QACrD,CAAC;KACF,CAAC;AACJ,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,UAAU,CAAC,GAAW;IAC1C,IAAI,GAAW,CAAC;IAChB,IAAI,CAAC;QACH,GAAG,GAAG,MAAM,QAAQ,CAAC,aAAa,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,CAAC;IACnD,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,OAAO,GAAG,GAA4B,CAAC;QAC7C,IAAI,OAAO,CAAC,IAAI,KAAK,QAAQ;YAAE,OAAO,EAAE,CAAC;QACzC,MAAM,GAAG,CAAC;IACZ,CAAC;IAED,MAAM,OAAO,GAAkB,EAAE,CAAC;IAClC,KAAK,MAAM,IAAI,IAAI,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;QACnC,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC;QAC5B,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;YAAE,SAAS;QACnC,IAAI,CAAC;YACH,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAgB,CAAC,CAAC;QACnD,CAAC;QAAC,MAAM,CAAC;YACP,uBAAuB;QACzB,CAAC;IACH,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC;AAeD;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,eAAe,CAAC,OAAsB;IACpD,IAAI,QAAQ,GAAG,CAAC,CAAC;IACjB,MAAM,OAAO,GAAmD,EAAE,CAAC;IAEnE,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;QAC5B,QAAQ,IAAI,KAAK,CAAC,GAAG,CAAC;QAEtB,MAAM,QAAQ,GAAG,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;QACtC,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;YAC3B,QAAQ,CAAC,KAAK,IAAI,CAAC,CAAC;YACpB,QAAQ,CAAC,GAAG,IAAI,KAAK,CAAC,GAAG,CAAC;QAC5B,CAAC;aAAM,CAAC;YACN,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,GAAG,EAAE,KAAK,EAAE,CAAC,EAAE,GAAG,EAAE,KAAK,CAAC,GAAG,EAAE,CAAC;QACtD,CAAC;IACH,CAAC;IAED,OAAO;QACL,QAAQ;QACR,KAAK,EAAE,OAAO,CAAC,MAAM;QACrB,OAAO;KACR,CAAC;AACJ,CAAC"}
+{"version":3,"file":"ledger.js","sourceRoot":"","sources":["../../src/infra/ledger.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAEnD,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAExD;;;;GAIG;AACH,MAAM,UAAU,YAAY,CAAC,IAAqB;IAChD,MAAM,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;IAErB,OAAO;QACL,KAAK,CAAC,MAAM,CAAC,KAAkB;YAC7B,MAAM,KAAK,CAAC,WAAW,CAAC,GAAG,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;YACnD,MAAM,iBAAiB,CAAC,aAAa,CAAC,GAAG,CAAC,EAAE,KAAK,CAAC,CAAC;QACrD,CAAC;KACF,CAAC;AACJ,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,UAAU,CAAC,GAAW;IAC1C,IAAI,GAAW,CAAC;IAChB,IAAI,CAAC;QACH,GAAG,GAAG,MAAM,QAAQ,CAAC,aAAa,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,CAAC;IACnD,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,OAAO,GAAG,GAA4B,CAAC;QAC7C,IAAI,OAAO,CAAC,IAAI,KAAK,QAAQ;YAAE,OAAO,EAAE,CAAC;QACzC,MAAM,GAAG,CAAC;IACZ,CAAC;IAED,MAAM,OAAO,GAAkB,EAAE,CAAC;IAClC,KAAK,MAAM,IAAI,IAAI,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;QACnC,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC;QAC5B,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;YAAE,SAAS;QACnC,IAAI,CAAC;YACH,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAgB,CAAC,CAAC;QACnD,CAAC;QAAC,MAAM,CAAC;YACP,uBAAuB;QACzB,CAAC;IACH,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC;AASD;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,eAAe,CAAC,OAAsB;IACpD,IAAI,QAAQ,GAAG,CAAC,CAAC;IACjB,MAAM,OAAO,GAAmD,EAAE,CAAC;IAEnE,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;QAC5B,QAAQ,IAAI,KAAK,CAAC,GAAG,CAAC;QAEtB,MAAM,QAAQ,GAAG,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;QACtC,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;YAC3B,QAAQ,CAAC,KAAK,IAAI,CAAC,CAAC;YACpB,QAAQ,CAAC,GAAG,IAAI,KAAK,CAAC,GAAG,CAAC;QAC5B,CAAC;aAAM,CAAC;YACN,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,GAAG,EAAE,KAAK,EAAE,CAAC,EAAE,GAAG,EAAE,KAAK,CAAC,GAAG,EAAE,CAAC;QACtD,CAAC;IACH,CAAC;IAED,OAAO;QACL,QAAQ;QACR,KAAK,EAAE,OAAO,CAAC,MAAM;QACrB,OAAO;KACR,CAAC;AACJ,CAAC"}

package/dist/interface/menu.d.ts

@@ -0,0 +1,112 @@
+/**
+ * src/interface/menu.ts — Sessions-first interactive control panel.
+ *
+ * Implements the dual-brain UX design bible:
+ *   - A boxed header with provider status (real, from EnvironmentStatus).
+ *   - Recent conversations (up to 7, relative timestamps from the store).
+ *   - A sectioned menu with letter-key dispatch.
+ *   - First-run welcome / 10-second setup flow.
+ *   - Per-conversation chat loop backed by runTask().
+ *
+ * Architecture rules:
+ *   - NO process.exit() — caller (cli.ts) owns process lifetime.
+ *   - NO Math.random() — all ids / timestamps via injected Clock.
+ *   - NO fabricated data — every displayed value is real (env, store, clock).
+ *   - NO digit-% literals — percentages are always computed, never hardcoded.
+ *   - All rendering goes through ui/tui.ts primitives.
+ */
+import type { Clock, LedgerWriter } from '../core/types.js';
+import type { AppConfig } from '../infra/config.js';
+import type { ConversationMeta, ConversationStore } from '../infra/conversation-store.js';
+import type { SpendSummary } from '../infra/insights.js';
+import type { EnvironmentStatus } from '../providers/detect.js';
+import type { Provider, ProviderId, SandboxLevel } from '../providers/port.js';
+import type { OutputSink } from './render.js';
+export interface MenuContext {
+    readonly version: string;
+    readonly clock: Clock;
+    readonly ledger: LedgerWriter;
+    readonly providers: Partial<Record<ProviderId, Provider>>;
+    readonly env: EnvironmentStatus;
+    readonly store: ConversationStore;
+    readonly config: AppConfig;
+    readonly cwd: string;
+    readonly sandbox: SandboxLevel;
+    readonly timeoutMs: number;
+    /**
+     * Optional injected line reader for testing. When provided, `startMenu` uses
+     * this instead of the real `node:readline` interface, allowing tests to drive
+     * the menu with scripted input without a TTY.
+     *
+     * Returns the next trimmed line of input, or `null` on EOF/close.
+     */
+    readonly readLine?: () => Promise<string | null>;
+}
+/**
+ * Return the shell alias hint the user can add to their shell profile to make
+ * `myshell-tools` the default command-line assistant.
+ *
+ * This is a pure, I/O-free helper — it never reads or writes any file. The
+ * caller is responsible for printing the result. No claim is made that the
+ * system has been changed; the output is a copy-pasteable suggestion only.
+ *
+ * @param shell    - The value of `process.env.SHELL` (e.g. '/bin/bash'), or
+ *                   empty/undefined on Windows where SHELL is absent.
+ * @param platform - The `process.platform` string (e.g. 'win32', 'linux').
+ * @returns A human-readable string containing the exact alias line to add.
+ */
+export declare function defaultAliasHint(shell: string | undefined, platform: string): string;
+/**
+ * Format a relative time string from a past epoch-ms to a now epoch-ms.
+ * Returns "just now", "Nm ago" (minutes), "Nh ago" (hours), or "Nd ago" (days).
+ * All arithmetic is pure — no Date, no Math.random.
+ */
+export declare function relativeTime(thenMs: number, nowMs: number): string;
+/**
+ * Build the header box lines (provider status) from real EnvironmentStatus.
+ * Returns string[] safe to pass as the `lines` arg to box().
+ *
+ * Per-provider logic (uses REAL authenticated + plan fields):
+ *   ✅  when ps.installed && ps.authenticated
+ *   ⚠️  when ps.installed && !ps.authenticated  (append " not signed in")
+ *   ❌  when !ps.installed                       (append install command)
+ * Plan label appended when ps.plan is non-null (e.g. " (Max x5)").
+ */
+export declare function renderHeaderLines(env: EnvironmentStatus, _version: string): string[];
+/**
+ * Render the budget/spend status line shown beneath the provider header.
+ *
+ * Uses real numbers only — all values come from the SpendSummary which is
+ * derived from `readLedger`. No digit-% literals appear in this function; it
+ * shows dollar amounts only.
+ *
+ * @param spend - Output of summarizeSpend() over real ledger entries.
+ * @param color - When false, no ANSI escape codes are emitted.
+ */
+export declare function renderBudgetLine(spend: SpendSummary, _color: boolean): string;
+/**
+ * Build the conversation list lines from real ConversationMeta[].
+ * Format: "[N] <pin> <relative-time>  <title>[  [<category>]]"
+ *
+ * Pin prefix: "📌 " for pinned, "   " (3 spaces) for alignment when not pinned.
+ * Category suffix: "  [<category>]" appended when category is set, omitted otherwise.
+ * Returns string[] (no ANSI — pure string building, safe for tests).
+ */
+export declare function renderConversationList(metas: ConversationMeta[], nowMs: number): string[];
+/**
+ * Start the sessions-first interactive menu.
+ *
+ * Follows the dual-brain UX design bible:
+ *   A. First run: welcome / 10-second setup → mark onboarded.
+ *   B. Main screen loop: header + recent conversations + sectioned menu.
+ *   C. Per-conversation chat loop backed by runTask().
+ *
+ * Never calls process.exit() — resolves when the user presses [q] or when
+ * stdin reaches EOF (resolves cleanly, no ERR_USE_AFTER_CLOSE thrown).
+ *
+ * When `ctx.readLine` is provided (e.g. in tests), it is used directly in
+ * place of a real readline interface. When absent, a readline interface is
+ * created from `process.stdin` as usual; the `close` event is wired up so
+ * that EOF resolves gracefully instead of throwing.
+ */
+export declare function startMenu(ctx: MenuContext, out: OutputSink): Promise<void>;