import { join } from "node:path";
import { getSfEnv } from "./env.js";

/**
 * app-paths.ts — central directory and file path constants for the sf runtime.
 *
 * Purpose: provide a single source of truth for all on-disk locations that sf
 * reads and writes (agent bundles, sessions, auth, preferences, PID files).
 * Centralising paths prevents drift when the layout changes and ensures tests
 * can override SF_HOME to redirect all I/O into a temp directory.
 *
 * Consumer: cli.ts, loader.ts, onboarding.ts, extension-registry.ts,
 * remote-questions-config.ts, update-check.ts, models-resolver.ts,
 * project-sessions.ts, and cli-web-branch.ts.
 */

/**
 * Returns the root directory for all sf runtime state.
 *
 * Purpose: define the top-level folder where sessions, agents, preferences,
 * and PID files live. Overridable via SF_HOME so tests and CI can redirect
 * all disk I/O away from the user's real home directory.
 *
 * Consumer: cli.ts (session manager, auth storage, resource loader),
 * loader.ts (agent directory setup), update-check.ts (cache file),
 * remote-questions-config.ts (global preferences), extension-registry.ts
 * (registry JSON), and every other derived path in this module.
 */
export const appRoot = getSfEnv().sfHome;

/**
 * Returns the path to the managed agent directory.
 *
 * Purpose: isolate bundled extensions, agent binaries, and compiled assets
 * from user data (sessions, preferences). This separation lets sf wipe and
 * re-sync the agent directory on upgrade without touching session history.
 *
 * Consumer: cli.ts (resource loader, settings manager, auth storage),
 * loader.ts (extension discovery and sync), onboarding.ts (first-run setup),
 * models-resolver.ts (model registry), and cli-web-branch.ts (server mode).
 */
export const agentDir = join(appRoot, "agent");

/**
 * Returns the path to the sessions directory.
 *
 * Purpose: keep all conversation history, checkpoints, and session metadata
 * in one tree so the SessionManager can enumerate, archive, or migrate them.
 *
 * Consumer: cli.ts (SessionManager base directory), project-sessions.ts
 * (project-scoped session subdirectories), and cli-web-branch.ts (server mode
 * session root).
 */
export const sessionsDir = join(appRoot, "sessions");

/**
 * Returns the path to the auth credentials file.
 *
 * Purpose: store API keys and tokens securely on disk so users do not have
 * to re-authenticate on every launch. The file is read by AuthStorage and
 * written during onboarding or login flows.
 *
 * Consumer: cli.ts (AuthStorage.create), cli-web-branch.ts (web-mode auth).
 */
export const authFilePath = join(agentDir, "auth.json");

/**
 * Returns the path to the web-server PID file.
 *
 * Purpose: track whether a background SF server is already running so that
 * concurrent `sf server` invocations can detect the existing process instead of
 * spawning a second listener on the same port.
 *
 * Consumer: cli-web-branch.ts (server mode start/stop lifecycle).
 */
export const webPidFilePath = join(appRoot, "web-server.pid");

/**
 * Returns the path to the web-preferences JSON file.
 *
 * Purpose: persist UI-specific settings (theme, layout, last-opened project)
 * separately from CLI preferences so the web frontend and the TUI can evolve
 * their configs independently.
 *
 * Consumer: cli-web-branch.ts (server mode settings read/write).
 */
export const webPreferencesPath = join(appRoot, "web-preferences.json");
