@cephalization/phoenix-insight 0.1.0

package/dist/commands/px-fetch-more-spans.js

@@ -0,0 +1,98 @@
+import { withErrorHandling } from "../snapshot/client.js";
+/**
+ * Fetches additional spans for a specific project on-demand
+ *
+ * @param client - Phoenix client instance
+ * @param mode - Execution mode for file operations
+ * @param options - Options for fetching spans
+ */
+export async function fetchMoreSpans(client, mode, options) {
+    const { project, limit, startTime, endTime } = options;
+    await withErrorHandling(async () => {
+        // Try to read existing metadata to get the last cursor
+        let existingMetadata = null;
+        let existingSpans = [];
+        try {
+            const metadataResult = await mode.exec(`cat /phoenix/projects/${project}/spans/metadata.json`);
+            if (metadataResult.exitCode === 0 && metadataResult.stdout) {
+                existingMetadata = JSON.parse(metadataResult.stdout);
+            }
+        }
+        catch (error) {
+            // Metadata doesn't exist, that's okay
+        }
+        // Try to read existing spans
+        try {
+            const spansResult = await mode.exec(`cat /phoenix/projects/${project}/spans/index.jsonl`);
+            if (spansResult.exitCode === 0 && spansResult.stdout) {
+                existingSpans = spansResult.stdout
+                    .trim()
+                    .split("\n")
+                    .filter((line) => line.length > 0)
+                    .map((line) => JSON.parse(line));
+            }
+        }
+        catch (error) {
+            // Spans file doesn't exist, that's okay
+        }
+        // Fetch new spans
+        const newSpans = [];
+        let cursor = existingMetadata?.lastCursor ?? null;
+        let totalFetched = 0;
+        while (totalFetched < limit) {
+            const query = {
+                limit: Math.min(100, limit - totalFetched), // Fetch in chunks of 100
+            };
+            if (cursor) {
+                query.cursor = cursor;
+            }
+            if (startTime) {
+                query.start_time =
+                    startTime instanceof Date ? startTime.toISOString() : startTime;
+            }
+            if (endTime) {
+                query.end_time =
+                    endTime instanceof Date ? endTime.toISOString() : endTime;
+            }
+            const response = await client.GET("/v1/projects/{project_identifier}/spans", {
+                params: {
+                    path: {
+                        project_identifier: project,
+                    },
+                    query,
+                },
+            });
+            if (response.error)
+                throw response.error;
+            const data = response.data?.data ?? [];
+            newSpans.push(...data);
+            totalFetched += data.length;
+            cursor = response.data?.next_cursor ?? null;
+            // Stop if there's no more data
+            if (!cursor || data.length === 0) {
+                break;
+            }
+        }
+        // Combine existing and new spans
+        const allSpans = [...existingSpans, ...newSpans];
+        // Write updated spans to JSONL file
+        const jsonlContent = allSpans
+            .map((span) => JSON.stringify(span))
+            .join("\n");
+        await mode.writeFile(`/phoenix/projects/${project}/spans/index.jsonl`, jsonlContent);
+        // Update metadata
+        const metadata = {
+            project,
+            spanCount: allSpans.length,
+            startTime: startTime instanceof Date
+                ? startTime.toISOString()
+                : (startTime ?? null),
+            endTime: endTime instanceof Date ? endTime.toISOString() : (endTime ?? null),
+            snapshotTime: new Date().toISOString(),
+            lastCursor: cursor,
+        };
+        await mode.writeFile(`/phoenix/projects/${project}/spans/metadata.json`, JSON.stringify(metadata, null, 2));
+        console.log(`Fetched ${newSpans.length} additional spans for project "${project}"`);
+        console.log(`Total spans for project: ${allSpans.length}`);
+    }, `fetching more spans for project ${project}`);
+}

package/dist/commands/px-fetch-more-trace.js

@@ -0,0 +1,110 @@
+import { withErrorHandling } from "../snapshot/client.js";
+/**
+ * Fetches all spans for a specific trace ID
+ *
+ * @param client - Phoenix client instance
+ * @param mode - Execution mode for file operations
+ * @param options - Options for fetching trace
+ */
+export async function fetchMoreTrace(client, mode, options) {
+    const { traceId, project } = options;
+    await withErrorHandling(async () => {
+        // First, check if the project exists in our snapshot
+        const projectsResult = await mode.exec("cat /phoenix/projects/index.jsonl");
+        if (projectsResult.exitCode !== 0 || !projectsResult.stdout) {
+            console.error("No projects found in snapshot. Run a snapshot first.");
+            return;
+        }
+        const projectNames = projectsResult.stdout
+            .trim()
+            .split("\n")
+            .filter((line) => line.length > 0)
+            .map((line) => JSON.parse(line).name);
+        if (!projectNames.includes(project)) {
+            console.error(`Project "${project}" not found. Available projects: ${projectNames.join(", ")}`);
+            return;
+        }
+        // Fetch all spans that belong to this trace
+        const traceSpans = [];
+        let cursor = null;
+        let totalFetched = 0;
+        console.log(`Fetching trace ${traceId} from project "${project}"...`);
+        // We need to fetch spans in batches and filter by trace_id
+        // Since the API doesn't support direct trace_id filtering
+        while (true) {
+            const query = {
+                limit: 100, // Fetch in chunks
+            };
+            if (cursor) {
+                query.cursor = cursor;
+            }
+            const response = await client.GET("/v1/projects/{project_identifier}/spans", {
+                params: {
+                    path: {
+                        project_identifier: project,
+                    },
+                    query,
+                },
+            });
+            if (response.error)
+                throw response.error;
+            const data = response.data?.data ?? [];
+            totalFetched += data.length;
+            // Filter spans that belong to our trace
+            const matchingSpans = data.filter((span) => span.context.trace_id === traceId);
+            traceSpans.push(...matchingSpans);
+            cursor = response.data?.next_cursor ?? null;
+            // Stop if we found spans for the trace or no more data
+            if (traceSpans.length > 0 || !cursor || data.length === 0) {
+                // If we found some spans, continue until we have all spans from the trace
+                // This is because trace spans might be spread across multiple pages
+                if (traceSpans.length > 0 && cursor && data.length > 0) {
+                    console.log(`Found ${traceSpans.length} spans so far, continuing search...`);
+                    continue;
+                }
+                break;
+            }
+            // Show progress for large datasets
+            if (totalFetched % 1000 === 0) {
+                console.log(`Searched ${totalFetched} spans so far...`);
+            }
+        }
+        if (traceSpans.length === 0) {
+            console.log(`No spans found for trace ${traceId} in project "${project}"`);
+            console.log(`Searched through ${totalFetched} spans. The trace might not exist or might be in a different project.`);
+            return;
+        }
+        // Sort spans by start_time to show them in order
+        traceSpans.sort((a, b) => new Date(a.start_time).getTime() - new Date(b.start_time).getTime());
+        // Write trace spans to a dedicated file
+        const jsonlContent = traceSpans
+            .map((span) => JSON.stringify(span))
+            .join("\n");
+        const traceDir = `/phoenix/traces/${traceId}`;
+        await mode.writeFile(`${traceDir}/spans.jsonl`, jsonlContent);
+        // Create trace metadata
+        const rootSpan = traceSpans.find((span) => !span.parent_id);
+        const firstSpan = traceSpans[0];
+        const lastSpan = traceSpans[traceSpans.length - 1];
+        const metadata = {
+            traceId,
+            project,
+            spanCount: traceSpans.length,
+            rootSpan: rootSpan ? { id: rootSpan.id, name: rootSpan.name } : null,
+            startTime: firstSpan?.start_time || null,
+            endTime: lastSpan?.end_time || null,
+            duration: firstSpan && lastSpan
+                ? new Date(lastSpan.end_time).getTime() -
+                    new Date(firstSpan.start_time).getTime()
+                : 0,
+            snapshotTime: new Date().toISOString(),
+        };
+        await mode.writeFile(`${traceDir}/metadata.json`, JSON.stringify(metadata, null, 2));
+        console.log(`\nSuccessfully fetched trace ${traceId}:`);
+        console.log(`- Project: ${project}`);
+        console.log(`- Spans: ${traceSpans.length}`);
+        console.log(`- Root span: ${rootSpan?.name || "Unknown"}`);
+        console.log(`- Duration: ${(metadata.duration / 1000).toFixed(2)} seconds`);
+        console.log(`\nTrace data saved to: ${traceDir}/`);
+    }, `fetching trace ${traceId}`);
+}

package/dist/config/index.js

@@ -0,0 +1,165 @@
+/**
+ * Config singleton module for Phoenix Insight CLI
+ *
+ * Provides centralized configuration management with priority-based merging:
+ * 1. Config file (lowest priority)
+ * 2. Environment variables
+ * 3. CLI arguments (highest priority)
+ */
+import { configSchema, getDefaultConfig } from "./schema.js";
+import { getConfigPath, loadConfigFile, validateConfig, createDefaultConfig, setCliConfigPath, } from "./loader.js";
+/**
+ * Module-level storage for the initialized config singleton
+ */
+let configInstance = null;
+/**
+ * Environment variable mappings to config keys
+ */
+const ENV_VAR_MAPPINGS = {
+    PHOENIX_BASE_URL: "baseUrl",
+    PHOENIX_API_KEY: "apiKey",
+    PHOENIX_INSIGHT_LIMIT: "limit",
+    PHOENIX_INSIGHT_STREAM: "stream",
+    PHOENIX_INSIGHT_MODE: "mode",
+    PHOENIX_INSIGHT_REFRESH: "refresh",
+    PHOENIX_INSIGHT_TRACE: "trace",
+};
+/**
+ * Parse environment variable value to appropriate type
+ */
+function parseEnvValue(key, value) {
+    switch (key) {
+        case "baseUrl":
+        case "apiKey":
+            return value;
+        case "limit":
+            const num = parseInt(value, 10);
+            return isNaN(num) ? undefined : num;
+        case "stream":
+        case "refresh":
+        case "trace":
+            return value.toLowerCase() === "true" || value === "1";
+        case "mode":
+            if (value === "sandbox" || value === "local") {
+                return value;
+            }
+            return undefined;
+        default:
+            return value;
+    }
+}
+/**
+ * Get config values from environment variables
+ */
+function getEnvConfig() {
+    const envConfig = {};
+    for (const [envVar, configKey] of Object.entries(ENV_VAR_MAPPINGS)) {
+        const value = process.env[envVar];
+        if (value !== undefined) {
+            const parsed = parseEnvValue(configKey, value);
+            if (parsed !== undefined) {
+                envConfig[configKey] = parsed;
+            }
+        }
+    }
+    return envConfig;
+}
+/**
+ * Convert CLI args to config format
+ */
+function cliArgsToConfig(cliArgs) {
+    const config = {};
+    if (cliArgs.baseUrl !== undefined) {
+        config.baseUrl = cliArgs.baseUrl;
+    }
+    if (cliArgs.apiKey !== undefined) {
+        config.apiKey = cliArgs.apiKey;
+    }
+    if (cliArgs.limit !== undefined) {
+        config.limit = cliArgs.limit;
+    }
+    if (cliArgs.stream !== undefined) {
+        config.stream = cliArgs.stream;
+    }
+    if (cliArgs.local !== undefined) {
+        // CLI uses --local flag, config uses mode
+        config.mode = cliArgs.local ? "local" : "sandbox";
+    }
+    if (cliArgs.refresh !== undefined) {
+        config.refresh = cliArgs.refresh;
+    }
+    if (cliArgs.trace !== undefined) {
+        config.trace = cliArgs.trace;
+    }
+    return config;
+}
+/**
+ * Initialize the configuration singleton
+ *
+ * Merges configuration from multiple sources with the following priority:
+ * 1. Config file (lowest priority)
+ * 2. Environment variables
+ * 3. CLI arguments (highest priority)
+ *
+ * @param cliArgs - CLI arguments from Commander
+ * @returns The initialized configuration
+ */
+export async function initializeConfig(cliArgs = {}) {
+    // Set CLI config path if provided (for getConfigPath to use)
+    if (cliArgs.config) {
+        setCliConfigPath(cliArgs.config);
+    }
+    // Get config file path
+    const { path: configPath, isDefault } = getConfigPath();
+    // Try to create default config if it doesn't exist (only for default path)
+    if (isDefault) {
+        await createDefaultConfig(configPath, isDefault);
+    }
+    // Load config file
+    const fileConfig = await loadConfigFile(configPath);
+    // Validate file config (returns defaults if null/invalid)
+    const validatedFileConfig = validateConfig(fileConfig);
+    // Get environment config
+    const envConfig = getEnvConfig();
+    // Get CLI config
+    const cliConfig = cliArgsToConfig(cliArgs);
+    // Merge configs: file < env < cli
+    const mergedConfig = {
+        ...validatedFileConfig,
+        ...envConfig,
+        ...cliConfig,
+    };
+    // Final validation with Zod
+    const result = configSchema.safeParse(mergedConfig);
+    if (result.success) {
+        configInstance = result.data;
+    }
+    else {
+        // Log validation issues as warnings
+        result.error.issues.forEach((issue) => {
+            console.warn(`Warning: Config validation error at '${issue.path.join(".")}': ${issue.message}`);
+        });
+        // Fall back to defaults
+        configInstance = getDefaultConfig();
+    }
+    return configInstance;
+}
+/**
+ * Get the initialized configuration
+ *
+ * @throws Error if config has not been initialized via initializeConfig()
+ * @returns The configuration object
+ */
+export function getConfig() {
+    if (configInstance === null) {
+        throw new Error("Config not initialized. Call initializeConfig() first before using getConfig().");
+    }
+    return configInstance;
+}
+/**
+ * Reset the config singleton (useful for testing)
+ */
+export function resetConfig() {
+    configInstance = null;
+    setCliConfigPath(undefined);
+}

package/dist/config/loader.js

@@ -0,0 +1,141 @@
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import * as os from "node:os";
+import { configSchema, getDefaultConfig } from "./schema.js";
+/**
+ * Default config directory and file path
+ */
+const DEFAULT_CONFIG_DIR = path.join(os.homedir(), ".phoenix-insight");
+const DEFAULT_CONFIG_FILE = path.join(DEFAULT_CONFIG_DIR, "config.json");
+/**
+ * Module-level storage for CLI args passed from commander
+ * This is set externally before getConfigPath is called
+ */
+let cliConfigPath;
+/**
+ * Set the CLI config path (called from CLI parsing)
+ */
+export function setCliConfigPath(configPath) {
+    cliConfigPath = configPath;
+}
+/**
+ * Get the config file path based on priority:
+ * 1. CLI argument (--config)
+ * 2. Environment variable (PHOENIX_INSIGHT_CONFIG)
+ * 3. Default path (~/.phoenix-insight/config.json)
+ *
+ * @returns The path to the config file and whether it's the default path
+ */
+export function getConfigPath() {
+    // Priority 1: CLI argument
+    if (cliConfigPath) {
+        return { path: cliConfigPath, isDefault: false };
+    }
+    // Priority 2: Environment variable
+    const envConfigPath = process.env.PHOENIX_INSIGHT_CONFIG;
+    if (envConfigPath) {
+        return { path: envConfigPath, isDefault: false };
+    }
+    // Priority 3: Default path
+    return { path: DEFAULT_CONFIG_FILE, isDefault: true };
+}
+/**
+ * Load and parse a config file from disk
+ *
+ * @param configPath - Path to the config file
+ * @returns Parsed JSON object or null if file not found
+ * @throws Error if file exists but cannot be parsed as JSON
+ */
+export async function loadConfigFile(configPath) {
+    try {
+        const content = await fs.readFile(configPath, "utf-8");
+        return JSON.parse(content);
+    }
+    catch (error) {
+        // File not found is expected - return null
+        if (error instanceof Error && "code" in error && error.code === "ENOENT") {
+            return null;
+        }
+        // JSON parse errors should be reported
+        if (error instanceof SyntaxError) {
+            console.warn(`Warning: Config file at ${configPath} contains invalid JSON: ${error.message}`);
+            return null;
+        }
+        // Other errors (permissions, etc.) - warn and return null
+        console.warn(`Warning: Could not read config file at ${configPath}: ${error instanceof Error ? error.message : String(error)}`);
+        return null;
+    }
+}
+/**
+ * Validate a raw config object against the schema
+ * Returns validated config or defaults if validation fails
+ *
+ * @param raw - Raw config object (or null/undefined)
+ * @returns Validated config with defaults applied
+ */
+export function validateConfig(raw) {
+    // If no raw config, return defaults
+    if (!raw) {
+        return getDefaultConfig();
+    }
+    try {
+        // Parse with Zod schema - this applies defaults for missing fields
+        return configSchema.parse(raw);
+    }
+    catch (error) {
+        // Log validation errors as warnings
+        if (error instanceof Error && "issues" in error) {
+            // Zod error with issues array
+            const zodError = error;
+            zodError.issues.forEach((issue) => {
+                console.warn(`Warning: Config validation error at '${issue.path.join(".")}': ${issue.message}`);
+            });
+        }
+        else {
+            console.warn(`Warning: Config validation failed: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        // Return defaults on validation failure
+        return getDefaultConfig();
+    }
+}
+/**
+ * Create a default config file at the given path
+ * Only creates the file if it doesn't already exist
+ * Only triggers for the default path, not custom paths
+ *
+ * @param configPath - Path where to create the config file
+ * @param isDefault - Whether this is the default path (only create if true)
+ * @returns true if file was created, false otherwise
+ */
+export async function createDefaultConfig(configPath, isDefault) {
+    // Only create default config for the default path
+    if (!isDefault) {
+        return false;
+    }
+    try {
+        // Check if file already exists
+        await fs.access(configPath);
+        // File exists, don't overwrite
+        return false;
+    }
+    catch {
+        // File doesn't exist, create it
+    }
+    try {
+        // Create directory if needed
+        const configDir = path.dirname(configPath);
+        await fs.mkdir(configDir, { recursive: true });
+        // Get default config and write it
+        const defaultConfig = getDefaultConfig();
+        const content = JSON.stringify(defaultConfig, null, 2);
+        await fs.writeFile(configPath, content, "utf-8");
+        // Log informational message to stderr
+        console.error(`Created default config at ${configPath}`);
+        return true;
+    }
+    catch (error) {
+        // Log warning but don't fail - config will use defaults
+        console.warn(`Warning: Could not create default config at ${configPath}: ${error instanceof Error ? error.message : String(error)}`);
+        return false;
+    }
+}

package/dist/config/schema.js

@@ -0,0 +1,53 @@
+import { z } from "zod";
+/**
+ * Zod schema for Phoenix Insight CLI configuration
+ *
+ * Configuration values can be set via:
+ * 1. Config file (~/.phoenix-insight/config.json or custom path)
+ * 2. Environment variables (PHOENIX_BASE_URL, PHOENIX_API_KEY, etc.)
+ * 3. CLI arguments (--base-url, --api-key, etc.)
+ *
+ * Priority: config file < env vars < CLI args
+ */
+export const configSchema = z.object({
+    /**
+     * Phoenix server base URL
+     * @default "http://localhost:6006"
+     */
+    baseUrl: z.string().default("http://localhost:6006"),
+    /**
+     * Phoenix API key for authentication (optional)
+     */
+    apiKey: z.string().optional(),
+    /**
+     * Maximum number of spans to fetch per project
+     * @default 1000
+     */
+    limit: z.number().int().positive().default(1000),
+    /**
+     * Enable streaming responses from the agent
+     * @default true
+     */
+    stream: z.boolean().default(true),
+    /**
+     * Execution mode: "sandbox" for in-memory filesystem, "local" for real filesystem
+     * @default "sandbox"
+     */
+    mode: z.enum(["sandbox", "local"]).default("sandbox"),
+    /**
+     * Force refresh of snapshot data
+     * @default false
+     */
+    refresh: z.boolean().default(false),
+    /**
+     * Enable tracing of the agent to Phoenix
+     * @default false
+     */
+    trace: z.boolean().default(false),
+});
+/**
+ * Get default configuration values
+ */
+export function getDefaultConfig() {
+    return configSchema.parse({});
+}

package/dist/index.js

@@ -0,0 +1 @@
+export * from "./modes/index.js";

package/dist/modes/index.js

@@ -0,0 +1,17 @@
+export * from "./types.js";
+export * from "./sandbox.js";
+export * from "./local.js";
+import { SandboxMode } from "./sandbox.js";
+import { LocalMode } from "./local.js";
+/**
+ * Creates a new sandbox execution mode
+ */
+export function createSandboxMode() {
+    return new SandboxMode();
+}
+/**
+ * Creates a new local execution mode
+ */
+export async function createLocalMode() {
+    return new LocalMode();
+}