myshell-tools 2.8.0 → 2.10.0

package/dist/infra/credentials.d.ts

@@ -56,3 +56,31 @@ export declare function applyStoredCredentials(env: NodeJS.ProcessEnv, homeDir?:
  *   extractClaudeToken('no token here')                   // → null
  */
 export declare function extractClaudeToken(text: string): string | null;
+/**
+ * Strip surrounding whitespace and enclosing `"` or `'` quotes from a pasted
+ * string. Useful for normalising user-pasted tokens before extraction.
+ *
+ * Pure / never throws.
+ *
+ * @example
+ *   stripPastedSecretWrapper('"  sk-ant-oat01-abc  "') // → 'sk-ant-oat01-abc'
+ *   stripPastedSecretWrapper("'token'")               // → 'token'
+ *   stripPastedSecretWrapper('  plain  ')             // → 'plain'
+ */
+export declare function stripPastedSecretWrapper(raw: string): string;
+/**
+ * Classify a pasted secret string into one of three categories:
+ *
+ * - `'oauth-token'` — starts with `sk-ant-oat` (the expected setup-token output).
+ * - `'api-key'`     — starts with `sk-ant-api` (a raw Anthropic API key, NOT what we want).
+ * - `'none'`        — neither; blank or unrecognised.
+ *
+ * Input is pre-normalised (trimmed, quotes stripped) by the caller.
+ * Pure / never throws.
+ *
+ * @example
+ *   classifyPastedSecret('sk-ant-oat01-abc-XYZ') // → 'oauth-token'
+ *   classifyPastedSecret('sk-ant-api03-abc-XYZ') // → 'api-key'
+ *   classifyPastedSecret('not-a-token')           // → 'none'
+ */
+export declare function classifyPastedSecret(s: string): 'oauth-token' | 'api-key' | 'none';

package/dist/infra/credentials.js

@@ -146,7 +146,7 @@ export async function applyStoredCredentials(env, homeDir) {
     }
 }
 // ---------------------------------------------------------------------------
-// Pure token extraction helper
+// Pure token extraction and classification helpers
 // ---------------------------------------------------------------------------
 /**
  * Extract the first Claude long-lived OAuth token from `text`.
@@ -169,4 +169,55 @@ export function extractClaudeToken(text) {
         return null;
     }
 }
+/**
+ * Strip surrounding whitespace and enclosing `"` or `'` quotes from a pasted
+ * string. Useful for normalising user-pasted tokens before extraction.
+ *
+ * Pure / never throws.
+ *
+ * @example
+ *   stripPastedSecretWrapper('"  sk-ant-oat01-abc  "') // → 'sk-ant-oat01-abc'
+ *   stripPastedSecretWrapper("'token'")               // → 'token'
+ *   stripPastedSecretWrapper('  plain  ')             // → 'plain'
+ */
+export function stripPastedSecretWrapper(raw) {
+    try {
+        let s = raw.trim();
+        if ((s.startsWith('"') && s.endsWith('"')) ||
+            (s.startsWith("'") && s.endsWith("'"))) {
+            s = s.slice(1, -1).trim();
+        }
+        return s;
+    }
+    catch {
+        return raw;
+    }
+}
+/**
+ * Classify a pasted secret string into one of three categories:
+ *
+ * - `'oauth-token'` — starts with `sk-ant-oat` (the expected setup-token output).
+ * - `'api-key'`     — starts with `sk-ant-api` (a raw Anthropic API key, NOT what we want).
+ * - `'none'`        — neither; blank or unrecognised.
+ *
+ * Input is pre-normalised (trimmed, quotes stripped) by the caller.
+ * Pure / never throws.
+ *
+ * @example
+ *   classifyPastedSecret('sk-ant-oat01-abc-XYZ') // → 'oauth-token'
+ *   classifyPastedSecret('sk-ant-api03-abc-XYZ') // → 'api-key'
+ *   classifyPastedSecret('not-a-token')           // → 'none'
+ */
+export function classifyPastedSecret(s) {
+    try {
+        if (s.includes('sk-ant-oat'))
+            return 'oauth-token';
+        if (s.includes('sk-ant-api'))
+            return 'api-key';
+        return 'none';
+    }
+    catch {
+        return 'none';
+    }
+}
 //# sourceMappingURL=credentials.js.map

package/dist/infra/credentials.js.map

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

package/dist/infra/update-check.d.ts

@@ -0,0 +1,67 @@
+/**
+ * src/infra/update-check.ts — Self-update detection for myshell-tools.
+ *
+ * Checks the npm registry for the latest published version, caches the result
+ * so the check costs nothing on subsequent runs within the TTL, and reports
+ * whether an update is available.
+ *
+ * Architecture rules:
+ *   - NEVER throws — all errors are caught and return a safe default.
+ *   - NEVER hits the network in tests — `fetchLatest` is injected so tests stay hermetic.
+ *   - Cache is stored atomically at ~/.myshell-tools/update-check.json.
+ *   - Date.now() is allowed here (infra layer, same as config.ts / atomic.ts).
+ */
+export interface UpdateCheckResult {
+    readonly current: string;
+    readonly latest: string | null;
+    readonly updateAvailable: boolean;
+}
+interface UpdateCache {
+    checkedAt: number;
+    latest: string;
+}
+/**
+ * Load the update cache from disk.  Returns null on missing/corrupt file.
+ * Never throws.
+ */
+export declare function loadUpdateCache(homeDir?: string): Promise<UpdateCache | null>;
+/**
+ * Persist the update cache atomically.  Creates the .myshell-tools directory
+ * if it does not exist.  Never throws.
+ */
+export declare function saveUpdateCache(latest: string, now: number, homeDir?: string): Promise<void>;
+/**
+ * Compare two semver-ish version strings.
+ *
+ * Splits on `.`, compares numeric major/minor/patch segments in order.
+ * Any `-prerelease` suffix is stripped before comparison.
+ * Non-numeric segments are treated as 0.
+ * Returns true iff latest > current.
+ * Never throws.
+ */
+export declare function isNewerVersion(latest: string, current: string): boolean;
+/**
+ * Fetch the latest published version of myshell-tools from the npm registry.
+ *
+ * Uses global fetch with a 1500ms AbortSignal timeout.
+ * Returns the version string, or null on any error/timeout.
+ * Never throws.
+ */
+export declare function fetchLatestFromNpm(): Promise<string | null>;
+export interface CheckForUpdateOpts {
+    readonly currentVersion: string;
+    readonly now: number;
+    readonly homeDir?: string;
+    readonly ttlMs?: number;
+    readonly fetchLatest?: () => Promise<string | null>;
+}
+/**
+ * Check whether a newer version of myshell-tools is available.
+ *
+ * Uses a cache file so the npm registry is only contacted once per TTL (default 24h).
+ * If the cache is fresh, the registry is NOT contacted at all.
+ * On any error returns { current, latest: null, updateAvailable: false }.
+ * Never throws.
+ */
+export declare function checkForUpdate(opts: CheckForUpdateOpts): Promise<UpdateCheckResult>;
+export {};

package/dist/infra/update-check.js

@@ -0,0 +1,181 @@
+/**
+ * src/infra/update-check.ts — Self-update detection for myshell-tools.
+ *
+ * Checks the npm registry for the latest published version, caches the result
+ * so the check costs nothing on subsequent runs within the TTL, and reports
+ * whether an update is available.
+ *
+ * Architecture rules:
+ *   - NEVER throws — all errors are caught and return a safe default.
+ *   - NEVER hits the network in tests — `fetchLatest` is injected so tests stay hermetic.
+ *   - Cache is stored atomically at ~/.myshell-tools/update-check.json.
+ *   - Date.now() is allowed here (infra layer, same as config.ts / atomic.ts).
+ */
+import { mkdir, readFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { atomicWrite } from './atomic.js';
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+const TTL_MS_DEFAULT = 24 * 60 * 60 * 1000; // 24 hours
+const FETCH_TIMEOUT_MS = 1_500;
+// ---------------------------------------------------------------------------
+// Path helpers
+// ---------------------------------------------------------------------------
+function getCacheDir(homeDir) {
+    return join(homeDir, '.myshell-tools');
+}
+function getCachePath(homeDir) {
+    return join(getCacheDir(homeDir), 'update-check.json');
+}
+// ---------------------------------------------------------------------------
+// Cache helpers
+// ---------------------------------------------------------------------------
+/**
+ * Load the update cache from disk.  Returns null on missing/corrupt file.
+ * Never throws.
+ */
+export async function loadUpdateCache(homeDir) {
+    const home = homeDir ?? homedir();
+    try {
+        const raw = await readFile(getCachePath(home), 'utf8');
+        const parsed = JSON.parse(raw);
+        if (parsed !== null &&
+            typeof parsed === 'object' &&
+            'checkedAt' in parsed &&
+            'latest' in parsed &&
+            typeof parsed['checkedAt'] === 'number' &&
+            typeof parsed['latest'] === 'string') {
+            return parsed;
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Persist the update cache atomically.  Creates the .myshell-tools directory
+ * if it does not exist.  Never throws.
+ */
+export async function saveUpdateCache(latest, now, homeDir) {
+    const home = homeDir ?? homedir();
+    try {
+        await mkdir(getCacheDir(home), { recursive: true });
+        const cache = { checkedAt: now, latest };
+        await atomicWrite(getCachePath(home), JSON.stringify(cache, null, 2));
+    }
+    catch {
+        // Silently ignore — failing to cache is not a fatal error.
+    }
+}
+// ---------------------------------------------------------------------------
+// Version comparison
+// ---------------------------------------------------------------------------
+/**
+ * Compare two semver-ish version strings.
+ *
+ * Splits on `.`, compares numeric major/minor/patch segments in order.
+ * Any `-prerelease` suffix is stripped before comparison.
+ * Non-numeric segments are treated as 0.
+ * Returns true iff latest > current.
+ * Never throws.
+ */
+export function isNewerVersion(latest, current) {
+    try {
+        const parse = (v) => {
+            // Strip any prerelease suffix (e.g. "1.2.3-beta.1" → "1.2.3")
+            const base = v.split('-')[0] ?? '';
+            return base.split('.').map((part) => {
+                const n = parseInt(part, 10);
+                return Number.isFinite(n) ? n : 0;
+            });
+        };
+        const lParts = parse(latest);
+        const cParts = parse(current);
+        const len = Math.max(lParts.length, cParts.length);
+        for (let i = 0; i < len; i++) {
+            const l = lParts[i] ?? 0;
+            const c = cParts[i] ?? 0;
+            if (l > c)
+                return true;
+            if (l < c)
+                return false;
+        }
+        return false; // equal
+    }
+    catch {
+        return false;
+    }
+}
+// ---------------------------------------------------------------------------
+// npm registry fetch (real network — injected in tests)
+// ---------------------------------------------------------------------------
+/**
+ * Fetch the latest published version of myshell-tools from the npm registry.
+ *
+ * Uses global fetch with a 1500ms AbortSignal timeout.
+ * Returns the version string, or null on any error/timeout.
+ * Never throws.
+ */
+export async function fetchLatestFromNpm() {
+    const ac = new AbortController();
+    const timer = setTimeout(() => { ac.abort(); }, FETCH_TIMEOUT_MS);
+    try {
+        const res = await fetch('https://registry.npmjs.org/myshell-tools/latest', {
+            signal: ac.signal,
+        });
+        if (!res.ok)
+            return null;
+        const data = await res.json();
+        if (data !== null &&
+            typeof data === 'object' &&
+            'version' in data &&
+            typeof data['version'] === 'string') {
+            return data['version'] ?? null;
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/**
+ * Check whether a newer version of myshell-tools is available.
+ *
+ * Uses a cache file so the npm registry is only contacted once per TTL (default 24h).
+ * If the cache is fresh, the registry is NOT contacted at all.
+ * On any error returns { current, latest: null, updateAvailable: false }.
+ * Never throws.
+ */
+export async function checkForUpdate(opts) {
+    const { currentVersion, now, homeDir, ttlMs = TTL_MS_DEFAULT } = opts;
+    const fetchFn = opts.fetchLatest ?? fetchLatestFromNpm;
+    try {
+        // Check if we have a fresh cache
+        const cache = await loadUpdateCache(homeDir);
+        if (cache !== null && now - cache.checkedAt < ttlMs) {
+            // Cache is fresh — use it without hitting the network
+            const updateAvailable = isNewerVersion(cache.latest, currentVersion);
+            return { current: currentVersion, latest: cache.latest, updateAvailable };
+        }
+        // Cache is stale or missing — fetch from the registry
+        const latest = await fetchFn();
+        if (latest !== null) {
+            await saveUpdateCache(latest, now, homeDir);
+        }
+        if (latest === null) {
+            return { current: currentVersion, latest: null, updateAvailable: false };
+        }
+        const updateAvailable = isNewerVersion(latest, currentVersion);
+        return { current: currentVersion, latest, updateAvailable };
+    }
+    catch {
+        return { current: currentVersion, latest: null, updateAvailable: false };
+    }
+}
+//# sourceMappingURL=update-check.js.map

package/dist/infra/update-check.js.map

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

package/dist/interface/menu.d.ts

@@ -23,6 +23,7 @@ import type { EnvironmentStatus } from '../providers/detect.js';
 import type { Provider, ProviderId, SandboxLevel } from '../providers/port.js';
 import type { OutputSink } from './render.js';
 import type { LoginMethod } from '../commands/login.js';
+import type { UpdateCheckResult } from '../infra/update-check.js';
 export interface MenuContext {
     readonly version: string;
     readonly clock: Clock;
@@ -67,6 +68,30 @@ export interface MenuContext {
      * spawning during tests (e.g. after first-run onboarding or [j]/[k]/[o] login).
      */
     readonly detectEnvironment?: () => Promise<EnvironmentStatus>;
+    /**
+     * Optional injected update-check for testing. When provided, `startMenu` uses
+     * this instead of the real `checkForUpdate` from infra/update-check.ts,
+     * preventing real npm registry requests from being made during tests.
+     *
+     * Returns the update check result (current, latest, updateAvailable).
+     */
+    readonly checkForUpdate?: () => Promise<UpdateCheckResult>;
+    /**
+     * Optional injected self-update function for testing. When provided, `startMenu`
+     * uses this instead of the real `npm install -g myshell-tools@latest` subprocess.
+     *
+     * Returns true when the update succeeded (exit code 0), false otherwise.
+     * Never throws.
+     */
+    readonly updateSelf?: (out: OutputSink) => Promise<boolean>;
+    /**
+     * Optional injected relaunch function for testing. When provided, `startMenu`
+     * uses this instead of the real `execa('myshell-tools', …)` re-exec.
+     *
+     * Returns the exit code of the relaunched process (or 1 on spawn failure).
+     * Used only for the opt-in auto-update path.
+     */
+    readonly relaunch?: () => Promise<number>;
 }
 /**
  * Parse a yes/no answer from a raw input line, with a configurable default.

package/dist/interface/menu.js

@@ -322,10 +322,15 @@ async function runWelcome(ctx, out, readLine, mutableConfig, installProviderFn,
     out.write('Set myshell-tools as your default shell tool? (y/N) ');
     const defaultAns = await readLine();
     const setAsDefault = parseYesNo(defaultAns, false);
+    // Default is NO for auto-update — require explicit 'y' to enable.
+    out.write('Keep myshell-tools up to date automatically? (y/N) ');
+    const autoUpdateAns = await readLine();
+    const autoUpdate = parseYesNo(autoUpdateAns, false);
     const saved = {
         onboarded: true,
         setAsDefault,
         ...(updated.mode !== undefined ? { mode: updated.mode } : {}),
+        ...(autoUpdate ? { autoUpdate: true } : {}),
     };
     await saveConfig(saved);
     // When the user opts in, actually write the shell startup hook (real install,
@@ -393,6 +398,7 @@ async function runSettings(_ctx, mutableCtx, out, readLine) {
         '',
         `  [1] Mode: ${cfg.mode ?? 'balanced'}`,
         `  [2] Set as default shell: ${cfg.setAsDefault ? 'on' : 'off'}`,
+        `  [3] Auto-update: ${cfg.autoUpdate === true ? 'on' : 'off'}`,
         '',
         '  [Enter] Back',
         '',
@@ -409,8 +415,27 @@ async function runSettings(_ctx, mutableCtx, out, readLine) {
     else if (key === '2') {
         mutableCtx.config = await toggleDefaultShell(mutableCtx.config, out);
     }
+    else if (key === '3') {
+        mutableCtx.config = await toggleAutoUpdate(mutableCtx.config, out);
+    }
     // anything else → back
 }
+/**
+ * Toggle the auto-update preference and persist the updated config.
+ * Reports the new state so the user knows what changed.
+ */
+async function toggleAutoUpdate(config, out) {
+    const enable = config.autoUpdate !== true;
+    const updated = {
+        onboarded: config.onboarded,
+        setAsDefault: config.setAsDefault,
+        ...(config.mode !== undefined ? { mode: config.mode } : {}),
+        ...(enable ? { autoUpdate: true } : {}),
+    };
+    await saveConfig(updated);
+    out.write(`Auto-update: ${enable ? 'on' : 'off'}\n`);
+    return updated;
+}
 // ---------------------------------------------------------------------------
 // Manage conversations screen
 // ---------------------------------------------------------------------------
@@ -693,11 +718,15 @@ async function runChatLoop(ctx, mutableCtx, convId, out, readLine) {
 // ---------------------------------------------------------------------------
 // Main screen render
 // ---------------------------------------------------------------------------
-async function renderMainScreen(ctx, mutableCtx, metas, out) {
+async function renderMainScreen(ctx, mutableCtx, metas, out, updateInfo) {
     out.write('\n');
     // Header box — always box(), 🧠 emoji, real provider data
     const headerLines = renderHeaderLines(mutableCtx.env, ctx.version);
     out.write(box(`🧠 myshell-tools v${ctx.version}`, headerLines) + '\n\n');
+    // Update banner — only shown when a newer version is genuinely available
+    if (updateInfo?.updateAvailable === true && updateInfo.latest !== null) {
+        out.write(`  ▲ Update available: ${updateInfo.current} → ${updateInfo.latest}  (press u)\n\n`);
+    }
     // Budget line — real ledger data, never fabricated
     const entries = await readLedger(ctx.cwd);
     const spend = summarizeSpend(entries, ctx.clock.isoNow());
@@ -727,6 +756,10 @@ async function renderMainScreen(ctx, mutableCtx, metas, out) {
         { key: 'k', label: 'Login Codex', section: 'Auth' },
         { key: 'o', label: opencodeLabel, section: 'Auth' },
     ];
+    // [u] Update now — shown only when a newer version is actually available
+    const updateEntry = updateInfo?.updateAvailable === true && updateInfo.latest !== null
+        ? [{ key: 'u', label: `Update now (→ ${updateInfo.latest})`, section: 'Options' }]
+        : [];
     // Menu — sectioned via menu()
     out.write(menu([
         { key: 'c', label: 'Continue last conversation', section: 'Conversations' },
@@ -739,6 +772,7 @@ async function renderMainScreen(ctx, mutableCtx, metas, out) {
         { key: 's', label: 'Settings', section: 'Options' },
         { key: 'd', label: 'Doctor', section: 'Options' },
         { key: '$', label: 'Cost', section: 'Options' },
+        ...updateEntry,
         { key: 'q', label: 'Quit', section: 'Options' },
     ]) + '\n\n');
 }
@@ -766,6 +800,9 @@ export async function startMenu(ctx, out) {
     const installProviderFn = ctx.installProvider !== undefined ? ctx.installProvider : installProvider;
     const loginFn = ctx.login !== undefined ? ctx.login : runLogin;
     const detectEnvironmentFn = ctx.detectEnvironment !== undefined ? ctx.detectEnvironment : detectEnvironment;
+    const checkForUpdateFn = ctx.checkForUpdate;
+    const updateSelfFn = ctx.updateSelf;
+    const relaunchFn = ctx.relaunch;
     // Build the readLine function — either injected (for tests) or backed by a
     // real readline interface driven by the event-driven LineReader queue.
     let readLine;
@@ -803,10 +840,33 @@ export async function startMenu(ctx, out) {
             // status (e.g. codex now "ready" if the user signed in during setup).
             mutableCtx.env = await detectEnvironmentFn();
         }
+        // ---- Update check (once per launch, after onboarding) --------------------
+        // Fast path: uses the cache when fresh, so it never hangs.
+        // Injected seam allows tests to stay hermetic (no real npm registry calls).
+        let updateInfo;
+        if (checkForUpdateFn !== undefined) {
+            updateInfo = await checkForUpdateFn().catch(() => undefined);
+        }
+        // ---- Opt-in auto-update at launch ----------------------------------------
+        // Guard: only runs once; requires both the update and relaunch seams to be wired.
+        if (mutableCtx.config.autoUpdate === true &&
+            updateInfo?.updateAvailable === true &&
+            updateInfo.latest !== null &&
+            updateSelfFn !== undefined) {
+            out.write(`▲ Auto-updating ${updateInfo.current} → ${updateInfo.latest}…\n`);
+            const ok = await updateSelfFn(out).catch(() => false);
+            if (ok) {
+                if (relaunchFn !== undefined) {
+                    await relaunchFn().catch(() => 1);
+                }
+                return; // Relinquish control to the freshly-installed version.
+            }
+            out.write('Auto-update failed — continuing with current version.\n');
+        }
         // ---- B. Main screen loop -------------------------------------------------
         while (true) {
             const metas = await ctx.store.list();
-            await renderMainScreen(ctx, mutableCtx, metas, out);
+            await renderMainScreen(ctx, mutableCtx, metas, out, updateInfo);
             out.write('> ');
             const key = await readLine();
             // ---- EOF / close — exit gracefully (FIX 1: no ERR_USE_AFTER_CLOSE) ----
@@ -908,6 +968,18 @@ export async function startMenu(ctx, out) {
                 mutableCtx.env = await detectEnvironmentFn();
                 continue;
             }
+            // ---- [u] Update now -----------------------------------------------------
+            // Only active when an update is actually available and the seam is wired.
+            if (key === 'u' && updateInfo?.updateAvailable === true && updateSelfFn !== undefined) {
+                const ok = await updateSelfFn(out).catch(() => false);
+                if (ok && updateInfo.latest !== null) {
+                    out.write(`✓ Updated to ${updateInfo.latest} — restart myshell-tools to use it.\n`);
+                }
+                else if (!ok) {
+                    out.write('Update failed. Run: npm install -g myshell-tools@latest\n');
+                }
+                continue;
+            }
             // ---- [s] Settings -------------------------------------------------------
             if (key === 's') {
                 await runSettings(ctx, mutableCtx, out, readLine);