dexto 1.1.3 → 1.1.5

package/README.md

@@ -1,4 +1,4 @@
-# Dexto
+# Dexto CLI
 
 <p align="center">
   <img src="https://img.shields.io/badge/Status-Beta-yellow">
@@ -54,28 +54,60 @@ Dexto is a universal agent interface for building agentic apps—software that u
 npm install -g dexto
 
 # —or— build from source
+# this sets up dexto CLI from the cloned code
 git clone https://github.com/truffle-ai/dexto.git
-cd dexto && npm i && npm run build && npm link
+cd dexto && pnpm install && pnpm install-cli
+
 ```
 
 ## Quick Start
 
 ```bash
-# 1. Set your API key
-export OPENAI_API_KEY=your_openai_api_key_here
+# 1. Run setup workflow - this prompts for your preferred LLM and API keys and starts the interactive CLI
+dexto
 
 # 2. Try a multi-step task
 dexto "create a snake game in HTML/CSS/JS, then open it in the browser"
 
-# Optional: Launch the Web UI
+# 3. Launch the Dexto Web UI
 dexto --mode web
 ```
 
-Dexto will use filesystem tools to write code and browser tools to open it—all from a single prompt. The Web UI allows you to navigate previous conversations and experiment with different models, tools and more.
+In 2 -> Dexto will use filesystem tools to write code and browser tools to open it — all from a single prompt. The Web UI allows you to navigate previous conversations and experiment with different models, tools and more.
+
+## Agent Recipes
+
+Dexto comes with pre-built agent recipes for common use cases. Install and use them instantly:
+
+```bash
+# List available agents
+dexto list-agents
+
+# Install specific agents
+dexto install nano-banana-agent podcast-agent
+
+# Use an agent
+dexto --agent nano-banana-agent "create a futuristic cityscape with flying cars"
+dexto --agent podcast-agent "generate a podcast intro with two hosts discussing AI"
+```
+
+**Available Agents:**
+- **Nano Banana Agent** – Advanced image generation and editing using Google's Nano Banana (Gemini 2.5 Flash Image)
+- **Podcast Agent** – Advanced podcast generation using Google Gemini TTS for multi-speaker audio content
+- **Database Agent** – Demo agent for SQL queries and database operations
+- **Image Editor Agent** – Image editing and manipulation  
+- **Music Agent** – Music creation and audio processing
+- **PDF Agent** – Document analysis and conversation
+- **Product Researcher** – Product naming and branding research
+- **Triage Agent** – Demo multi-agent customer support routing system
+
+Each agent is pre-configured with the right tools, prompts, and LLM settings for its domain. No setup required—just install and start building.
+
+More ready-to-run recipes live in [`agents/`](https://github.com/truffle-ai/dexto/tree/HEAD/agents/) and the [docs site](https://docs.dexto.ai/).
 
 ## Examples & Demos
 
-### 🛒 Amazon Shopping Assistant
+### 🛒 Browser Agent: Amazon Shopping Assistant
 **Task:** `Can you go to amazon and add some snacks to my cart? I like trail mix, cheetos and maybe surprise me with something else?`
 ```bash
 # Default agent has browser tools
@@ -125,7 +157,7 @@ dexto "create a snake game in HTML/CSS/JS, then open it in the browser"
 ```bash
 dexto --agent ./agents/examples/email_slack.yml
 ```
-<img src="assets/email_slack_demo.gif" alt="Email to Slack Demo" width="600">
+<img src="https://github.com/truffle-ai/dexto/blob/HEAD/assets/email_slack_demo.gif?raw=1" alt="Email to Slack Demo" width="600">
 
 ---
 
@@ -138,8 +170,8 @@ dexto --agent ./agents/examples/email_slack.yml
 | **Headless Server** | `dexto --mode server` | REST & WebSocket APIs for agent interaction |
 | **MCP Server (Agent)** | `dexto --mode mcp` | Exposing your agent as a tool for others via stdio |
 | **MCP Server (Aggregator)** | `dexto mcp --group-servers` | Re-exposing tools from multiple MCP servers via stdio |
-| **Discord Bot** | `dexto --mode discord` | Community servers & channels ([Requires Setup](src/app/discord/README.md)) |
-| **Telegram Bot** | `dexto --mode telegram` | Mobile chat ([Requires Setup](src/app/telegram/README.md)) |
+| **Discord Bot** | `dexto --mode discord` | Community servers & channels ([Requires Setup](https://github.com/truffle-ai/dexto/blob/HEAD/packages/cli/src/discord/README.md)) |
+| **Telegram Bot** | `dexto --mode telegram` | Mobile chat ([Requires Setup](https://github.com/truffle-ai/dexto/blob/HEAD/packages/cli/src/telegram/README.md)) |
 
 Run `dexto --help` for **all flags, sub-commands, and environment variables**.
 
@@ -191,43 +223,17 @@ dexto -m gemini-2.5-pro
 
 See our [Configuration Guide](https://docs.dexto.ai/docs/category/guides/) for complete setup instructions.
 
-## Agent Recipes
-
-Dexto comes with pre-built agent recipes for common use cases. Install and use them instantly:
 
-```bash
-# List available agents
-dexto list-agents
+## Programmatic API
 
-# Install specific agents
-dexto install nano-banana-agent podcast-agent
+Install the `@dexto/core` library, and build applications with the `DextoAgent` class. Everything the CLI can do, your code can too.
 
-# Use an agent
-dexto --agent nano-banana-agent "create a futuristic cityscape with flying cars"
-dexto --agent podcast-agent "generate a podcast intro with two hosts discussing AI"
+```bash
+npm install @dexto/core
 ```
 
-**Available Agents:**
-- **Nano Banana Agent** – Advanced image generation and editing using Google's Nano Banana (Gemini 2.5 Flash Image)
-- **Podcast Agent** – Advanced podcast generation using Google Gemini TTS for multi-speaker audio content
-- **Database Agent** – Demo agent for SQL queries and database operations
-- **Image Editor Agent** – Image editing and manipulation  
-- **Music Agent** – Music creation and audio processing
-- **PDF Agent** – Document analysis and conversation
-- **Product Researcher** – Product naming and branding research
-- **Triage Agent** – Demo multi-agent customer support routing system
-
-Each agent is pre-configured with the right tools, prompts, and LLM settings for its domain. No setup required—just install and start building.
-
-More ready-to-run recipes live in [`agents/`](agents/) and the [docs site](https://docs.dexto.ai/).
-
-
-## Programmatic API
-
-Build applications with the `DextoAgent` class. Everything the CLI can do, your code can too.
-
 ```ts
-import { DextoAgent } from 'dexto';
+import { DextoAgent } from '@dexto/core';
 
 // Create and start agent
 const agent = new DextoAgent({
@@ -289,6 +295,9 @@ const currentLLM = agent.getCurrentLLMConfig();
 await agent.switchLLM({ model: 'gpt-4.1-mini' });
 await agent.switchLLM({ model: 'claude-4-sonnet-20250514' });
 
+// Switch model for a specific session id 1234
+await agent.switchLLM({ model: 'gpt-4.1-mini' }, '1234')
+
 // Get supported providers and models
 const providers = agent.getSupportedProviders();
 const models = agent.getSupportedModels();
@@ -300,7 +309,7 @@ const openaiModels = agent.getSupportedModelsForProvider('openai');
 For advanced MCP server management, use the MCPManager directly.
 
 ```typescript
-import { MCPManager } from 'dexto';
+import { MCPManager } from '@dexto/core';
 
 const manager = new MCPManager();
 
@@ -418,9 +427,23 @@ Commands:
 
 ---
 
+## Telemetry
+
+We collect anonymous usage data (no personal/sensitive info) to help improve Dexto. This includes:
+
+- Commands used
+- Command execution time
+- Error occurrences
+- System information (OS, Node version)
+- LLM Models used
+
+To opt-out:
+
+Set env variable `DEXTO_ANALYTICS_DISABLED=1` 
+
 ## Contributing
 
-We welcome contributions! Refer to our [Contributing Guide](./CONTRIBUTING.md) for more details.
+We welcome contributions! Refer to our [Contributing Guide](https://github.com/truffle-ai/dexto/blob/HEAD/CONTRIBUTING.md) for more details.
 
 ## Community & Support
 
@@ -450,4 +473,4 @@ Thanks to all these amazing people for contributing to Dexto!
 
 ## License
 
-Elastic License 2.0.  See [LICENSE](LICENSE) for full terms.
+Elastic License 2.0.  See [LICENSE](https://github.com/truffle-ai/dexto/blob/HEAD/LICENSE) for full terms.

package/dist/analytics/constants.d.ts

@@ -0,0 +1,19 @@
+export declare const DEFAULT_POSTHOG_KEY = "phc_IJHITHjBKOjDyFiVeilfdumcGniXMuLeXeiLQhYvwDW";
+export declare const DEFAULT_POSTHOG_HOST = "https://app.posthog.com";
+/**
+ * Single opt-out switch for analytics.
+ *
+ * Usage:
+ *   DEXTO_ANALYTICS_DISABLED=1 dexto ...
+ *
+ * When set to a truthy value ("1", "true", "yes"), analytics are fully disabled.
+ */
+export declare function isAnalyticsDisabled(): boolean;
+/**
+ * Generic per-command timeout (in milliseconds) used by the analytics wrapper.
+ *
+ * This does NOT terminate the command. It emits a non-terminating timeout
+ * event when the duration threshold is crossed to help diagnose long runs.
+ */
+export declare const COMMAND_TIMEOUT_MS = 120000;
+//# sourceMappingURL=constants.d.ts.map

package/dist/analytics/constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../src/analytics/constants.ts"],"names":[],"mappings":"AAIA,eAAO,MAAM,mBAAmB,oDAAoD,CAAC;AACrF,eAAO,MAAM,oBAAoB,4BAA4B,CAAC;AAE9D;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,IAAI,OAAO,CAG7C;AAED;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB,SAAS,CAAC"}

package/dist/analytics/constants.js

@@ -0,0 +1,24 @@
+// packages/cli/src/analytics/constants.ts
+// Single source for PostHog configuration.
+// Embed your public key here (safe to publish). Host can stay default.
+export const DEFAULT_POSTHOG_KEY = 'phc_IJHITHjBKOjDyFiVeilfdumcGniXMuLeXeiLQhYvwDW';
+export const DEFAULT_POSTHOG_HOST = 'https://app.posthog.com';
+/**
+ * Single opt-out switch for analytics.
+ *
+ * Usage:
+ *   DEXTO_ANALYTICS_DISABLED=1 dexto ...
+ *
+ * When set to a truthy value ("1", "true", "yes"), analytics are fully disabled.
+ */
+export function isAnalyticsDisabled() {
+    const v = process.env.DEXTO_ANALYTICS_DISABLED;
+    return typeof v === 'string' && /^(1|true|yes)$/i.test(v);
+}
+/**
+ * Generic per-command timeout (in milliseconds) used by the analytics wrapper.
+ *
+ * This does NOT terminate the command. It emits a non-terminating timeout
+ * event when the duration threshold is crossed to help diagnose long runs.
+ */
+export const COMMAND_TIMEOUT_MS = 120000; // 2 minutes (default for quick commands)

package/dist/analytics/events.d.ts

@@ -0,0 +1,112 @@
+import type { ExecutionContext } from '@dexto/core';
+export interface BaseEventContext {
+    app?: 'dexto';
+    app_version?: string;
+    node_version?: string;
+    os_platform?: NodeJS.Platform;
+    os_release?: string;
+    os_arch?: string;
+    execution_context?: ExecutionContext;
+    session_id?: string | null;
+}
+export interface CommandArgsMeta {
+    argTypes: string[];
+    positionalRaw?: string[];
+    positionalCount?: number;
+    optionKeys?: string[];
+    options?: Record<string, SanitizedOptionValue>;
+}
+export type SanitizedOptionValue = string | number | boolean | null | {
+    type: 'array';
+    length: number;
+} | {
+    type: 'object';
+};
+export type CliCommandPhase = 'start' | 'end' | 'timeout';
+interface CliCommandBaseEvent {
+    name: string;
+    phase: CliCommandPhase;
+    args?: CommandArgsMeta;
+}
+export interface CliCommandStartEvent extends CliCommandBaseEvent {
+    phase: 'start';
+}
+export interface CliCommandEndEvent extends CliCommandBaseEvent {
+    phase: 'end';
+    success: boolean;
+    durationMs: number;
+    error?: string;
+    reason?: string;
+    command?: string;
+}
+export interface CliCommandTimeoutEvent extends CliCommandBaseEvent {
+    phase: 'timeout';
+    timeoutMs: number;
+}
+export type CliCommandEvent = CliCommandStartEvent | CliCommandEndEvent | CliCommandTimeoutEvent;
+export interface SessionStartEvent {
+}
+export interface PromptEvent {
+    mode: 'cli' | 'headless';
+    provider: string;
+    model: string;
+}
+export interface SetupEvent {
+    provider: string;
+    model: string;
+    hadApiKeyBefore: boolean;
+    setupMode: 'interactive' | 'non-interactive';
+}
+export interface InstallAgentEvent {
+    agent: string;
+    status: 'installed' | 'skipped' | 'failed';
+    force: boolean;
+    injectPreferences: boolean;
+    reason?: string;
+    error_message?: string;
+}
+export interface InstallAggregateEvent {
+    requested: string[];
+    installed: string[];
+    skipped: string[];
+    failed: string[];
+    successCount: number;
+    errorCount: number;
+}
+export interface UninstallAgentEvent {
+    agent: string;
+    status: 'uninstalled' | 'failed';
+    force: boolean;
+    error_message?: string;
+}
+export interface UninstallAggregateEvent {
+    requested: string[];
+    uninstalled: string[];
+    failed: string[];
+    successCount: number;
+    errorCount: number;
+}
+export interface CreateProjectEvent {
+    provider: string;
+    providedKey: boolean;
+}
+export interface InitProjectEvent {
+    provider: string;
+    providedKey: boolean;
+}
+export interface DextoAnalyticsEventMap {
+    dexto_session_start: SessionStartEvent;
+    dexto_cli_command: CliCommandEvent;
+    dexto_prompt: PromptEvent;
+    dexto_setup: SetupEvent;
+    dexto_install_agent: InstallAgentEvent;
+    dexto_install: InstallAggregateEvent;
+    dexto_uninstall_agent: UninstallAgentEvent;
+    dexto_uninstall: UninstallAggregateEvent;
+    dexto_create: CreateProjectEvent;
+    dexto_init: InitProjectEvent;
+}
+export type AnalyticsEventName = keyof DextoAnalyticsEventMap;
+export type AnalyticsEventPayload<Name extends AnalyticsEventName> = DextoAnalyticsEventMap[Name];
+export {};
+//# sourceMappingURL=events.d.ts.map

package/dist/analytics/events.d.ts.map

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

package/dist/analytics/events.js

@@ -0,0 +1,6 @@
+// packages/cli/src/analytics/events.ts
+// Typed payload scaffolding for PostHog events emitted by the CLI.
+// These types describe the additional properties supplied when we call
+// `capture(event, properties)`. Base context (app, version, OS, execution context,
+// session_id, etc.) is merged automatically in analytics/index.ts.
+export {};

package/dist/analytics/index.d.ts

@@ -0,0 +1,37 @@
+import { AnalyticsEventName, AnalyticsEventPayload, CliCommandEndEvent, CliCommandStartEvent } from './events.js';
+interface InitOptions {
+    appVersion: string;
+}
+/**
+ * Initialize the analytics client for the CLI.
+ *
+ * - Respects DEXTO_ANALYTICS_DISABLED.
+ * - Creates/loads the anonymous distinctId and a per-process session_id.
+ * - Emits a dexto_session_start event for each process run.
+ */
+export declare function initAnalytics(opts: InitOptions): Promise<void>;
+/**
+ * Capture a single analytics event with optional properties.
+ * Automatically enriches events with base context (app/os/node/session).
+ */
+export declare function capture<Name extends AnalyticsEventName>(event: Name, properties?: AnalyticsEventPayload<Name>): void;
+/**
+ * Attempt a graceful shutdown of the analytics client, flushing queued events.
+ */
+export declare function shutdownAnalytics(): Promise<void>;
+/**
+ * Mark the start of a command for timing and emit a lightweight start event.
+ * Adds local counters as a coarse diagnostic aid.
+ */
+export declare function onCommandStart(name: string, extra?: Partial<Omit<CliCommandStartEvent, 'name' | 'phase'>>): Promise<void>;
+/**
+ * Mark the end of a command and emit a completion event with success/failure
+ * and measured duration. Accepts optional extra properties.
+ */
+export declare function onCommandEnd(name: string, success: boolean, extra?: Partial<Omit<CliCommandEndEvent, 'name' | 'phase' | 'success' | 'durationMs'>>): Promise<void>;
+/**
+ * Whether analytics are currently enabled for this process.
+ */
+export declare function getEnabled(): boolean;
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/analytics/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/analytics/index.ts"],"names":[],"mappings":"AAQA,OAAO,EACH,kBAAkB,EAClB,qBAAqB,EAErB,kBAAkB,EAClB,oBAAoB,EACvB,MAAM,aAAa,CAAC;AAErB,UAAU,WAAW;IACjB,UAAU,EAAE,MAAM,CAAC;CACtB;AAqBD;;;;;;GAMG;AACH,wBAAsB,aAAa,CAAC,IAAI,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAkCpE;AAED;;;GAGG;AACH,wBAAgB,OAAO,CAAC,IAAI,SAAS,kBAAkB,EACnD,KAAK,EAAE,IAAI,EACX,UAAU,GAAE,qBAAqB,CAAC,IAAI,CAAqC,GAC5E,IAAI,CAWN;AAED;;GAEG;AACH,wBAAsB,iBAAiB,IAAI,OAAO,CAAC,IAAI,CAAC,CAQvD;AAMD;;;GAGG;AACH,wBAAsB,cAAc,CAChC,IAAI,EAAE,MAAM,EACZ,KAAK,GAAE,OAAO,CAAC,IAAI,CAAC,oBAAoB,EAAE,MAAM,GAAG,OAAO,CAAC,CAAM,GAClE,OAAO,CAAC,IAAI,CAAC,CAYf;AAED;;;GAGG;AACH,wBAAsB,YAAY,CAC9B,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,OAAO,EAChB,KAAK,GAAE,OAAO,CAAC,IAAI,CAAC,kBAAkB,EAAE,MAAM,GAAG,OAAO,GAAG,SAAS,GAAG,YAAY,CAAC,CAAM,GAC3F,OAAO,CAAC,IAAI,CAAC,CAoBf;AAED;;GAEG;AACH,wBAAgB,UAAU,IAAI,OAAO,CAEpC"}

package/dist/analytics/index.js

@@ -0,0 +1,145 @@
+// packages/cli/src/analytics/index.ts
+import { PostHog } from 'posthog-node';
+import os from 'os';
+import { isAnalyticsDisabled, DEFAULT_POSTHOG_HOST, DEFAULT_POSTHOG_KEY } from './constants.js';
+import { loadState, saveState } from './state.js';
+import { getExecutionContext } from '@dexto/core';
+import { randomUUID } from 'crypto';
+let client = null;
+let enabled = false;
+let state = null;
+let sessionId = null;
+let appVersion = null;
+function baseProps() {
+    return {
+        app: 'dexto',
+        app_version: appVersion || 'unknown',
+        node_version: process.version,
+        os_platform: os.platform(),
+        os_release: os.release(),
+        os_arch: os.arch(),
+        execution_context: getExecutionContext(),
+        session_id: sessionId,
+    };
+}
+/**
+ * Initialize the analytics client for the CLI.
+ *
+ * - Respects DEXTO_ANALYTICS_DISABLED.
+ * - Creates/loads the anonymous distinctId and a per-process session_id.
+ * - Emits a dexto_session_start event for each process run.
+ */
+export async function initAnalytics(opts) {
+    if (enabled || client)
+        return; // idempotent
+    if (isAnalyticsDisabled()) {
+        enabled = false;
+        return;
+    }
+    // Load or create state
+    state = await loadState();
+    sessionId = randomUUID();
+    appVersion = opts.appVersion;
+    const key = process.env.DEXTO_POSTHOG_KEY ?? DEFAULT_POSTHOG_KEY;
+    const host = process.env.DEXTO_POSTHOG_HOST ?? DEFAULT_POSTHOG_HOST;
+    if (typeof key !== 'string' || !/^phc_[A-Za-z0-9]+/.test(key) || !host) {
+        enabled = false;
+        return;
+    }
+    client = new PostHog(key, {
+        host,
+        flushAt: 1,
+        flushInterval: 0,
+        disableGeoip: false,
+    });
+    enabled = true;
+    process.on('exit', () => {
+        try {
+            client?.flush?.();
+        }
+        catch {
+            // Ignore flush errors: analytics should never block process exit.
+        }
+    });
+    capture('dexto_session_start', {});
+}
+/**
+ * Capture a single analytics event with optional properties.
+ * Automatically enriches events with base context (app/os/node/session).
+ */
+export function capture(event, properties = {}) {
+    if (!enabled || !client || !state)
+        return;
+    try {
+        client.capture({
+            distinctId: state.distinctId,
+            event,
+            properties: { ...baseProps(), ...properties },
+        });
+    }
+    catch {
+        // swallow
+    }
+}
+/**
+ * Attempt a graceful shutdown of the analytics client, flushing queued events.
+ */
+export async function shutdownAnalytics() {
+    if (client) {
+        try {
+            await client.shutdown();
+        }
+        catch {
+            // ignore
+        }
+    }
+}
+const timers = new Map();
+/**
+ * Mark the start of a command for timing and emit a lightweight start event.
+ * Adds local counters as a coarse diagnostic aid.
+ */
+export async function onCommandStart(name, extra = {}) {
+    if (!enabled)
+        return;
+    timers.set(name, Date.now());
+    if (state) {
+        await saveState(state);
+    }
+    const payload = {
+        name,
+        phase: 'start',
+        ...extra,
+    };
+    capture('dexto_cli_command', payload);
+}
+/**
+ * Mark the end of a command and emit a completion event with success/failure
+ * and measured duration. Accepts optional extra properties.
+ */
+export async function onCommandEnd(name, success, extra = {}) {
+    if (!enabled)
+        return;
+    const start = timers.get(name) ?? Date.now();
+    const durationMs = Date.now() - start;
+    timers.delete(name);
+    const payload = {
+        name,
+        phase: 'end',
+        success,
+        durationMs,
+        ...extra,
+    };
+    capture('dexto_cli_command', payload);
+    if (state) {
+        state.commandRunCounts = state.commandRunCounts || {};
+        state.commandRunCounts[name] = (state.commandRunCounts[name] || 0) + 1;
+        await saveState(state);
+    }
+}
+/**
+ * Whether analytics are currently enabled for this process.
+ */
+export function getEnabled() {
+    return enabled;
+}

package/dist/analytics/state.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Shape of the persisted analytics state written to
+ * ~/.dexto/telemetry/state.json.
+ *
+ * - distinctId: Anonymous ID (UUID) for grouping events by machine.
+ * - createdAt: ISO timestamp when the state was first created.
+ * - commandRunCounts: Local counters per command for coarse diagnostics.
+ */
+export interface AnalyticsState {
+    distinctId: string;
+    createdAt: string;
+    commandRunCounts?: Record<string, number>;
+}
+/**
+ * Load the persisted analytics state, creating a new file if missing.
+ * Returns a valid state object with defaults populated.
+ */
+export declare function loadState(): Promise<AnalyticsState>;
+/**
+ * Persist the analytics state to ~/.dexto/telemetry/state.json.
+ */
+export declare function saveState(state: AnalyticsState): Promise<void>;
+//# sourceMappingURL=state.d.ts.map

package/dist/analytics/state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"state.d.ts","sourceRoot":"","sources":["../../src/analytics/state.ts"],"names":[],"mappings":"AAcA;;;;;;;GAOG;AACH,MAAM,WAAW,cAAc;IAC3B,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,gBAAgB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC7C;AAKD;;;GAGG;AACH,wBAAsB,SAAS,IAAI,OAAO,CAAC,cAAc,CAAC,CAqBzD;AAED;;GAEG;AACH,wBAAsB,SAAS,CAAC,KAAK,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAGpE"}

package/dist/analytics/state.js

@@ -0,0 +1,74 @@
+// packages/cli/src/analytics/state.ts
+import { promises as fs } from 'fs';
+import * as path from 'path';
+import os from 'os';
+import { randomUUID, createHash } from 'crypto';
+import { createRequire } from 'module';
+const requireCJS = createRequire(import.meta.url);
+// node-machine-id is CommonJS; import via createRequire to avoid ESM interop issues
+const { machineIdSync } = requireCJS('node-machine-id');
+import { getDextoGlobalPath } from '@dexto/core';
+const STATE_DIR = getDextoGlobalPath('telemetry');
+const STATE_FILE = path.join(STATE_DIR, 'state.json');
+/**
+ * Load the persisted analytics state, creating a new file if missing.
+ * Returns a valid state object with defaults populated.
+ */
+export async function loadState() {
+    try {
+        const content = await fs.readFile(STATE_FILE, 'utf8');
+        const parsed = JSON.parse(content);
+        // Validate minimal shape
+        if (!parsed.distinctId)
+            throw new Error('invalid state');
+        return {
+            distinctId: parsed.distinctId,
+            createdAt: parsed.createdAt || new Date().toISOString(),
+            commandRunCounts: parsed.commandRunCounts ?? {},
+        };
+    }
+    catch {
+        await fs.mkdir(STATE_DIR, { recursive: true });
+        const state = {
+            distinctId: computeDistinctId(),
+            createdAt: new Date().toISOString(),
+            commandRunCounts: {},
+        };
+        await saveState(state);
+        return state;
+    }
+}
+/**
+ * Persist the analytics state to ~/.dexto/telemetry/state.json.
+ */
+export async function saveState(state) {
+    await fs.mkdir(STATE_DIR, { recursive: true });
+    await fs.writeFile(STATE_FILE, JSON.stringify(state, null, 2), 'utf8');
+}
+/**
+ * Compute a stable, privacy‑safe machine identifier so identity
+ * survives ~/.dexto deletion by default.
+ *
+ * Strategy:
+ * - Prefer node-machine-id (hashed), which abstracts platform differences.
+ * - Fallback to a salted/hashed hostname.
+ * - As a last resort, generate a random UUID.
+ */
+function computeDistinctId() {
+    try {
+        // machineIdSync(true) returns a hashed, stable identifier
+        const id = machineIdSync(true);
+        if (typeof id === 'string' && id.length > 0)
+            return `DEXTO-${id}`;
+    }
+    catch {
+        // fall through to hostname hash
+    }
+    // Fallback: hash hostname to avoid exposing raw value
+    const hostname = os.hostname() || 'unknown-host';
+    const digest = createHash('sha256').update(hostname).digest('hex');
+    if (digest)
+        return `DEXTO-${digest.slice(0, 32)}`;
+    // Last resort
+    return `DEXTO-${randomUUID()}`;
+}

package/dist/analytics/wrapper.d.ts

@@ -0,0 +1,11 @@
+export declare function withAnalytics<A extends unknown[], R = unknown>(commandName: string, handler: (...args: A) => Promise<R> | R, opts?: {
+    timeoutMs?: number;
+}): (...args: A) => Promise<R>;
+export declare class ExitSignal extends Error {
+    code: number;
+    reason?: string | undefined;
+    commandName?: string | undefined;
+    constructor(code?: number, reason?: string, commandName?: string);
+}
+export declare function safeExit(commandName: string, code?: number, reason?: string): never;
+//# sourceMappingURL=wrapper.d.ts.map

package/dist/analytics/wrapper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wrapper.d.ts","sourceRoot":"","sources":["../../src/analytics/wrapper.ts"],"names":[],"mappings":"AAkDA,wBAAgB,aAAa,CAAC,CAAC,SAAS,OAAO,EAAE,EAAE,CAAC,GAAG,OAAO,EAC1D,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,CAAC,GAAG,IAAI,EAAE,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,EACvC,IAAI,CAAC,EAAE;IAAE,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,GAC9B,CAAC,GAAG,IAAI,EAAE,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,CA+D5B;AAED,qBAAa,UAAW,SAAQ,KAAK;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5B,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;gBACrB,IAAI,GAAE,MAAU,EAAE,MAAM,CAAC,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,MAAM;CAOtE;AAED,wBAAgB,QAAQ,CAAC,WAAW,EAAE,MAAM,EAAE,IAAI,GAAE,MAAU,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,KAAK,CAEtF"}