@mastra/code-sdk 0.0.0-mastracode-cloud-20260706153555

package/dist/utils/plans.d.ts

@@ -0,0 +1,56 @@
+/** Global plans directory for approved-plan archives. */
+export declare function getPlansDir(): string;
+/** Local (project-scoped) plans directory where the agent writes named plan files. */
+export declare function getLocalPlansDir(projectPath: string): string;
+/** Workspace-relative directory the agent writes plan files into. */
+export declare function getLocalPlansRelativeDir(): string;
+/** Derive a plan filename from a title (e.g. `add-dark-mode.md`). */
+export declare function getPlanFilename(title: string): string;
+/**
+ * Suggested workspace-relative path for a new plan file, shown in plan-mode prompts.
+ * Without a title we fall back to a generic name the agent can rename later.
+ */
+export declare function getSuggestedPlanRelativePath(title?: string): string;
+/**
+ * Resolve a plan path submitted by the agent (absolute or project-relative) to an
+ * absolute path. Returns `undefined` when no usable path was provided.
+ */
+export declare function resolvePlanPath(projectPath: string, submittedPath: string): string | undefined;
+/**
+ * Whether `targetPath` (absolute or project-relative) is a valid plan file: a `.md`
+ * file located directly inside the project's `.mastracode/plans/` directory. Used by the
+ * plan-mode write guard so the agent can write any named plan file there, but nothing
+ * outside that directory.
+ */
+export declare function isPlanFilePath(projectPath: string, targetPath: string): boolean;
+export declare function savePlanToDisk(opts: {
+    title: string;
+    plan: string;
+    resourceId: string;
+    plansDir?: string;
+}): Promise<void>;
+/**
+ * Read a plan markdown file by absolute path.
+ *
+ * The leading `# <title>` heading (if present) is parsed as the title and the remaining
+ * content is returned as the plan body. Returns `undefined` when the file does not exist.
+ */
+export declare function readPlanFile(absPath: string): Promise<{
+    title: string;
+    plan: string;
+} | undefined>;
+/**
+ * Approve the plan file at `planPath`: write a timestamped copy to the global plans
+ * archive so approved plans are findable later. The local named plan file is left in
+ * place so the user can review every plan made over time.
+ *
+ * Returns the local plan filename (e.g. `add-dark-mode.md`), or `undefined` when there
+ * was no plan file to approve.
+ */
+export declare function approvePlanFile(opts: {
+    planPath: string;
+    title: string;
+    resourceId: string;
+    plansDir?: string;
+}): Promise<string | undefined>;
+//# sourceMappingURL=plans.d.ts.map

package/dist/utils/plans.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plans.d.ts","sourceRoot":"","sources":["../../src/utils/plans.ts"],"names":[],"mappings":"AAKA,yDAAyD;AACzD,wBAAgB,WAAW,IAAI,MAAM,CAEpC;AAED,sFAAsF;AACtF,wBAAgB,gBAAgB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAE5D;AAED,qEAAqE;AACrE,wBAAgB,wBAAwB,IAAI,MAAM,CAEjD;AAUD,qEAAqE;AACrE,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAErD;AAED;;;GAGG;AACH,wBAAgB,4BAA4B,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAGnE;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,WAAW,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAG9F;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,WAAW,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAU/E;AAED,wBAAsB,cAAc,CAAC,IAAI,EAAE;IACzC,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,GAAG,OAAO,CAAC,IAAI,CAAC,CAoBhB;AAED;;;;;GAKG;AACH,wBAAsB,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG,SAAS,CAAC,CAsBxG;AAED;;;;;;;GAOG;AACH,wBAAsB,eAAe,CAAC,IAAI,EAAE;IAC1C,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAc9B"}

package/dist/utils/plans.js

@@ -0,0 +1,99 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { DEFAULT_CONFIG_DIR } from "../constants.js";
+import { getAppDataDir } from "./project.js";
+function getPlansDir() {
+  return process.env.MASTRA_PLANS_DIR ?? path.join(getAppDataDir(), "plans");
+}
+function getLocalPlansDir(projectPath) {
+  return path.join(projectPath, DEFAULT_CONFIG_DIR, "plans");
+}
+function getLocalPlansRelativeDir() {
+  return path.join(DEFAULT_CONFIG_DIR, "plans");
+}
+function slugify(str) {
+  const slug = str.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "");
+  return slug || "untitled";
+}
+function getPlanFilename(title) {
+  return `${slugify(title)}.md`;
+}
+function getSuggestedPlanRelativePath(title) {
+  const filename = title ? getPlanFilename(title) : "plan.md";
+  return path.join(getLocalPlansRelativeDir(), filename);
+}
+function resolvePlanPath(projectPath, submittedPath) {
+  if (!submittedPath) return void 0;
+  return path.isAbsolute(submittedPath) ? submittedPath : path.resolve(projectPath, submittedPath);
+}
+function isPlanFilePath(projectPath, targetPath) {
+  const abs = resolvePlanPath(projectPath, targetPath);
+  if (!abs) return false;
+  if (path.extname(abs).toLowerCase() !== ".md") return false;
+  const plansDir = path.resolve(getLocalPlansDir(projectPath));
+  const rel = path.relative(plansDir, abs);
+  if (rel === "" || rel.startsWith("..") || path.isAbsolute(rel)) return false;
+  return !rel.includes(path.sep);
+}
+async function savePlanToDisk(opts) {
+  const { title, plan, resourceId } = opts;
+  const plansDir = opts.plansDir ?? getPlansDir();
+  const baseDir = path.resolve(plansDir);
+  const dir = path.resolve(baseDir, resourceId);
+  const rel = path.relative(baseDir, dir);
+  if (rel.startsWith("..") || path.isAbsolute(rel)) {
+    throw new Error(`Invalid resourceId: ${resourceId}`);
+  }
+  await fs.mkdir(dir, { recursive: true });
+  const now = /* @__PURE__ */ new Date();
+  const timestamp = now.toISOString().replace(/:/g, "-");
+  const slug = slugify(title);
+  const filename = `${timestamp}-${slug}.md`;
+  const content = `# ${title}
+
+Approved: ${now.toISOString()}
+
+${plan}
+`;
+  await fs.writeFile(path.join(dir, filename), content, "utf-8");
+}
+async function readPlanFile(absPath) {
+  let raw;
+  try {
+    raw = await fs.readFile(absPath, "utf-8");
+  } catch {
+    return void 0;
+  }
+  const lines = raw.split(/\r?\n/);
+  const headingIndex = lines.findIndex((line) => line.trim().length > 0);
+  const heading = headingIndex >= 0 ? lines[headingIndex] : void 0;
+  if (heading?.startsWith("# ")) {
+    const title = heading.slice(2).trim();
+    const plan = lines.slice(headingIndex + 1).join("\n").replace(/^\n+/, "").trimEnd();
+    return { title, plan };
+  }
+  return { title: "", plan: raw.trimEnd() };
+}
+async function approvePlanFile(opts) {
+  const { planPath, title, resourceId, plansDir } = opts;
+  const current = await readPlanFile(planPath);
+  if (!current) {
+    return void 0;
+  }
+  const resolvedTitle = title || current.title || "Implementation Plan";
+  await savePlanToDisk({ title: resolvedTitle, plan: current.plan, resourceId, plansDir });
+  return path.basename(planPath);
+}
+export {
+  approvePlanFile,
+  getLocalPlansDir,
+  getLocalPlansRelativeDir,
+  getPlanFilename,
+  getPlansDir,
+  getSuggestedPlanRelativePath,
+  isPlanFilePath,
+  readPlanFile,
+  resolvePlanPath,
+  savePlanToDisk
+};
+//# sourceMappingURL=plans.js.map

package/dist/utils/plans.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/utils/plans.ts"],"sourcesContent":["import fs from 'node:fs/promises';\nimport path from 'node:path';\nimport { DEFAULT_CONFIG_DIR } from '../constants.js';\nimport { getAppDataDir } from './project.js';\n\n/** Global plans directory for approved-plan archives. */\nexport function getPlansDir(): string {\n  return process.env.MASTRA_PLANS_DIR ?? path.join(getAppDataDir(), 'plans');\n}\n\n/** Local (project-scoped) plans directory where the agent writes named plan files. */\nexport function getLocalPlansDir(projectPath: string): string {\n  return path.join(projectPath, DEFAULT_CONFIG_DIR, 'plans');\n}\n\n/** Workspace-relative directory the agent writes plan files into. */\nexport function getLocalPlansRelativeDir(): string {\n  return path.join(DEFAULT_CONFIG_DIR, 'plans');\n}\n\nfunction slugify(str: string): string {\n  const slug = str\n    .toLowerCase()\n    .replace(/[^a-z0-9]+/g, '-')\n    .replace(/^-|-$/g, '');\n  return slug || 'untitled';\n}\n\n/** Derive a plan filename from a title (e.g. `add-dark-mode.md`). */\nexport function getPlanFilename(title: string): string {\n  return `${slugify(title)}.md`;\n}\n\n/**\n * Suggested workspace-relative path for a new plan file, shown in plan-mode prompts.\n * Without a title we fall back to a generic name the agent can rename later.\n */\nexport function getSuggestedPlanRelativePath(title?: string): string {\n  const filename = title ? getPlanFilename(title) : 'plan.md';\n  return path.join(getLocalPlansRelativeDir(), filename);\n}\n\n/**\n * Resolve a plan path submitted by the agent (absolute or project-relative) to an\n * absolute path. Returns `undefined` when no usable path was provided.\n */\nexport function resolvePlanPath(projectPath: string, submittedPath: string): string | undefined {\n  if (!submittedPath) return undefined;\n  return path.isAbsolute(submittedPath) ? submittedPath : path.resolve(projectPath, submittedPath);\n}\n\n/**\n * Whether `targetPath` (absolute or project-relative) is a valid plan file: a `.md`\n * file located directly inside the project's `.mastracode/plans/` directory. Used by the\n * plan-mode write guard so the agent can write any named plan file there, but nothing\n * outside that directory.\n */\nexport function isPlanFilePath(projectPath: string, targetPath: string): boolean {\n  const abs = resolvePlanPath(projectPath, targetPath);\n  if (!abs) return false;\n  if (path.extname(abs).toLowerCase() !== '.md') return false;\n\n  const plansDir = path.resolve(getLocalPlansDir(projectPath));\n  const rel = path.relative(plansDir, abs);\n  // Must be directly inside the plans dir (no nested subdirectories, no escaping it).\n  if (rel === '' || rel.startsWith('..') || path.isAbsolute(rel)) return false;\n  return !rel.includes(path.sep);\n}\n\nexport async function savePlanToDisk(opts: {\n  title: string;\n  plan: string;\n  resourceId: string;\n  plansDir?: string;\n}): Promise<void> {\n  const { title, plan, resourceId } = opts;\n  const plansDir = opts.plansDir ?? getPlansDir();\n  const baseDir = path.resolve(plansDir);\n  const dir = path.resolve(baseDir, resourceId);\n  const rel = path.relative(baseDir, dir);\n  if (rel.startsWith('..') || path.isAbsolute(rel)) {\n    throw new Error(`Invalid resourceId: ${resourceId}`);\n  }\n\n  await fs.mkdir(dir, { recursive: true });\n\n  const now = new Date();\n  const timestamp = now.toISOString().replace(/:/g, '-');\n  const slug = slugify(title);\n  const filename = `${timestamp}-${slug}.md`;\n\n  const content = `# ${title}\\n\\nApproved: ${now.toISOString()}\\n\\n${plan}\\n`;\n\n  await fs.writeFile(path.join(dir, filename), content, 'utf-8');\n}\n\n/**\n * Read a plan markdown file by absolute path.\n *\n * The leading `# <title>` heading (if present) is parsed as the title and the remaining\n * content is returned as the plan body. Returns `undefined` when the file does not exist.\n */\nexport async function readPlanFile(absPath: string): Promise<{ title: string; plan: string } | undefined> {\n  let raw: string;\n  try {\n    raw = await fs.readFile(absPath, 'utf-8');\n  } catch {\n    return undefined;\n  }\n\n  const lines = raw.split(/\\r?\\n/);\n  const headingIndex = lines.findIndex(line => line.trim().length > 0);\n  const heading = headingIndex >= 0 ? lines[headingIndex] : undefined;\n  if (heading?.startsWith('# ')) {\n    const title = heading.slice(2).trim();\n    const plan = lines\n      .slice(headingIndex + 1)\n      .join('\\n')\n      .replace(/^\\n+/, '')\n      .trimEnd();\n    return { title, plan };\n  }\n\n  return { title: '', plan: raw.trimEnd() };\n}\n\n/**\n * Approve the plan file at `planPath`: write a timestamped copy to the global plans\n * archive so approved plans are findable later. The local named plan file is left in\n * place so the user can review every plan made over time.\n *\n * Returns the local plan filename (e.g. `add-dark-mode.md`), or `undefined` when there\n * was no plan file to approve.\n */\nexport async function approvePlanFile(opts: {\n  planPath: string;\n  title: string;\n  resourceId: string;\n  plansDir?: string;\n}): Promise<string | undefined> {\n  const { planPath, title, resourceId, plansDir } = opts;\n\n  const current = await readPlanFile(planPath);\n  if (!current) {\n    return undefined;\n  }\n\n  const resolvedTitle = title || current.title || 'Implementation Plan';\n\n  // Global archive (timestamped, never overwritten) so approved plans are findable later.\n  await savePlanToDisk({ title: resolvedTitle, plan: current.plan, resourceId, plansDir });\n\n  return path.basename(planPath);\n}\n"],"mappings":"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","names":[]}

package/dist/utils/project.d.ts

@@ -0,0 +1,161 @@
+/**
+ * Project detection utilities
+ *
+ * Detects project identity from git repo or filesystem path.
+ * Handles git worktrees by finding the main repository.
+ */
+export interface ProjectInfo {
+    /** Unique resource ID for this project (used for thread grouping) */
+    resourceId: string;
+    /** Human-readable project name */
+    name: string;
+    /** Absolute path to the project root */
+    rootPath: string;
+    /** Git remote URL if available */
+    gitUrl?: string;
+    /** Current git branch */
+    gitBranch?: string;
+    /** Whether this is a git worktree */
+    isWorktree: boolean;
+    /** Path to main git repo (different from rootPath if worktree) */
+    mainRepoPath?: string;
+    /** Whether the resourceId was explicitly overridden (env var or config) */
+    resourceIdOverride?: boolean;
+}
+/**
+ * Detect project info from a directory path
+ */
+export declare function detectProject(projectPath: string): ProjectInfo;
+/**
+ * Get the current git branch for a given directory.
+ * Lightweight alternative to detectProject() for refreshing just the branch.
+ */
+export declare function getCurrentGitBranch(cwd: string): string | undefined;
+/**
+ * Async version of getCurrentGitBranch — avoids blocking the event loop
+ * with execSync.  Falls back to undefined on any failure.
+ */
+export declare function getCurrentGitBranchAsync(cwd: string): Promise<string | undefined>;
+/**
+ * Get the application data directory for mastracode
+ * - macOS: ~/Library/Application Support/mastracode
+ * - Linux: ~/.local/share/mastracode
+ * - Windows: %APPDATA%/mastracode
+ */
+export declare function getAppDataDir(): string;
+/**
+ * Get the database path for mastracode
+ * Can be overridden with the MASTRA_DB_PATH environment variable for debugging.
+ */
+export declare function getDatabasePath(): string;
+/**
+ * Get the vector database path for mastracode.
+ * Separate from the main DB to avoid bloating it with embedding data.
+ */
+export declare function getVectorDatabasePath(): string;
+/**
+ * Get the observability DuckDB database path for mastracode.
+ * Separate from the main DB — DuckDB is used for OLAP-style trace/score/feedback queries.
+ * Can be overridden with the MASTRA_OBSERVABILITY_DB_PATH environment variable.
+ */
+export declare function getObservabilityDatabasePath(): string;
+import type { StorageSettings } from '../onboarding/settings.js';
+/**
+ * LibSQL storage configuration.
+ */
+export interface LibSQLStorageConfig {
+    backend: 'libsql';
+    url: string;
+    authToken?: string;
+    isRemote: boolean;
+    /**
+     * Optional explicit url for the recall vector DB. When omitted, the factory
+     * uses the shared default vector file. Per-tenant storage sets this so each
+     * tenant's recall vectors live in their own isolated DB, not a shared file.
+     */
+    vectorUrl?: string;
+    /** Auth token for the vector DB when `vectorUrl` points at a remote libSQL. */
+    vectorAuthToken?: string;
+}
+/**
+ * PostgreSQL storage configuration.
+ */
+export interface PgStorageConfig {
+    backend: 'pg';
+    connectionString?: string;
+    host?: string;
+    port?: number;
+    database?: string;
+    user?: string;
+    password?: string;
+    schemaName?: string;
+    disableInit?: boolean;
+    skipDefaultIndexes?: boolean;
+}
+/**
+ * Resolved storage configuration for either backend.
+ */
+export type StorageConfig = LibSQLStorageConfig | PgStorageConfig;
+/**
+ * Get the resolved storage configuration.
+ *
+ * Priority (highest to lowest):
+ *   1. Environment variables: MASTRA_STORAGE_BACKEND + backend-specific vars
+ *   2. Global settings (from /settings): settings.storage
+ *   3. Legacy config files: .mastracode/database.json (LibSQL only)
+ *   4. Local file database (LibSQL default)
+ *
+ * For PG, the env vars are:
+ *   MASTRA_STORAGE_BACKEND=pg
+ *   MASTRA_PG_CONNECTION_STRING or MASTRA_PG_HOST/PORT/DATABASE/USER/PASSWORD
+ *   MASTRA_PG_SCHEMA_NAME (optional)
+ *
+ * For LibSQL, the legacy env vars still work:
+ *   MASTRA_DB_URL + MASTRA_DB_AUTH_TOKEN
+ */
+export declare function getStorageConfig(projectDir?: string, storageSettings?: StorageSettings, configDirName?: string): StorageConfig;
+/**
+ * Get the current user identity.
+ *
+ * Priority:
+ *   1. MASTRA_USER_ID environment variable
+ *   2. git config user.email (from project dir or global)
+ *   3. OS username as fallback
+ */
+export declare function getUserId(projectDir?: string): string;
+/**
+ * Get the current user's display name.
+ *
+ * Priority:
+ *   1. git config user.name
+ *   2. OS username as fallback
+ */
+export declare function getUserName(projectDir?: string): string;
+/**
+ * Observational memory scope: "thread" (per-conversation) or "resource" (shared across threads).
+ */
+export type OmScope = 'thread' | 'resource';
+/**
+ * Get the configured observational memory scope.
+ *
+ * Priority:
+ *   1. MASTRA_OM_SCOPE environment variable ("thread" or "resource")
+ *   2. Project config: .mastracode/database.json → omScope
+ *   3. Global config: ~/.mastracode/database.json → omScope
+ *   4. Default: "thread"
+ */
+export declare function getOmScope(projectDir?: string, configDirName?: string): OmScope;
+/**
+ * Get an explicit resource ID override, if configured.
+ *
+ * Resource IDs act as shared tags — two users who set the same resourceId
+ * will share threads and observations for that resource.
+ *
+ * Priority:
+ *   1. MASTRA_RESOURCE_ID environment variable
+ *   2. Project config: .mastracode/database.json → resourceId
+ *   3. Global config: ~/.mastracode/database.json → resourceId
+ *   4. null (use auto-detected value)
+ */
+export declare function getResourceIdOverride(projectDir?: string, configDirName?: string): string | null;
+//# sourceMappingURL=project.d.ts.map

package/dist/utils/project.d.ts.map

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

package/dist/utils/project.js

@@ -0,0 +1,302 @@
+import { execFile, execSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { DEFAULT_CONFIG_DIR } from "../constants.js";
+function git(args, cwd) {
+  try {
+    return execSync(`git ${args}`, {
+      cwd,
+      encoding: "utf-8",
+      stdio: ["pipe", "pipe", "pipe"]
+    }).trim();
+  } catch {
+    return void 0;
+  }
+}
+function slugify(str) {
+  return str.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "");
+}
+function shortHash(str) {
+  return createHash("sha256").update(str).digest("hex").slice(0, 12);
+}
+function normalizeGitUrl(url) {
+  return url.replace(/\.git$/, "").replace(/^git@([^:]+):/, "https://$1/").replace(/^ssh:\/\/git@/, "https://").toLowerCase();
+}
+function detectProject(projectPath) {
+  const absolutePath = path.resolve(projectPath);
+  const gitDir = git("rev-parse --git-dir", absolutePath);
+  const isGitRepo = gitDir !== void 0;
+  let rootPath = absolutePath;
+  let gitUrl;
+  let gitBranch;
+  let isWorktree = false;
+  let mainRepoPath;
+  if (isGitRepo) {
+    rootPath = git("rev-parse --show-toplevel", absolutePath) || absolutePath;
+    const commonDir = git("rev-parse --git-common-dir", absolutePath);
+    if (commonDir && commonDir !== ".git" && commonDir !== gitDir) {
+      isWorktree = true;
+      mainRepoPath = path.dirname(path.resolve(rootPath, commonDir));
+    }
+    gitUrl = git("remote get-url origin", absolutePath);
+    if (!gitUrl) {
+      const remotes = git("remote", absolutePath);
+      if (remotes) {
+        const firstRemote = remotes.split("\n")[0];
+        if (firstRemote) {
+          gitUrl = git(`remote get-url ${firstRemote}`, absolutePath);
+        }
+      }
+    }
+    gitBranch = git("rev-parse --abbrev-ref HEAD", absolutePath);
+  }
+  let resourceIdSource;
+  if (gitUrl) {
+    resourceIdSource = normalizeGitUrl(gitUrl);
+  } else if (mainRepoPath) {
+    resourceIdSource = mainRepoPath;
+  } else {
+    resourceIdSource = rootPath;
+  }
+  const baseName = gitUrl ? gitUrl.split("/").pop()?.replace(/\.git$/, "") || "project" : path.basename(rootPath);
+  const resourceId = `${slugify(baseName)}-${shortHash(resourceIdSource)}`;
+  return {
+    resourceId,
+    name: baseName,
+    rootPath,
+    gitUrl,
+    gitBranch,
+    isWorktree,
+    mainRepoPath
+  };
+}
+function getCurrentGitBranch(cwd) {
+  return git("rev-parse --abbrev-ref HEAD", cwd);
+}
+function getCurrentGitBranchAsync(cwd) {
+  return new Promise((resolve) => {
+    execFile("git", ["rev-parse", "--abbrev-ref", "HEAD"], { cwd, encoding: "utf-8" }, (err, stdout) => {
+      if (err) {
+        resolve(void 0);
+        return;
+      }
+      const branch = stdout.trim();
+      resolve(branch || void 0);
+    });
+  });
+}
+function getAppDataDir() {
+  if (process.env.MASTRA_APP_DATA_DIR) {
+    fs.mkdirSync(process.env.MASTRA_APP_DATA_DIR, { recursive: true });
+    return process.env.MASTRA_APP_DATA_DIR;
+  }
+  const platform = os.platform();
+  let baseDir;
+  if (platform === "darwin") {
+    baseDir = path.join(os.homedir(), "Library", "Application Support");
+  } else if (platform === "win32") {
+    baseDir = process.env.APPDATA || path.join(os.homedir(), "AppData", "Roaming");
+  } else {
+    baseDir = process.env.XDG_DATA_HOME || path.join(os.homedir(), ".local", "share");
+  }
+  const appDir = path.join(baseDir, "mastracode");
+  if (!fs.existsSync(appDir)) {
+    fs.mkdirSync(appDir, { recursive: true });
+  }
+  return appDir;
+}
+function getDatabasePath() {
+  if (process.env.MASTRA_DB_PATH) {
+    return process.env.MASTRA_DB_PATH;
+  }
+  return path.join(getAppDataDir(), "mastra.db");
+}
+function getVectorDatabasePath() {
+  return path.join(getAppDataDir(), "mastra-vectors.db");
+}
+function getObservabilityDatabasePath() {
+  if (process.env.MASTRA_OBSERVABILITY_DB_PATH) {
+    return process.env.MASTRA_OBSERVABILITY_DB_PATH;
+  }
+  return path.join(getAppDataDir(), "observability.duckdb");
+}
+function getStorageConfig(projectDir, storageSettings, configDirName = DEFAULT_CONFIG_DIR) {
+  const envBackend = process.env.MASTRA_STORAGE_BACKEND;
+  if (envBackend === "pg") {
+    return resolvePgFromEnv();
+  }
+  if (envBackend === "libsql" || process.env.MASTRA_DB_URL) {
+    return resolveLibSQLFromEnv();
+  }
+  if (storageSettings && storageSettings.backend === "pg") {
+    return resolvePgFromSettings(storageSettings);
+  }
+  if (storageSettings && storageSettings.backend === "libsql" && storageSettings.libsql.url) {
+    return {
+      backend: "libsql",
+      url: storageSettings.libsql.url,
+      authToken: storageSettings.libsql.authToken,
+      isRemote: !storageSettings.libsql.url.startsWith("file:")
+    };
+  }
+  if (projectDir) {
+    const projectConfig = loadDatabaseConfig(path.join(projectDir, configDirName, "database.json"));
+    if (projectConfig) return projectConfig;
+  }
+  const globalConfig = loadDatabaseConfig(path.join(os.homedir(), configDirName, "database.json"));
+  if (globalConfig) return globalConfig;
+  return {
+    backend: "libsql",
+    url: `file:${getDatabasePath()}`,
+    isRemote: false
+  };
+}
+function resolveLibSQLFromEnv() {
+  const url = process.env.MASTRA_DB_URL;
+  return {
+    backend: "libsql",
+    url,
+    authToken: process.env.MASTRA_DB_AUTH_TOKEN,
+    isRemote: !url.startsWith("file:")
+  };
+}
+function resolvePgFromEnv() {
+  const connectionString = process.env.MASTRA_PG_CONNECTION_STRING;
+  if (connectionString) {
+    return {
+      backend: "pg",
+      connectionString,
+      schemaName: process.env.MASTRA_PG_SCHEMA_NAME
+    };
+  }
+  return {
+    backend: "pg",
+    host: process.env.MASTRA_PG_HOST,
+    port: process.env.MASTRA_PG_PORT ? parseInt(process.env.MASTRA_PG_PORT, 10) : void 0,
+    database: process.env.MASTRA_PG_DATABASE,
+    user: process.env.MASTRA_PG_USER,
+    password: process.env.MASTRA_PG_PASSWORD,
+    schemaName: process.env.MASTRA_PG_SCHEMA_NAME
+  };
+}
+function resolvePgFromSettings(settings) {
+  const pg = settings.pg;
+  return {
+    backend: "pg",
+    connectionString: pg.connectionString,
+    host: pg.host,
+    port: pg.port,
+    database: pg.database,
+    user: pg.user,
+    password: pg.password,
+    schemaName: pg.schemaName,
+    disableInit: pg.disableInit,
+    skipDefaultIndexes: pg.skipDefaultIndexes
+  };
+}
+function loadDatabaseConfig(filePath) {
+  try {
+    if (!fs.existsSync(filePath)) return null;
+    const raw = fs.readFileSync(filePath, "utf-8");
+    const parsed = JSON.parse(raw);
+    if (typeof parsed?.url === "string" && parsed.url) {
+      return {
+        backend: "libsql",
+        url: parsed.url,
+        authToken: typeof parsed.authToken === "string" ? parsed.authToken : void 0,
+        isRemote: !parsed.url.startsWith("file:")
+      };
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+function getUserId(projectDir) {
+  if (process.env.MASTRA_USER_ID) {
+    return process.env.MASTRA_USER_ID;
+  }
+  const cwd = projectDir || process.cwd();
+  const email = git("config user.email", cwd);
+  if (email) {
+    return email;
+  }
+  return os.userInfo().username || "unknown";
+}
+function getUserName(projectDir) {
+  const cwd = projectDir || process.cwd();
+  const name = git("config user.name", cwd);
+  if (name) {
+    return name;
+  }
+  return os.userInfo().username || "unknown";
+}
+function getOmScope(projectDir, configDirName = DEFAULT_CONFIG_DIR) {
+  const envScope = process.env.MASTRA_OM_SCOPE;
+  if (envScope === "thread" || envScope === "resource") {
+    return envScope;
+  }
+  if (projectDir) {
+    const scope2 = loadOmScopeFromConfig(path.join(projectDir, configDirName, "database.json"));
+    if (scope2) return scope2;
+  }
+  const scope = loadOmScopeFromConfig(path.join(os.homedir(), configDirName, "database.json"));
+  if (scope) return scope;
+  return "thread";
+}
+function loadOmScopeFromConfig(filePath) {
+  try {
+    if (!fs.existsSync(filePath)) return null;
+    const raw = fs.readFileSync(filePath, "utf-8");
+    const parsed = JSON.parse(raw);
+    if (parsed?.omScope === "thread" || parsed?.omScope === "resource") {
+      return parsed.omScope;
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+function getResourceIdOverride(projectDir, configDirName = DEFAULT_CONFIG_DIR) {
+  if (process.env.MASTRA_RESOURCE_ID) {
+    return process.env.MASTRA_RESOURCE_ID;
+  }
+  if (projectDir) {
+    const rid2 = loadStringField(path.join(projectDir, configDirName, "database.json"), "resourceId");
+    if (rid2) return rid2;
+  }
+  const rid = loadStringField(path.join(os.homedir(), configDirName, "database.json"), "resourceId");
+  if (rid) return rid;
+  return null;
+}
+function loadStringField(filePath, field) {
+  try {
+    if (!fs.existsSync(filePath)) return null;
+    const raw = fs.readFileSync(filePath, "utf-8");
+    const parsed = JSON.parse(raw);
+    const value = parsed?.[field];
+    if (typeof value === "string" && value) {
+      return value;
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+export {
+  detectProject,
+  getAppDataDir,
+  getCurrentGitBranch,
+  getCurrentGitBranchAsync,
+  getDatabasePath,
+  getObservabilityDatabasePath,
+  getOmScope,
+  getResourceIdOverride,
+  getStorageConfig,
+  getUserId,
+  getUserName,
+  getVectorDatabasePath
+};
+//# sourceMappingURL=project.js.map