@phuetz/code-buddy 2.0.0 → 2.1.0

package/dist/utils/atomic-write.js

@@ -475,6 +475,35 @@ async function recoverJsonLines(filePath, fallback, isValid) {
 export function resetAtomicReadWarningsForTests() {
     warnedReadPaths.clear();
 }
+/**
+ * Strictly read-only JSON reader for diagnostics. Never restores, renames,
+ * chmods, creates, or writes anything — not the primary file, not `.bak`,
+ * not `.tmp.*`. Never consults recovery candidates. Callers that need the
+ * historical recovery policy must keep using `readJsonAtomicSync`.
+ */
+export function readJsonAtomicSyncReadOnly(filePath, isValid) {
+    let contents;
+    try {
+        contents = fs.readFileSync(filePath, 'utf8');
+    }
+    catch (error) {
+        return isMissing(error) ? { status: 'missing' } : { status: 'unreadable' };
+    }
+    if (!contents.trim()) {
+        return { status: 'corrupt' };
+    }
+    let value;
+    try {
+        value = JSON.parse(contents);
+    }
+    catch {
+        return { status: 'corrupt' };
+    }
+    if (isValid && !isValid(value)) {
+        return { status: 'corrupt' };
+    }
+    return { status: 'ok', value: value };
+}
 const warnedCleanupPaths = new Set();
 /**
  * Remove stale `<filePath>.tmp.*` (and legacy `<filePath>.tmp`) siblings left

package/dist/utils/bounded-output.d.ts

@@ -0,0 +1,16 @@
+/** Bounded byte storage retaining the beginning and most recent end of output. */
+export declare class BoundedOutput {
+    readonly capacity: number;
+    private head;
+    private tail;
+    private observed;
+    constructor(capacity?: number);
+    get retainedBytes(): number;
+    get omittedBytes(): number;
+    append(chunk: string | Buffer): void;
+    text(): string;
+    /** Consume the pending preview; producers can continue into a fresh bounded buffer. */
+    drain(): string;
+}
+/** A rendered byte budget, including the omission marker, for model context. */
+export declare function truncateOutput(text: string, maxBytes: number): string;

package/dist/utils/bounded-output.js

@@ -0,0 +1,63 @@
+import { StringDecoder } from 'node:string_decoder';
+/** Decode a retained UTF-8 segment without exposing a cut code point. */
+function decode(bytes) {
+    let start = 0;
+    while (start < bytes.length && (bytes[start] & 0xc0) === 0x80)
+        start++;
+    return new StringDecoder('utf8').write(bytes.subarray(start));
+}
+/** Bounded byte storage retaining the beginning and most recent end of output. */
+export class BoundedOutput {
+    capacity;
+    head = Buffer.alloc(0);
+    tail = Buffer.alloc(0);
+    observed = 0;
+    constructor(capacity = 256 * 1024) {
+        this.capacity = capacity;
+        if (!Number.isSafeInteger(capacity) || capacity < 1)
+            throw new Error('Output capacity must be a positive integer');
+    }
+    get retainedBytes() { return this.head.length + this.tail.length; }
+    get omittedBytes() { return this.observed - this.retainedBytes; }
+    append(chunk) {
+        let bytes = typeof chunk === 'string' ? Buffer.from(chunk) : chunk;
+        this.observed += bytes.length;
+        const headRemaining = Math.ceil(this.capacity / 2) - this.head.length;
+        if (headRemaining > 0) {
+            this.head = Buffer.concat([this.head, bytes.subarray(0, headRemaining)]);
+            bytes = bytes.subarray(headRemaining);
+        }
+        const tailCapacity = Math.floor(this.capacity / 2);
+        if (tailCapacity > 0 && bytes.length > 0) {
+            this.tail = bytes.length >= tailCapacity
+                ? Buffer.from(bytes.subarray(-tailCapacity))
+                : Buffer.concat([this.tail.subarray(Math.max(0, this.tail.length + bytes.length - tailCapacity)), bytes]);
+        }
+    }
+    text() {
+        if (!this.omittedBytes)
+            return decode(Buffer.concat([this.head, this.tail]));
+        return `${decode(this.head)}\n[... ${this.omittedBytes} bytes omitted ...]\n${decode(this.tail)}`;
+    }
+    /** Consume the pending preview; producers can continue into a fresh bounded buffer. */
+    drain() {
+        const result = this.text();
+        this.head = Buffer.alloc(0);
+        this.tail = Buffer.alloc(0);
+        this.observed = 0;
+        return result;
+    }
+}
+/** A rendered byte budget, including the omission marker, for model context. */
+export function truncateOutput(text, maxBytes) {
+    if (!Number.isSafeInteger(maxBytes) || maxBytes < 1)
+        throw new Error('Output budget must be a positive integer');
+    if (Buffer.byteLength(text) <= maxBytes)
+        return text;
+    if (maxBytes < 80)
+        return decode(Buffer.from(text).subarray(0, maxBytes));
+    const buffer = new BoundedOutput(maxBytes - 80);
+    buffer.append(text);
+    return buffer.text();
+}
+//# sourceMappingURL=bounded-output.js.map

package/dist/utils/device-store-file.d.ts

@@ -0,0 +1,4 @@
+/** Shared envelope: legacy SSH/ADB nodes and Android authentication coexist. */
+export declare function readDeviceStoreFile(file: string): Record<string, unknown>;
+/** Cross-process exclusion for the local CLI and server. Busy/crashed locks fail closed. */
+export declare function updateDeviceStoreFile<T>(file: string, update: (data: Record<string, unknown>) => T): T;

package/dist/utils/device-store-file.js

@@ -0,0 +1,40 @@
+import { mkdirSync, readFileSync, rmdirSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { writeJsonAtomicSync } from './atomic-write.js';
+/** Shared envelope: legacy SSH/ADB nodes and Android authentication coexist. */
+export function readDeviceStoreFile(file) {
+    try {
+        const value = JSON.parse(readFileSync(file, 'utf8'));
+        if (!value || typeof value !== 'object' || Array.isArray(value)) {
+            throw new Error('Invalid device store');
+        }
+        return value;
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return {};
+        // Never recover a stale backup: that could resurrect a revoked key.
+        throw new Error('Device store unavailable');
+    }
+}
+/** Cross-process exclusion for the local CLI and server. Busy/crashed locks fail closed. */
+export function updateDeviceStoreFile(file, update) {
+    mkdirSync(dirname(file), { recursive: true, mode: 0o700 });
+    const lock = `${file}.lock`;
+    try {
+        mkdirSync(lock, { mode: 0o700 });
+    }
+    catch {
+        throw new Error('Device store unavailable');
+    }
+    try {
+        const data = readDeviceStoreFile(file);
+        const result = update(data);
+        writeJsonAtomicSync(file, data, { mode: 0o600 });
+        return result;
+    }
+    finally {
+        rmdirSync(lock);
+    }
+}
+//# sourceMappingURL=device-store-file.js.map

package/dist/utils/export-manager.d.ts

@@ -94,6 +94,15 @@ export declare class ExportManager extends EventEmitter {
         filePath?: string;
         error?: string;
     }>;
+    /**
+     * Export an in-memory conversation (e.g. the live CLI transcript) to a file,
+     * with the same redaction and formatting as session exports.
+     */
+    exportConversationData(data: ConversationExport, format: ExportFormat, options?: Partial<ExportOptions>, prefix?: string): Promise<{
+        success: boolean;
+        filePath?: string;
+        error?: string;
+    }>;
     /**
      * Export session to string
      */

package/dist/utils/export-manager.js

@@ -511,6 +511,25 @@ export class ExportManager extends EventEmitter {
             return { success: false, error: errorMsg };
         }
     }
+    /**
+     * Export an in-memory conversation (e.g. the live CLI transcript) to a file,
+     * with the same redaction and formatting as session exports.
+     */
+    async exportConversationData(data, format, options = {}, prefix = 'conversation') {
+        try {
+            const content = this.formatExport(data, format, options);
+            const filePath = path.join(this.outputDir, this.generateFilename(prefix, format));
+            await this.ensureOutputDir();
+            await fs.writeFile(filePath, content, 'utf-8');
+            this.emit('conversation:exported', { filePath, format });
+            return { success: true, filePath };
+        }
+        catch (error) {
+            const errorMsg = error instanceof Error ? error.message : 'Unknown error';
+            this.emit('error', error);
+            return { success: false, error: errorMsg };
+        }
+    }
     /**
      * Export session to string
      */

package/dist/utils/first-use-hints.d.ts

@@ -0,0 +1,25 @@
+/**
+ * First-use hints (comparatif plan P4, optional part).
+ *
+ * A short contextual tip shown ONCE per profile, the first time the user meets
+ * a surprising behaviour: a command unavailable on this surface, a message
+ * queued behind a running turn, a tool output shortened for the model (exact
+ * output recoverable through restore_context).
+ *
+ * Persistence: one marker file per hint under ~/.codebuddy/hints/ created with
+ * O_EXCL, so concurrent processes (CLI + Cowork) show a hint at most once.
+ * `CODEBUDDY_HINTS=off` disables every hint. Never throws: an unwritable
+ * profile means no hint rather than a repeated one.
+ */
+export type FirstUseHintId = 'surface_unavailable' | 'message_queued' | 'restore_context';
+export declare const FIRST_USE_HINTS: Readonly<Record<FirstUseHintId, {
+    en: string;
+    fr: string;
+}>>;
+export declare function firstUseHintsDir(): string;
+/**
+ * Return the hint text the first time `id` is requested in this profile, then
+ * null forever. The marker is created before the text is returned.
+ */
+export declare function takeFirstUseHint(id: FirstUseHintId, lang?: 'en' | 'fr', dir?: string): string | null;
+export declare function resetFirstUseHints(dir?: string): void;

package/dist/utils/first-use-hints.js

@@ -0,0 +1,58 @@
+/**
+ * First-use hints (comparatif plan P4, optional part).
+ *
+ * A short contextual tip shown ONCE per profile, the first time the user meets
+ * a surprising behaviour: a command unavailable on this surface, a message
+ * queued behind a running turn, a tool output shortened for the model (exact
+ * output recoverable through restore_context).
+ *
+ * Persistence: one marker file per hint under ~/.codebuddy/hints/ created with
+ * O_EXCL, so concurrent processes (CLI + Cowork) show a hint at most once.
+ * `CODEBUDDY_HINTS=off` disables every hint. Never throws: an unwritable
+ * profile means no hint rather than a repeated one.
+ */
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+export const FIRST_USE_HINTS = Object.freeze({
+    surface_unavailable: {
+        en: 'Tip: greyed-out commands are not available on this surface yet; run them in the terminal with `buddy`.',
+        fr: 'Astuce : les commandes grisées ne sont pas encore pilotables ici ; lance-les dans un terminal avec `buddy`.',
+    },
+    message_queued: {
+        en: 'Tip: this message was queued while Buddy was busy and runs now; messages sent during a turn always run in order.',
+        fr: 'Astuce : un message envoyé pendant un tour est mis en file et partira à la fin du tour en cours.',
+    },
+    restore_context: {
+        en: 'Tip: long tool outputs are shortened for the model; the exact output stays recoverable with restore_context.',
+        fr: 'Astuce : les longues sorties d’outils sont raccourcies pour le modèle ; la sortie exacte reste récupérable avec restore_context.',
+    },
+});
+export function firstUseHintsDir() {
+    return process.env.CODEBUDDY_HINTS_DIR || path.join(os.homedir(), '.codebuddy', 'hints');
+}
+/**
+ * Return the hint text the first time `id` is requested in this profile, then
+ * null forever. The marker is created before the text is returned.
+ */
+export function takeFirstUseHint(id, lang = 'en', dir = firstUseHintsDir()) {
+    if ((process.env.CODEBUDDY_HINTS ?? '').toLowerCase() === 'off')
+        return null;
+    const hint = FIRST_USE_HINTS[id];
+    if (!hint)
+        return null;
+    try {
+        fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+        fs.writeFileSync(path.join(dir, id), `${new Date().toISOString()}\n`, { flag: 'wx', mode: 0o600 });
+        return hint[lang];
+    }
+    catch {
+        return null;
+    }
+}
+export function resetFirstUseHints(dir = firstUseHintsDir()) {
+    for (const id of Object.keys(FIRST_USE_HINTS)) {
+        fs.rmSync(path.join(dir, id), { force: true });
+    }
+}
+//# sourceMappingURL=first-use-hints.js.map

package/dist/utils/history-manager.js

@@ -29,7 +29,7 @@ export class HistoryManager {
     };
     static DEFAULT_CONFIG = {
         maxEntries: 1000, // Increased default limit
-        historyFile: path.join(os.homedir(), '.codebuddy', 'history.json'),
+        get historyFile() { return path.join(os.homedir(), '.codebuddy', 'history.json'); },
         excludePrefixes: [], // Include all commands by default
         includeSlashCommands: true, // Include slash commands
     };

package/dist/utils/update-notifier.js

@@ -3,7 +3,7 @@
  *
  * Checks for new versions and notifies users (mistral-vibe style).
  */
-import { existsSync, readFileSync } from 'fs';
+import { readFileSync } from 'fs';
 import { join } from 'path';
 import { homedir } from 'os';
 import https from 'https';
@@ -24,27 +24,17 @@ const DEFAULT_CONFIG = {
  */
 function getCurrentVersion() {
     try {
-        // Try to find package.json from various locations
-        // Works in both local dev and npm global install
-        const possiblePaths = [
-            // Local development or npx
-            join(process.cwd(), 'package.json'),
-            // npm global install (node_modules/@phuetz/code-buddy/package.json)
-            join(process.execPath, '..', '..', 'lib', 'node_modules', '@phuetz', 'code-buddy', 'package.json'),
-        ];
-        for (const pkgPath of possiblePaths) {
-            if (existsSync(pkgPath)) {
-                const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
-                if (pkg.name?.includes('code-buddy')) {
-                    return pkg.version || '0.0.0';
-                }
-            }
+        // Resolve our own manifest in both src/utils and dist/utils. The caller's
+        // working directory and Node executable do not identify a global npm install.
+        const pkg = JSON.parse(readFileSync(new URL('../../package.json', import.meta.url), 'utf-8'));
+        if (pkg.name === '@phuetz/code-buddy' && typeof pkg.version === 'string' && pkg.version.trim()) {
+            return pkg.version;
         }
-        return '0.0.0';
     }
     catch {
-        return '0.0.0';
+        // An unknown installed version must never produce a fictitious upgrade.
     }
+    return null;
 }
 /**
  * Fetch latest version from npm registry
@@ -147,6 +137,10 @@ export class UpdateNotifier {
             return null;
         }
         const currentVersion = getCurrentVersion();
+        if (!currentVersion) {
+            this.updateInfo = null;
+            return null;
+        }
         // Check cache first
         const cache = loadCache();
         if (cache && !shouldCheckForUpdates(this.config)) {
@@ -184,6 +178,10 @@ export class UpdateNotifier {
      */
     async forceCheck() {
         const currentVersion = getCurrentVersion();
+        if (!currentVersion) {
+            this.updateInfo = null;
+            return null;
+        }
         const latestVersion = await fetchLatestVersion(this.config.packageName, this.config.registryUrl);
         if (!latestVersion) {
             return null;

package/dist/wizard/environment-detection.d.ts

@@ -54,6 +54,8 @@ export declare function detectOllama(): Promise<DetectedCapability>;
 export declare function detectLmStudio(): Promise<DetectedCapability>;
 /** Check the ChatGPT (Codex) OAuth credential file. */
 export declare function detectChatGptOAuth(): Promise<DetectedCapability>;
+/** Offline variant: credential presence only, never refreshes tokens. */
+export declare function detectChatGptOAuthOffline(): Promise<DetectedCapability>;
 /** Check the xAI (Grok) OAuth credential file. */
 export declare function detectXaiOAuth(): Promise<DetectedCapability>;
 /** Report API keys present in the environment (not billed to us, so free:false). */
@@ -62,6 +64,8 @@ export declare function detectApiKeys(): DetectedCapability[];
  * One call to learn everything the setup surfaces need. Free local/OAuth probes
  * run in parallel; the API-key scan is synchronous.
  */
-export declare function detectEnvironment(): Promise<EnvironmentSnapshot>;
+export declare function detectEnvironment(options?: {
+    offline?: boolean;
+}): Promise<EnvironmentSnapshot>;
 /** Compact human summary of what was detected — used by wizard + doctor. */
 export declare function renderDetectionSummary(snapshot: EnvironmentSnapshot): string;

package/dist/wizard/environment-detection.js

@@ -121,6 +121,40 @@ export async function detectChatGptOAuth() {
         return base;
     }
 }
+/** Offline variant: credential presence only, never refreshes tokens. */
+export async function detectChatGptOAuthOffline() {
+    const base = {
+        id: 'chatgpt',
+        label: 'ChatGPT subscription (OAuth, $0)',
+        kind: 'oauth',
+        free: true,
+        available: false,
+        detail: 'not signed in',
+        setupCommand: 'buddy login',
+    };
+    try {
+        const { hasCodexCredentials } = await import('../providers/codex-oauth.js');
+        if (!hasCodexCredentials())
+            return base;
+        return { ...base, available: true, detail: 'credentials present (not verified offline)', setupCommand: undefined };
+    }
+    catch {
+        return base;
+    }
+}
+function notProbedLocalRuntime(id, label, rawHost, setupCommand) {
+    const host = normalizeHost(rawHost);
+    return Promise.resolve({
+        id,
+        label,
+        kind: 'local',
+        free: true,
+        available: false,
+        detail: 'not probed (--offline)',
+        baseURL: `${host}/v1`,
+        setupCommand,
+    });
+}
 /** Check the xAI (Grok) OAuth credential file. */
 export async function detectXaiOAuth() {
     const base = {
@@ -167,13 +201,21 @@ export function detectApiKeys() {
  * One call to learn everything the setup surfaces need. Free local/OAuth probes
  * run in parallel; the API-key scan is synchronous.
  */
-export async function detectEnvironment() {
-    const [ollama, lmstudio, chatgpt, xai] = await Promise.all([
-        detectOllama(),
-        detectLmStudio(),
-        detectChatGptOAuth(),
-        detectXaiOAuth(),
-    ]);
+export async function detectEnvironment(options = {}) {
+    // Offline: no HTTP probe and no OAuth refresh — only local credential files are read.
+    const [ollama, lmstudio, chatgpt, xai] = await Promise.all(options.offline
+        ? [
+            notProbedLocalRuntime('ollama', 'Ollama (local, $0)', process.env.OLLAMA_HOST || OLLAMA_DEFAULT_HOST, 'ollama serve'),
+            notProbedLocalRuntime('lmstudio', 'LM Studio (local, $0)', process.env.LMSTUDIO_HOST || LMSTUDIO_DEFAULT_HOST, 'Start the LM Studio local server'),
+            detectChatGptOAuthOffline(),
+            detectXaiOAuth(),
+        ]
+        : [
+            detectOllama(),
+            detectLmStudio(),
+            detectChatGptOAuth(),
+            detectXaiOAuth(),
+        ]);
     const apiKeys = detectApiKeys();
     const capabilities = [ollama, lmstudio, chatgpt, xai, ...apiKeys];
     // Free path priority: a local Ollama that actually has a model → ChatGPT

package/dist/wizard/onboarding.d.ts

@@ -1,3 +1,4 @@
+import * as readline from 'readline';
 import { type EnvironmentSnapshot } from './environment-detection.js';
 export interface OnboardingResult {
     provider: string;
@@ -47,7 +48,7 @@ export declare const ONBOARDING_PHASES: OnboardingPhase[];
  *   - an entered API key → encrypted credential store (never plaintext in settings),
  *     plus `process.env[envVar]` so the current process resolves immediately.
  *   - ollama → default `OLLAMA_HOST` so auto-detection picks it up.
- * All writes are best-effort; the wizard summary still prints on failure.
+ * Persistence errors propagate so the wizard cannot report a false success.
  */
 export declare function persistProviderSelection(guide: OnboardingProviderGuide, model: string, apiKey: string): Promise<void>;
 export declare const PROJECT_FOLDER_QUESTION = "Which project folder should Code Buddy use?";
@@ -67,4 +68,7 @@ export declare function renderCapabilitiesFooter(): string;
  *  recommended free path at index 0. Availability annotations are appended to
  *  the label so the newcomer sees "(detected)" without extra prose. */
 export declare function orderGuidesByDetection(snapshot: EnvironmentSnapshot): OnboardingProviderGuide[];
+/** Offer to run the isolated 60-second demo right after setup — ending the
+ *  wizard on proof (a green test), not prose. */
+export declare function offerOnboardingDemo(rl: readline.Interface, result: OnboardingResult): Promise<void>;
 export declare function runOnboarding(): Promise<OnboardingResult | null>;