// burger:* module declarations — Contract C4 (burger:host) and C6 (Phase 1 modules).
// Anything not declared here is not provided by Burger Phase 1.
// Modules provided under a Node or Bun name also have a `default` export: an
// object containing all their named exports (C6).

declare module "burger:host" {
  /** Per-app identity and paths, fixed at runtime creation. */
  export const appId: string;
  export const dataDir: string;
  export const logDir: string;
  export const entryPoint: string;
  export const config: unknown;

  export interface HostChannel {
    /** Serialise `frame` with serde_json, append "\n", write. Throws TypeError if not JSON-serialisable. */
    send(frame: object): void;
    /** Register the frame handler. Replaces any previous handler. */
    onFrame(handler: (frame: any) => void): void;
    /** Called once when the connection closes; `error` is set when it closed abnormally. */
    onClose(handler: (error?: Error) => void): void;
    close(): void;
  }

  /** Open the app channel. Calling it twice returns the same channel. */
  export function connect(): HostChannel;

  /** QuickJS runtime memory for THIS app, in KiB. */
  export function memoryUsage(): {
    heap_used_kb: number;
    heap_total_kb: number;
    external_kb: number;
    heap_capacity_kb: number;
  };

  /** Stop this app. Never returns. */
  export function exit(code: number): never;
}

declare module "burger:fs" {
  export type PathLike = string;
  export type Utf8Encoding = "utf8" | "utf-8";

  export interface Stats {
    isFile(): boolean;
    isDirectory(): boolean;
    readonly size: number;
    readonly mtimeMs: number;
  }

  export function existsSync(path: PathLike): boolean;
  export function readFileSync(path: PathLike): Uint8Array;
  export function readFileSync(path: PathLike, encoding: Utf8Encoding | { encoding: Utf8Encoding }): string;
  export function writeFileSync(path: PathLike, data: string | Uint8Array): void;
  export function appendFileSync(path: PathLike, data: string | Uint8Array): void;
  export function mkdirSync(path: PathLike, options?: { recursive?: boolean }): void;
  export function readdirSync(path: PathLike): string[];
  export function statSync(path: PathLike): Stats;
  export function rmSync(path: PathLike, options?: { recursive?: boolean; force?: boolean }): void;
  export function renameSync(oldPath: PathLike, newPath: PathLike): void;
  export function chmodSync(path: PathLike, mode: number): void;
  export function unlinkSync(path: PathLike): void;
  /** Create a unique directory whose name starts with `prefix`; returns its path. */
  export function mkdtempSync(prefix: string): string;

  export interface FsPromises {
    exists(path: PathLike): Promise<boolean>;
    readFile(path: PathLike): Promise<Uint8Array>;
    readFile(path: PathLike, encoding: Utf8Encoding | { encoding: Utf8Encoding }): Promise<string>;
    writeFile(path: PathLike, data: string | Uint8Array): Promise<void>;
    appendFile(path: PathLike, data: string | Uint8Array): Promise<void>;
    mkdir(path: PathLike, options?: { recursive?: boolean }): Promise<void>;
    readdir(path: PathLike): Promise<string[]>;
    stat(path: PathLike): Promise<Stats>;
    rm(path: PathLike, options?: { recursive?: boolean; force?: boolean }): Promise<void>;
    rename(oldPath: PathLike, newPath: PathLike): Promise<void>;
    chmod(path: PathLike, mode: number): Promise<void>;
    unlink(path: PathLike): Promise<void>;
    mkdtemp(prefix: string): Promise<string>;
  }

  export const promises: FsPromises;

  const fs: {
    existsSync: typeof existsSync;
    readFileSync: typeof readFileSync;
    writeFileSync: typeof writeFileSync;
    appendFileSync: typeof appendFileSync;
    mkdirSync: typeof mkdirSync;
    readdirSync: typeof readdirSync;
    statSync: typeof statSync;
    rmSync: typeof rmSync;
    renameSync: typeof renameSync;
    chmodSync: typeof chmodSync;
    unlinkSync: typeof unlinkSync;
    mkdtempSync: typeof mkdtempSync;
    promises: FsPromises;
  };
  export default fs;
}

declare module "burger:fs/promises" {
  import type { FsPromises } from "burger:fs";
  export const exists: FsPromises["exists"];
  export const readFile: FsPromises["readFile"];
  export const writeFile: FsPromises["writeFile"];
  export const appendFile: FsPromises["appendFile"];
  export const mkdir: FsPromises["mkdir"];
  export const readdir: FsPromises["readdir"];
  export const stat: FsPromises["stat"];
  export const rm: FsPromises["rm"];
  export const rename: FsPromises["rename"];
  export const chmod: FsPromises["chmod"];
  export const unlink: FsPromises["unlink"];
  export const mkdtemp: FsPromises["mkdtemp"];
  const fsPromises: FsPromises;
  export default fsPromises;
}

declare module "burger:path" {
  export interface ParsedPath {
    root: string;
    dir: string;
    base: string;
    ext: string;
    name: string;
  }
  export interface PathModule {
    join(...paths: string[]): string;
    resolve(...paths: string[]): string;
    dirname(path: string): string;
    basename(path: string, suffix?: string): string;
    extname(path: string): string;
    relative(from: string, to: string): string;
    normalize(path: string): string;
    isAbsolute(path: string): boolean;
    readonly sep: "/";
    readonly delimiter: ":";
    parse(path: string): ParsedPath;
    format(pathObject: Partial<ParsedPath>): string;
  }
  export const join: PathModule["join"];
  export const resolve: PathModule["resolve"];
  export const dirname: PathModule["dirname"];
  export const basename: PathModule["basename"];
  export const extname: PathModule["extname"];
  export const relative: PathModule["relative"];
  export const normalize: PathModule["normalize"];
  export const isAbsolute: PathModule["isAbsolute"];
  export const sep: PathModule["sep"];
  export const delimiter: PathModule["delimiter"];
  export const parse: PathModule["parse"];
  export const format: PathModule["format"];
  const path: PathModule;
  export default path;
}

declare module "burger:os" {
  export interface CpuInfo {
    model: string;
    speed: number;
  }
  export interface OsModule {
    platform(): "linux" | "darwin";
    arch(): "arm64" | "x64";
    cpus(): CpuInfo[];
    totalmem(): number;
    freemem(): number;
    hostname(): string;
    tmpdir(): string;
    homedir(): string;
    readonly EOL: string;
  }
  export const platform: OsModule["platform"];
  export const arch: OsModule["arch"];
  export const cpus: OsModule["cpus"];
  export const totalmem: OsModule["totalmem"];
  export const freemem: OsModule["freemem"];
  export const hostname: OsModule["hostname"];
  export const tmpdir: OsModule["tmpdir"];
  export const homedir: OsModule["homedir"];
  export const EOL: OsModule["EOL"];
  const os: OsModule;
  export default os;
}

declare module "burger:worker_threads" {
  export const isMainThread: true;
  export const workerData: undefined;
  export const parentPort: null;
  export const threadId: 0;
  const workerThreads: {
    isMainThread: true;
    workerData: undefined;
    parentPort: null;
    threadId: 0;
  };
  export default workerThreads;
}

declare module "burger:crypto" {
  export type HashAlgorithm = "sha256" | "sha512" | "sha1";
  export type DigestEncoding = "hex" | "base64";
  export interface Hash {
    update(data: string | Uint8Array): Hash;
    digest(): Uint8Array;
    digest(encoding: DigestEncoding): string;
  }
  export type Hmac = Hash;
  export function randomUUID(): string;
  export function randomBytes(size: number): Uint8Array;
  export function createHash(algorithm: HashAlgorithm): Hash;
  export function createHmac(algorithm: HashAlgorithm, key: string | Uint8Array): Hmac;
  export function timingSafeEqual(a: Uint8Array, b: Uint8Array): boolean;
  const crypto: {
    randomUUID: typeof randomUUID;
    randomBytes: typeof randomBytes;
    createHash: typeof createHash;
    createHmac: typeof createHmac;
    timingSafeEqual: typeof timingSafeEqual;
  };
  export default crypto;
}

declare module "burger:buffer" {
  export type BufferEncoding = "utf8" | "utf-8" | "hex" | "base64" | "base64url";

  /** C5 subset of Node's Buffer. Instances are `Uint8Array`s. */
  export interface Buffer extends Uint8Array<ArrayBuffer> {
    toString(encoding?: BufferEncoding): string;
    equals(other: Uint8Array): boolean;
    subarray(start?: number, end?: number): Buffer;
    slice(start?: number, end?: number): Buffer;
  }

  export interface BufferConstructor {
    readonly prototype: Buffer;
    from(value: string, encoding?: BufferEncoding): Buffer;
    from(value: Uint8Array | ArrayBuffer | readonly number[]): Buffer;
    alloc(size: number): Buffer;
    concat(list: readonly Uint8Array[]): Buffer;
    isBuffer(value: unknown): value is Buffer;
    byteLength(value: string): number;
  }

  export const Buffer: BufferConstructor;
  const buffer: { Buffer: BufferConstructor };
  export default buffer;
}

declare module "burger:sqlite" {
  export type SQLValue = null | number | bigint | string | Uint8Array;
  export type SQLBinding = SQLValue | boolean | undefined;
  export type SQLParams =
    | SQLBinding[]
    | [SQLBinding[]]
    | [Record<string, SQLBinding>];

  export interface Changes {
    changes: number;
    lastInsertRowid: number | bigint;
  }

  export interface Statement<Row = unknown> {
    all(...params: SQLParams): Row[];
    get(...params: SQLParams): Row | null;
    run(...params: SQLParams): Changes;
    values(...params: SQLParams): SQLValue[][];
  }

  export interface DatabaseOptions {
    create?: boolean;
    readonly?: boolean;
  }

  export class Database {
    constructor(filename?: string, options?: DatabaseOptions);
    query<Row = unknown>(sql: string): Statement<Row>;
    prepare<Row = unknown>(sql: string): Statement<Row>;
    exec(sql: string, ...params: SQLParams): Changes;
    run(sql: string, ...params: SQLParams): Changes;
    transaction<Args extends unknown[], Result>(fn: (...args: Args) => Result): (...args: Args) => Result;
    close(): void;
  }

  /** Default export is the Database class itself, which also carries `.Database` (C6). */
  const sqlite: typeof Database & { Database: typeof Database };
  export default sqlite;
}

declare module "burger:test" {
  export type TestBody = () => void | Promise<unknown>;
  /** A per-test timeout in milliseconds, or `{ timeout }` (as bun:test accepts). */
  export type TestOptions = number | { timeout?: number };

  /**
   * `test.each(table)(title, fn)`: one test per row. A row that is an array is
   * spread into `fn`'s arguments; `title` takes `%s %d %i %f %j %o %p %#`.
   */
  export interface EachFunction {
    <Row extends readonly unknown[]>(table: readonly Row[]): (
      title: string,
      fn: (...args: Row) => void | Promise<unknown>,
      options?: TestOptions,
    ) => void;
    <Row>(table: readonly Row[]): (title: string, fn: (arg: Row) => void | Promise<unknown>, options?: TestOptions) => void;
  }

  export interface DescribeEachFunction {
    <Row extends readonly unknown[]>(table: readonly Row[]): (title: string, fn: (...args: Row) => void) => void;
    <Row>(table: readonly Row[]): (title: string, fn: (arg: Row) => void) => void;
  }

  export interface TestFunction {
    (name: string, fn: TestBody, options?: TestOptions): void;
    skip(name: string, fn?: TestBody, options?: TestOptions): void;
    only(name: string, fn: TestBody, options?: TestOptions): void;
    todo(name: string, fn?: TestBody): void;
    each: EachFunction;
  }

  export interface DescribeFunction {
    (name: string, fn: () => void): void;
    skip(name: string, fn: () => void): void;
    only(name: string, fn: () => void): void;
    todo(name: string, fn?: () => void): void;
    each: DescribeEachFunction;
  }

  export const describe: DescribeFunction;
  export const test: TestFunction;
  export const it: TestFunction;

  export function beforeEach(fn: TestBody): void;
  export function afterEach(fn: TestBody): void;
  export function beforeAll(fn: TestBody): void;
  export function afterAll(fn: TestBody): void;
  export function setDefaultTimeout(ms: number): void;

  export interface Matchers<R> {
    toBe(expected: unknown): R;
    toContain(expected: unknown): R;
    toEqual(expected: unknown): R;
    toStrictEqual(expected: unknown): R;
    toHaveLength(length: number): R;
    toBeDefined(): R;
    toBeUndefined(): R;
    toBeNull(): R;
    toBeTruthy(): R;
    toBeFalsy(): R;
    toHaveProperty(keyPath: string | string[], value?: unknown): R;
    toMatchObject(expected: object): R;
    toMatch(expected: string | RegExp): R;
    toBeGreaterThan(expected: number | bigint): R;
    toBeGreaterThanOrEqual(expected: number | bigint): R;
    toBeLessThan(expected: number | bigint): R;
    toBeLessThanOrEqual(expected: number | bigint): R;
    /** `|expected - actual| < 10^-digits / 2`; `digits` defaults to 2. */
    toBeCloseTo(expected: number, digits?: number): R;
    toStartWith(prefix: string): R;
    toThrow(expected?: string | RegExp | Error | AsymmetricMatcher | (new (...args: any[]) => Error)): R;
    toBeInstanceOf(expected: abstract new (...args: any[]) => unknown): R;
    toContainEqual(expected: unknown): R;
    /** The subject is a `mock()` function. */
    toHaveBeenCalled(): R;
    toHaveBeenCalledTimes(count: number): R;
    toHaveBeenCalledWith(...args: unknown[]): R;
  }

  export interface Expect extends Matchers<void> {
    readonly not: Matchers<void>;
    readonly resolves: Matchers<Promise<void>> & { readonly not: Matchers<Promise<void>> };
    readonly rejects: Matchers<Promise<void>> & { readonly not: Matchers<Promise<void>> };
  }

  /** Placeholder accepted wherever an expected value is (`toEqual`, `toContainEqual`, `toHaveBeenCalledWith`, …). */
  export interface AsymmetricMatcher {
    asymmetricMatch(other: unknown): boolean;
  }

  export interface ExpectFunction {
    (actual: unknown): Expect;
    /** Matches any value created by `constructor` (or of that primitive type for `Number`, `String`, …). */
    any(constructor: abstract new (...args: any[]) => unknown): AsymmetricMatcher;
    /** Matches anything but `null` and `undefined`. */
    anything(): AsymmetricMatcher;
    /** Matches any object that has at least `sample`'s properties with equal values. */
    objectContaining(sample: object): AsymmetricMatcher;
    /** Matches any array that contains an element equal to each of `items`. */
    arrayContaining(items: readonly unknown[]): AsymmetricMatcher;
    stringContaining(text: string): AsymmetricMatcher;
    stringMatching(pattern: string | RegExp): AsymmetricMatcher;
  }

  export const expect: ExpectFunction;

  export type AnyFunction = (...args: any[]) => any;

  export type MockResult<T> = { readonly type: "return"; readonly value: T } | { readonly type: "throw"; readonly value: unknown };

  export interface MockState<F extends AnyFunction> {
    readonly calls: Parameters<F>[];
    readonly results: MockResult<ReturnType<F>>[];
    /** `this` of each call. */
    readonly instances: unknown[];
  }

  export interface Mock<F extends AnyFunction> {
    (...args: Parameters<F>): ReturnType<F>;
    readonly mock: MockState<F>;
    mockImplementation(fn: F): Mock<F>;
    mockImplementationOnce(fn: F): Mock<F>;
    mockReturnValue(value: ReturnType<F>): Mock<F>;
    mockReturnValueOnce(value: ReturnType<F>): Mock<F>;
    mockResolvedValue(value: Awaited<ReturnType<F>>): Mock<F>;
    mockResolvedValueOnce(value: Awaited<ReturnType<F>>): Mock<F>;
    mockRejectedValue(error: unknown): Mock<F>;
    mockRejectedValueOnce(error: unknown): Mock<F>;
    /** Forget recorded calls, results and instances; keep the implementation. */
    mockClear(): Mock<F>;
    /** `mockClear()`, and drop every implementation (calls then return `undefined`). */
    mockReset(): Mock<F>;
  }

  export interface MockFactory {
    <F extends AnyFunction = AnyFunction>(fn?: F): Mock<F>;
    /**
     * Replace the module `specifier` (resolved as an import from the calling
     * file) with `factory()`'s result. Factories are synchronous (C8). Call it
     * before the module is loaded, then load it with `await import()`: static
     * imports are linked before any test code runs.
     */
    module(specifier: string, factory: () => Record<string, unknown>): void;
  }

  export const mock: MockFactory;
}