<?php
/**
 * Physical (on-disk) writer for llms.txt / llms-full.txt.
 *
 * Pure filesystem logic, deliberately free of WordPress function calls so it
 * can be unit-tested in isolation. The caller (ADG_AIM_LLMS_Generator) is
 * responsible for resolving the target directory and persisting the
 * ownership state returned here (e.g. into a WP option).
 *
 * @package ADG_AI_Markdown
 */

if ( ! defined( 'ABSPATH' ) && ! defined( 'ADG_AIM_TESTING' ) ) {
	exit;
}

class ADG_AIM_LLMS_Physical_Writer {

	/**
	 * Write $content to $dir/$filename, unless a foreign (not plugin-owned)
	 * file already occupies that path.
	 *
	 * @param string $dir      Absolute directory, trailing slash optional.
	 * @param string $filename e.g. 'llms.txt'.
	 * @param string $content  File content to write.
	 * @param bool   $owned    Whether the plugin already owns this filename
	 *                         (from previously persisted state).
	 * @return array{written:bool,owned:bool,reason:string} reason is one of
	 *         'ok', 'not_writable', 'conflict', 'write_failed'.
	 */
	public static function write( $dir, $filename, $content, $owned ) {
		$dir  = self::normalize_dir( $dir );
		$path = $dir . $filename;

		if ( ! is_dir( $dir ) || ! is_writable( $dir ) ) {
			return array(
				'written' => false,
				'owned'   => $owned,
				'reason'  => 'not_writable',
			);
		}

		if ( ! $owned && file_exists( $path ) ) {
			// Something else (host, another plugin, a manual upload) already
			// put a file here — never clobber it silently.
			return array(
				'written' => false,
				'owned'   => false,
				'reason'  => 'conflict',
			);
		}

		$bytes = @file_put_contents( $path, $content, LOCK_EX ); // phpcs:ignore WordPress.PHP.NoSilencedErrors.Discouraged -- filesystem outcome is checked via the return value, not surfaced as a PHP warning.

		if ( false === $bytes ) {
			return array(
				'written' => false,
				'owned'   => $owned,
				'reason'  => 'write_failed',
			);
		}

		return array(
			'written' => true,
			'owned'   => true,
			'reason'  => 'ok',
		);
	}

	/**
	 * Delete the physical file, but only if the plugin owns it. Never removes
	 * a foreign file.
	 *
	 * @param string $dir      Absolute directory, trailing slash optional.
	 * @param string $filename e.g. 'llms.txt'.
	 * @param bool   $owned    Whether the plugin owns this filename.
	 * @return bool True if deleted or already absent; false if refused or failed.
	 */
	public static function delete_if_owned( $dir, $filename, $owned ) {
		if ( ! $owned ) {
			return false;
		}

		$path = self::normalize_dir( $dir ) . $filename;

		if ( ! file_exists( $path ) ) {
			return true;
		}

		return (bool) @unlink( $path ); // phpcs:ignore WordPress.PHP.NoSilencedErrors.Discouraged -- filesystem outcome is checked via the return value.
	}

	/**
	 * Normalize a directory path to have exactly one trailing slash.
	 *
	 * @param string $dir Directory path.
	 * @return string
	 */
	private static function normalize_dir( $dir ) {
		return rtrim( (string) $dir, '/\\' ) . '/';
	}
}