myshell-tools 2.7.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,7 +68,48 @@ 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.
+ *
+ * Accepts (case-insensitive, trimmed):
+ *   - `"y"` or `"yes"`           → true
+ *   - `"n"` or `"no"`            → false
+ *   - empty string or `null` (EOF) → `defaultYes`
+ *   - anything else              → `defaultYes` (lenient)
+ *
+ * Never throws.  Callers should display `(Y/n)` when `defaultYes` is true and
+ * `(y/N)` when `defaultYes` is false so the user knows which choice Enter gives.
+ *
+ * @param input      - The raw line from readLine(), or null on EOF.
+ * @param defaultYes - True if pressing Enter (or EOF) means yes.
+ * @returns True for yes, false for no.
+ */
+export declare function parseYesNo(input: string | null, defaultYes: boolean): boolean;
 /**
  * Return the shell alias hint the user can add to their shell profile to make
  * `myshell-tools` the default command-line assistant.