@dexto/core 1.1.4 → 1.1.6

package/dist/utils/api-key-store.js

@@ -0,0 +1,30 @@
+import { LLM_PROVIDERS } from "../llm/types.js";
+import { getPrimaryApiKeyEnvVar, resolveApiKeyForProvider } from "./api-key-resolver.js";
+import { updateEnvFile } from "./env.js";
+import { getDextoEnvPath } from "./path.js";
+async function saveProviderApiKey(provider, apiKey, startPath) {
+  if (!provider) throw new Error("provider is required");
+  if (!apiKey || !apiKey.trim()) throw new Error("apiKey is required");
+  const envVar = getPrimaryApiKeyEnvVar(provider);
+  const targetEnvPath = getDextoEnvPath(startPath);
+  await updateEnvFile(targetEnvPath, { [envVar]: apiKey });
+  process.env[envVar] = apiKey;
+  return { envVar, targetEnvPath };
+}
+function getProviderKeyStatus(provider) {
+  const envVar = getPrimaryApiKeyEnvVar(provider);
+  const key = resolveApiKeyForProvider(provider);
+  return { hasApiKey: Boolean(key && key.trim()), envVar };
+}
+function listProviderKeyStatus() {
+  const result = {};
+  for (const p of LLM_PROVIDERS) {
+    result[p] = getProviderKeyStatus(p);
+  }
+  return result;
+}
+export {
+  getProviderKeyStatus,
+  listProviderKeyStatus,
+  saveProviderApiKey
+};

package/dist/utils/env.cjs

@@ -0,0 +1,154 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var env_exports = {};
+__export(env_exports, {
+  applyLayeredEnvironmentLoading: () => applyLayeredEnvironmentLoading,
+  loadEnvironmentVariables: () => loadEnvironmentVariables,
+  updateEnvFile: () => updateEnvFile
+});
+module.exports = __toCommonJS(env_exports);
+var path = __toESM(require("path"), 1);
+var import_os = require("os");
+var import_fs = require("fs");
+var import_dotenv = __toESM(require("dotenv"), 1);
+var import_execution_context = require("./execution-context.js");
+var import_path = require("./path.js");
+async function loadEnvironmentVariables(startPath = process.cwd()) {
+  const context = (0, import_execution_context.getExecutionContext)(startPath);
+  const env = {};
+  const globalEnvPath = path.join((0, import_os.homedir)(), ".dexto", ".env");
+  try {
+    const globalResult = import_dotenv.default.config({ path: globalEnvPath, processEnv: {} });
+    if (globalResult.parsed) {
+      Object.assign(env, globalResult.parsed);
+    }
+  } catch {
+  }
+  if (context === "dexto-source" || context === "dexto-project") {
+    const projectEnvPath = (0, import_path.getDextoEnvPath)(startPath);
+    try {
+      const projectResult = import_dotenv.default.config({ path: projectEnvPath, processEnv: {} });
+      if (projectResult.parsed) {
+        Object.assign(env, projectResult.parsed);
+      }
+    } catch {
+    }
+  }
+  for (const [key, value] of Object.entries(process.env)) {
+    if (value !== void 0 && value !== "") {
+      env[key] = value;
+    }
+  }
+  return env;
+}
+async function applyLayeredEnvironmentLoading(startPath = process.cwd()) {
+  await (0, import_path.ensureDextoGlobalDirectory)();
+  const layeredEnv = await loadEnvironmentVariables(startPath);
+  Object.assign(process.env, layeredEnv);
+}
+async function updateEnvFile(envFilePath, updates) {
+  const dextoEnvKeys = [
+    "OPENAI_API_KEY",
+    "ANTHROPIC_API_KEY",
+    "GOOGLE_GENERATIVE_AI_API_KEY",
+    "GROQ_API_KEY",
+    "COHERE_API_KEY",
+    "XAI_API_KEY",
+    "DEXTO_LOG_LEVEL"
+  ];
+  await import_fs.promises.mkdir(path.dirname(envFilePath), { recursive: true });
+  let envLines = [];
+  try {
+    const existingEnv = await import_fs.promises.readFile(envFilePath, "utf8");
+    envLines = existingEnv.split("\n");
+  } catch {
+  }
+  const currentValues = {};
+  envLines.forEach((line) => {
+    const match = line.match(/^([A-Z0-9_]+)=(.*)$/);
+    if (match && match[1] && match[2] !== void 0 && dextoEnvKeys.includes(match[1])) {
+      currentValues[match[1]] = match[2];
+    }
+  });
+  const updatedValues = {
+    OPENAI_API_KEY: updates.OPENAI_API_KEY ?? currentValues.OPENAI_API_KEY ?? "",
+    ANTHROPIC_API_KEY: updates.ANTHROPIC_API_KEY ?? currentValues.ANTHROPIC_API_KEY ?? "",
+    GOOGLE_GENERATIVE_AI_API_KEY: updates.GOOGLE_GENERATIVE_AI_API_KEY ?? currentValues.GOOGLE_GENERATIVE_AI_API_KEY ?? "",
+    GROQ_API_KEY: updates.GROQ_API_KEY ?? currentValues.GROQ_API_KEY ?? "",
+    COHERE_API_KEY: updates.COHERE_API_KEY ?? currentValues.COHERE_API_KEY ?? "",
+    XAI_API_KEY: updates.XAI_API_KEY ?? currentValues.XAI_API_KEY ?? "",
+    DEXTO_LOG_LEVEL: updates.DEXTO_LOG_LEVEL ?? currentValues.DEXTO_LOG_LEVEL ?? "info"
+  };
+  const sectionHeader = "## Dexto env variables";
+  const headerIndex = envLines.findIndex((line) => line.trim() === sectionHeader);
+  let contentLines;
+  if (headerIndex !== -1) {
+    const beforeSection = envLines.slice(0, headerIndex);
+    let sectionEnd = headerIndex + 1;
+    while (sectionEnd < envLines.length && envLines[sectionEnd]?.trim() !== "") {
+      sectionEnd++;
+    }
+    if (sectionEnd < envLines.length && envLines[sectionEnd]?.trim() === "") {
+      sectionEnd++;
+    }
+    const afterSection = envLines.slice(sectionEnd);
+    contentLines = [...beforeSection, ...afterSection];
+  } else {
+    contentLines = envLines;
+  }
+  const existingEnvVars = {};
+  contentLines.forEach((line) => {
+    const match = line.match(/^([A-Z0-9_]+)=(.*)$/);
+    if (match && match[1] && match[2] !== void 0 && dextoEnvKeys.includes(match[1])) {
+      existingEnvVars[match[1]] = match[2];
+    }
+  });
+  if (contentLines.length > 0) {
+    if (contentLines[contentLines.length - 1]?.trim() !== "") {
+      contentLines.push("");
+    }
+  } else {
+    contentLines.push("");
+  }
+  contentLines.push(sectionHeader);
+  for (const key of dextoEnvKeys) {
+    if (key in existingEnvVars && !(key in updates)) {
+      continue;
+    }
+    contentLines.push(`${key}=${updatedValues[key]}`);
+  }
+  contentLines.push("");
+  await import_fs.promises.writeFile(envFilePath, contentLines.join("\n"), "utf8");
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  applyLayeredEnvironmentLoading,
+  loadEnvironmentVariables,
+  updateEnvFile
+});

package/dist/utils/env.d.cts

@@ -0,0 +1,29 @@
+/**
+ * Multi-layer environment variable loading with context awareness.
+ * Loads environment variables in priority order:
+ * 1. Shell environment (highest priority)
+ * 2. Project .env (if in dexto project)
+ * 3. Global ~/.dexto/.env (fallback)
+ *
+ * @param startPath Starting directory for project detection
+ * @returns Combined environment variables object
+ */
+declare function loadEnvironmentVariables(startPath?: string): Promise<Record<string, string>>;
+/**
+ * Apply layered environment loading to process.env.
+ * This replaces the simple dotenv.config() with multi-layer loading.
+ * Should be called at CLI startup before any schema validation.
+ *
+ * @param startPath Starting directory for project detection
+ */
+declare function applyLayeredEnvironmentLoading(startPath?: string): Promise<void>;
+/**
+ * Core logic to update an .env file with Dexto environment variables.
+ * This is the shared implementation used by both project and interactive env file updates.
+ *
+ * @param envFilePath - Absolute path to the .env file to update
+ * @param updates - Object containing environment variable updates
+ */
+declare function updateEnvFile(envFilePath: string, updates: Record<string, string>): Promise<void>;
+
+export { applyLayeredEnvironmentLoading, loadEnvironmentVariables, updateEnvFile };

package/dist/utils/env.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Multi-layer environment variable loading with context awareness.
+ * Loads environment variables in priority order:
+ * 1. Shell environment (highest priority)
+ * 2. Project .env (if in dexto project)
+ * 3. Global ~/.dexto/.env (fallback)
+ *
+ * @param startPath Starting directory for project detection
+ * @returns Combined environment variables object
+ */
+declare function loadEnvironmentVariables(startPath?: string): Promise<Record<string, string>>;
+/**
+ * Apply layered environment loading to process.env.
+ * This replaces the simple dotenv.config() with multi-layer loading.
+ * Should be called at CLI startup before any schema validation.
+ *
+ * @param startPath Starting directory for project detection
+ */
+declare function applyLayeredEnvironmentLoading(startPath?: string): Promise<void>;
+/**
+ * Core logic to update an .env file with Dexto environment variables.
+ * This is the shared implementation used by both project and interactive env file updates.
+ *
+ * @param envFilePath - Absolute path to the .env file to update
+ * @param updates - Object containing environment variable updates
+ */
+declare function updateEnvFile(envFilePath: string, updates: Record<string, string>): Promise<void>;
+
+export { applyLayeredEnvironmentLoading, loadEnvironmentVariables, updateEnvFile };

package/dist/utils/env.js

@@ -0,0 +1,118 @@
+import * as path from "path";
+import { homedir } from "os";
+import { promises as fs } from "fs";
+import dotenv from "dotenv";
+import { getExecutionContext } from "./execution-context.js";
+import { ensureDextoGlobalDirectory, getDextoEnvPath } from "./path.js";
+async function loadEnvironmentVariables(startPath = process.cwd()) {
+  const context = getExecutionContext(startPath);
+  const env = {};
+  const globalEnvPath = path.join(homedir(), ".dexto", ".env");
+  try {
+    const globalResult = dotenv.config({ path: globalEnvPath, processEnv: {} });
+    if (globalResult.parsed) {
+      Object.assign(env, globalResult.parsed);
+    }
+  } catch {
+  }
+  if (context === "dexto-source" || context === "dexto-project") {
+    const projectEnvPath = getDextoEnvPath(startPath);
+    try {
+      const projectResult = dotenv.config({ path: projectEnvPath, processEnv: {} });
+      if (projectResult.parsed) {
+        Object.assign(env, projectResult.parsed);
+      }
+    } catch {
+    }
+  }
+  for (const [key, value] of Object.entries(process.env)) {
+    if (value !== void 0 && value !== "") {
+      env[key] = value;
+    }
+  }
+  return env;
+}
+async function applyLayeredEnvironmentLoading(startPath = process.cwd()) {
+  await ensureDextoGlobalDirectory();
+  const layeredEnv = await loadEnvironmentVariables(startPath);
+  Object.assign(process.env, layeredEnv);
+}
+async function updateEnvFile(envFilePath, updates) {
+  const dextoEnvKeys = [
+    "OPENAI_API_KEY",
+    "ANTHROPIC_API_KEY",
+    "GOOGLE_GENERATIVE_AI_API_KEY",
+    "GROQ_API_KEY",
+    "COHERE_API_KEY",
+    "XAI_API_KEY",
+    "DEXTO_LOG_LEVEL"
+  ];
+  await fs.mkdir(path.dirname(envFilePath), { recursive: true });
+  let envLines = [];
+  try {
+    const existingEnv = await fs.readFile(envFilePath, "utf8");
+    envLines = existingEnv.split("\n");
+  } catch {
+  }
+  const currentValues = {};
+  envLines.forEach((line) => {
+    const match = line.match(/^([A-Z0-9_]+)=(.*)$/);
+    if (match && match[1] && match[2] !== void 0 && dextoEnvKeys.includes(match[1])) {
+      currentValues[match[1]] = match[2];
+    }
+  });
+  const updatedValues = {
+    OPENAI_API_KEY: updates.OPENAI_API_KEY ?? currentValues.OPENAI_API_KEY ?? "",
+    ANTHROPIC_API_KEY: updates.ANTHROPIC_API_KEY ?? currentValues.ANTHROPIC_API_KEY ?? "",
+    GOOGLE_GENERATIVE_AI_API_KEY: updates.GOOGLE_GENERATIVE_AI_API_KEY ?? currentValues.GOOGLE_GENERATIVE_AI_API_KEY ?? "",
+    GROQ_API_KEY: updates.GROQ_API_KEY ?? currentValues.GROQ_API_KEY ?? "",
+    COHERE_API_KEY: updates.COHERE_API_KEY ?? currentValues.COHERE_API_KEY ?? "",
+    XAI_API_KEY: updates.XAI_API_KEY ?? currentValues.XAI_API_KEY ?? "",
+    DEXTO_LOG_LEVEL: updates.DEXTO_LOG_LEVEL ?? currentValues.DEXTO_LOG_LEVEL ?? "info"
+  };
+  const sectionHeader = "## Dexto env variables";
+  const headerIndex = envLines.findIndex((line) => line.trim() === sectionHeader);
+  let contentLines;
+  if (headerIndex !== -1) {
+    const beforeSection = envLines.slice(0, headerIndex);
+    let sectionEnd = headerIndex + 1;
+    while (sectionEnd < envLines.length && envLines[sectionEnd]?.trim() !== "") {
+      sectionEnd++;
+    }
+    if (sectionEnd < envLines.length && envLines[sectionEnd]?.trim() === "") {
+      sectionEnd++;
+    }
+    const afterSection = envLines.slice(sectionEnd);
+    contentLines = [...beforeSection, ...afterSection];
+  } else {
+    contentLines = envLines;
+  }
+  const existingEnvVars = {};
+  contentLines.forEach((line) => {
+    const match = line.match(/^([A-Z0-9_]+)=(.*)$/);
+    if (match && match[1] && match[2] !== void 0 && dextoEnvKeys.includes(match[1])) {
+      existingEnvVars[match[1]] = match[2];
+    }
+  });
+  if (contentLines.length > 0) {
+    if (contentLines[contentLines.length - 1]?.trim() !== "") {
+      contentLines.push("");
+    }
+  } else {
+    contentLines.push("");
+  }
+  contentLines.push(sectionHeader);
+  for (const key of dextoEnvKeys) {
+    if (key in existingEnvVars && !(key in updates)) {
+      continue;
+    }
+    contentLines.push(`${key}=${updatedValues[key]}`);
+  }
+  contentLines.push("");
+  await fs.writeFile(envFilePath, contentLines.join("\n"), "utf8");
+}
+export {
+  applyLayeredEnvironmentLoading,
+  loadEnvironmentVariables,
+  updateEnvFile
+};

package/dist/utils/error-conversion.cjs

@@ -0,0 +1,53 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var error_conversion_exports = {};
+__export(error_conversion_exports, {
+  toError: () => toError
+});
+module.exports = __toCommonJS(error_conversion_exports);
+var import_safe_stringify = require("./safe-stringify.js");
+function toError(error) {
+  if (error instanceof Error) {
+    return error;
+  }
+  if (error && typeof error === "object") {
+    if ("message" in error && typeof error.message === "string") {
+      return new Error(error.message, { cause: error });
+    }
+    if ("error" in error && typeof error.error === "string") {
+      return new Error(error.error, { cause: error });
+    }
+    if ("details" in error && typeof error.details === "string") {
+      return new Error(error.details, { cause: error });
+    }
+    if ("description" in error && typeof error.description === "string") {
+      return new Error(error.description, { cause: error });
+    }
+    const serialized = (0, import_safe_stringify.safeStringify)(error);
+    return new Error(serialized);
+  }
+  if (typeof error === "string") {
+    return new Error(error, { cause: error });
+  }
+  return new Error(String(error), { cause: error });
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  toError
+});

package/dist/utils/error-conversion.d.cts

@@ -0,0 +1,13 @@
+/**
+ * Utility functions for converting various error types to proper Error instances
+ * with meaningful messages instead of "[object Object]"
+ */
+/**
+ * Converts any error value to an Error instance with a meaningful message
+ *
+ * @param error - The error value to convert (can be Error, object, string, etc.)
+ * @returns Error instance with extracted or serialized message
+ */
+declare function toError(error: unknown): Error;
+
+export { toError };

package/dist/utils/error-conversion.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Utility functions for converting various error types to proper Error instances
+ * with meaningful messages instead of "[object Object]"
+ */
+/**
+ * Converts any error value to an Error instance with a meaningful message
+ *
+ * @param error - The error value to convert (can be Error, object, string, etc.)
+ * @returns Error instance with extracted or serialized message
+ */
+declare function toError(error: unknown): Error;
+
+export { toError };

package/dist/utils/error-conversion.js

@@ -0,0 +1,29 @@
+import { safeStringify } from "./safe-stringify.js";
+function toError(error) {
+  if (error instanceof Error) {
+    return error;
+  }
+  if (error && typeof error === "object") {
+    if ("message" in error && typeof error.message === "string") {
+      return new Error(error.message, { cause: error });
+    }
+    if ("error" in error && typeof error.error === "string") {
+      return new Error(error.error, { cause: error });
+    }
+    if ("details" in error && typeof error.details === "string") {
+      return new Error(error.details, { cause: error });
+    }
+    if ("description" in error && typeof error.description === "string") {
+      return new Error(error.description, { cause: error });
+    }
+    const serialized = safeStringify(error);
+    return new Error(serialized);
+  }
+  if (typeof error === "string") {
+    return new Error(error, { cause: error });
+  }
+  return new Error(String(error), { cause: error });
+}
+export {
+  toError
+};

package/dist/utils/execution-context.cjs

@@ -0,0 +1,85 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var execution_context_exports = {};
+__export(execution_context_exports, {
+  findDextoProjectRoot: () => findDextoProjectRoot,
+  findDextoSourceRoot: () => findDextoSourceRoot,
+  getExecutionContext: () => getExecutionContext
+});
+module.exports = __toCommonJS(execution_context_exports);
+var import_fs_walk = require("./fs-walk.js");
+var import_fs = require("fs");
+var path = __toESM(require("path"), 1);
+function isDextoSourceDirectory(dirPath) {
+  const packageJsonPath = path.join(dirPath, "package.json");
+  try {
+    const pkg = JSON.parse((0, import_fs.readFileSync)(packageJsonPath, "utf-8"));
+    return pkg.name === "dexto-monorepo";
+  } catch {
+    return false;
+  }
+}
+function isDextoProjectDirectory(dirPath) {
+  const packageJsonPath = path.join(dirPath, "package.json");
+  try {
+    const pkg = JSON.parse((0, import_fs.readFileSync)(packageJsonPath, "utf-8"));
+    if (pkg.name === "dexto" || pkg.name === "@dexto/core" || pkg.name === "@dexto/webui") {
+      return false;
+    }
+    const allDeps = {
+      ...pkg.dependencies ?? {},
+      ...pkg.devDependencies ?? {},
+      ...pkg.peerDependencies ?? {}
+    };
+    return "dexto" in allDeps || "@dexto/core" in allDeps;
+  } catch {
+    return false;
+  }
+}
+function findDextoSourceRoot(startPath = process.cwd()) {
+  return (0, import_fs_walk.walkUpDirectories)(startPath, isDextoSourceDirectory);
+}
+function findDextoProjectRoot(startPath = process.cwd()) {
+  return (0, import_fs_walk.walkUpDirectories)(startPath, isDextoProjectDirectory);
+}
+function getExecutionContext(startPath = process.cwd()) {
+  if (findDextoSourceRoot(startPath)) {
+    return "dexto-source";
+  }
+  if (findDextoProjectRoot(startPath)) {
+    return "dexto-project";
+  }
+  return "global-cli";
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  findDextoProjectRoot,
+  findDextoSourceRoot,
+  getExecutionContext
+});

package/dist/utils/execution-context.d.cts

@@ -0,0 +1,21 @@
+type ExecutionContext = 'dexto-source' | 'dexto-project' | 'global-cli';
+/**
+ * Find dexto source root directory
+ * @param startPath Starting directory path
+ * @returns Dexto source root directory or null if not found
+ */
+declare function findDextoSourceRoot(startPath?: string): string | null;
+/**
+ * Find dexto project root directory (projects using dexto as dependency)
+ * @param startPath Starting directory path
+ * @returns Dexto project root directory or null if not found
+ */
+declare function findDextoProjectRoot(startPath?: string): string | null;
+/**
+ * Detect current execution context - standardized across codebase
+ * @param startPath Starting directory path (defaults to process.cwd())
+ * @returns Execution context
+ */
+declare function getExecutionContext(startPath?: string): ExecutionContext;
+
+export { type ExecutionContext, findDextoProjectRoot, findDextoSourceRoot, getExecutionContext };

package/dist/utils/execution-context.d.ts

@@ -0,0 +1,21 @@
+type ExecutionContext = 'dexto-source' | 'dexto-project' | 'global-cli';
+/**
+ * Find dexto source root directory
+ * @param startPath Starting directory path
+ * @returns Dexto source root directory or null if not found
+ */
+declare function findDextoSourceRoot(startPath?: string): string | null;
+/**
+ * Find dexto project root directory (projects using dexto as dependency)
+ * @param startPath Starting directory path
+ * @returns Dexto project root directory or null if not found
+ */
+declare function findDextoProjectRoot(startPath?: string): string | null;
+/**
+ * Detect current execution context - standardized across codebase
+ * @param startPath Starting directory path (defaults to process.cwd())
+ * @returns Execution context
+ */
+declare function getExecutionContext(startPath?: string): ExecutionContext;
+
+export { type ExecutionContext, findDextoProjectRoot, findDextoSourceRoot, getExecutionContext };

package/dist/utils/execution-context.js

@@ -0,0 +1,49 @@
+import { walkUpDirectories } from "./fs-walk.js";
+import { readFileSync } from "fs";
+import * as path from "path";
+function isDextoSourceDirectory(dirPath) {
+  const packageJsonPath = path.join(dirPath, "package.json");
+  try {
+    const pkg = JSON.parse(readFileSync(packageJsonPath, "utf-8"));
+    return pkg.name === "dexto-monorepo";
+  } catch {
+    return false;
+  }
+}
+function isDextoProjectDirectory(dirPath) {
+  const packageJsonPath = path.join(dirPath, "package.json");
+  try {
+    const pkg = JSON.parse(readFileSync(packageJsonPath, "utf-8"));
+    if (pkg.name === "dexto" || pkg.name === "@dexto/core" || pkg.name === "@dexto/webui") {
+      return false;
+    }
+    const allDeps = {
+      ...pkg.dependencies ?? {},
+      ...pkg.devDependencies ?? {},
+      ...pkg.peerDependencies ?? {}
+    };
+    return "dexto" in allDeps || "@dexto/core" in allDeps;
+  } catch {
+    return false;
+  }
+}
+function findDextoSourceRoot(startPath = process.cwd()) {
+  return walkUpDirectories(startPath, isDextoSourceDirectory);
+}
+function findDextoProjectRoot(startPath = process.cwd()) {
+  return walkUpDirectories(startPath, isDextoProjectDirectory);
+}
+function getExecutionContext(startPath = process.cwd()) {
+  if (findDextoSourceRoot(startPath)) {
+    return "dexto-source";
+  }
+  if (findDextoProjectRoot(startPath)) {
+    return "dexto-project";
+  }
+  return "global-cli";
+}
+export {
+  findDextoProjectRoot,
+  findDextoSourceRoot,
+  getExecutionContext
+};