import { ConfigEnv, Plugin } from "vite";
//#region src/types.d.ts
/**
 * Configuration types for the KickJS Vite plugin.
 *
 * @module @forinda/kickjs-vite/types
 */
/**
 * Options for the KickJS Vite plugin.
 *
 * @example
 * ```ts
 * // vite.config.ts
 * import { kickjsVitePlugin } from '@forinda/kickjs-vite'
 *
 * export default defineConfig({
 *   plugins: [
 *     kickjsVitePlugin({
 *       entry: 'src/index.ts',
 *     }),
 *   ],
 * })
 * ```
 */
interface KickJSPluginOptions {
  /**
   * Path to the application entry file, relative to the project root.
   * This file should export an Express app instance from `bootstrap()`.
   *
   * @default 'src/index.ts'
   *
   * @example
   * ```ts
   * // src/index.ts
   * import { bootstrap } from '@forinda/kickjs'
   * export const app = bootstrap({ modules: [...] })
   * ```
   */
  entry?: string;
  /** HMR logger / behaviour overrides (see {@link HmrOptions}). */
  hmr?: HmrOptions;
  /**
   * DevTools build-time flag knob. The plugin exposes
   * `__KICKJS_DEVTOOLS__` as a global constant adopters can guard
   * imports of `@forinda/kickjs-devtools` behind so the entire
   * adapter (and its dynamic-import chunk) drops out of production
   * bundles via Vite's existing tree-shaking. Default value: `true`
   * during `vite dev`, `false` during `vite build`.
   *
   * Pass `{ enabled: false }` to force-disable in any mode (useful
   * for shipping a "no devtools" build profile alongside the dev
   * server). Pass `{ flagName: '__APP_DEVTOOLS__' }` to rename the
   * global if it collides with another tool. Pass `false` to skip
   * registering the plugin entirely (no `define` entry written).
   *
   * @default `{}` — flag is registered with environment-based defaults
   */
  devtools?: DevtoolsOptions | false;
}
/**
 * DevTools-flag plugin options. Mirrors the structure of
 * `DevtoolsFlagOptions` from `./devtools-flag-plugin` so the public
 * type stays close to the runtime contract.
 */
interface DevtoolsOptions {
  /** Force the flag value, bypassing dev-vs-build detection. */
  enabled?: boolean;
  /** Override the global name. Default `__KICKJS_DEVTOOLS__`. */
  flagName?: string;
}
/**
 * Payload handed to {@link HmrOptions.onInvalidation}.
 *
 * `tokens` is the deduplicated batch flushed for one debounce window —
 * a mix of class names (`'UserController'`), v4 factory entries
 * (`'MyAdapter (defineAdapter)'`), and bare basenames (`'hello.ts'`)
 * for plain source files without kickjs patterns. `timestamp` matches
 * the value broadcast on the `kickjs:hmr` HMR client event so dev tools
 * can correlate.
 */
interface HmrInvalidationContext {
  /** Token names / file basenames flushed in this debounce window. */
  tokens: readonly string[];
  /** Epoch ms when the batch was flushed. */
  timestamp: number;
}
/**
 * HMR-related plugin options.
 *
 * Defaults preserve the existing `HMR invalidated N tokens: …` log line.
 * Adopters with custom dev tooling (Discord webhooks, structured JSON
 * logs, in-app overlays) override `onInvalidation`; tests / CI dev runs
 * usually want `silent: true`.
 */
interface HmrOptions {
  /**
   * Suppress the built-in console log entirely. The `kickjs:hmr` HMR
   * event is still broadcast — DevTools / Swagger UI continue to react
   * to invalidations, only the terminal stays quiet.
   */
  silent?: boolean;
  /**
   * Replace the built-in dev-console line with a custom function. When
   * provided, the default log is *not* printed (your function owns the
   * channel). Returning a string emits a single `console.log`; returning
   * `undefined` / `void` suppresses output entirely so you can route
   * elsewhere (pino, OTel span events, websocket, etc.).
   *
   * @example
   * ```ts
   * kickjsVitePlugin({
   *   hmr: {
   *     onInvalidation: ({ tokens }) => `↻ rebuilt: ${tokens.join(' · ')}`,
   *   },
   * })
   * ```
   */
  onInvalidation?: (context: HmrInvalidationContext) => string | undefined | void;
}
/**
 * Shared context passed between all KickJS sub-plugins.
 * Created once by the main plugin factory and shared via closure.
 */
interface PluginContext {
  /** Resolved absolute path to the application entry file */
  entry: string;
  /** Project root directory (from Vite config) */
  root: string;
}
//#endregion
//#region src/env-watch-plugin.d.ts
/**
 * Vite plugin that watches `.env` files and triggers a full reload
 * when they change. This ensures the dev server picks up environment
 * variable changes without a manual restart.
 *
 * Lives in `@forinda/kickjs-vite` so all Vite-only concerns are in one
 * place.
 *
 * @example
 * ```ts
 * // vite.config.ts
 * import { envWatchPlugin } from '@forinda/kickjs-vite'
 *
 * export default defineConfig({
 *   plugins: [swc.vite(), envWatchPlugin()],
 * })
 * ```
 */
declare function envWatchPlugin(): Plugin;
//#endregion
//#region src/typegen-plugin.d.ts
/** Structural slice of the CLI surface this plugin consumes. */
interface TypegenCliModule {
  loadKickConfig(cwd: string): Promise<unknown>;
  createTypegenDevWatcher(opts: {
    cwd: string;
    config: unknown;
    emitWarning: (message: string) => void;
  }): {
    handleWatchEvent(event: 'add' | 'change' | 'unlink' | 'unlinkDir', file: string): void;
    runOnce(): void;
    assetSrcRoots: readonly string[];
    dispose(): void;
  };
}
interface TypegenPluginOptions {
  /** Test seam — defaults to project-root resolution of the real CLI. */
  loadCli?: (root: string) => Promise<TypegenCliModule | null>;
}
declare function kickjsTypegenPlugin(opts?: TypegenPluginOptions): Plugin;
//#endregion
//#region src/devtools-flag-plugin.d.ts
interface DevtoolsFlagOptions {
  /**
   * Force the flag value. When set, environment-based detection is
   * bypassed entirely. Useful for explicit feature gates per build
   * profile.
   *
   * @default `vite command === 'serve'` (true in dev, false in build)
   */
  enabled?: boolean;
  /**
   * Override the global name. Default `__KICKJS_DEVTOOLS__`.
   * Useful for adopters who want a project-specific flag name to
   * avoid colliding with another tooling's own globals.
   */
  flagName?: string;
}
/**
 * Resolve the build-time devtools flag. Exposed for unit tests +
 * adopters who want to compute the same answer the plugin would.
 */
declare function resolveDevtoolsFlag(opts?: DevtoolsFlagOptions, env?: ConfigEnv): boolean;
declare function devtoolsFlagPlugin(opts?: DevtoolsFlagOptions): Plugin;
//#endregion
//#region src/devtools-strip-plugin.d.ts
interface DevtoolsStripOptions {
  /**
   * Force enable / disable. Default: enabled when `command === 'build'`.
   * Adopters running a debug-prod build (`kick build` with the flag
   * forced on) can pass `false` to keep devtools-kit code in the
   * bundle.
   */
  enabled?: boolean;
  /**
   * Glob-like include pattern. Default: any `.ts` / `.tsx` /
   * `.mts` / `.cts` file under the project root. The transform is
   * a no-op on files that don't import devtools-kit, so this is
   * normally fine to leave at the default.
   */
  include?: RegExp;
}
/**
 * Strips devtools-kit imports + their top-level call sites from
 * production bundles. See `babel-strip-devtools.ts` for the exact
 * rule set.
 */
declare function devtoolsStripPlugin(opts?: DevtoolsStripOptions): Plugin;
//#endregion
//#region src/babel-strip-devtools.d.ts
/**
 * Babel-based devtools stripper for production builds.
 *
 * Built around a single rule: anything sourced from
 * `@forinda/kickjs-devtools-kit` (or any of its sub-paths) is dev-
 * only and must not ship in the prod bundle. The transform walks
 * each module and removes:
 *
 *  1. `import ... from '@forinda/kickjs-devtools-kit'` declarations
 *     (named, default, namespace, side-effect — all forms).
 *  2. Top-level `ExpressionStatement`s whose call/expression root is
 *     a binding imported from devtools-kit
 *     (e.g., `defineDevtoolsRenderTab({...})`).
 *  3. Side-effect imports whose path ends in `/devtools-events`
 *     (with any extension) — type-augmentation modules shipped by
 *     adapter packages. Already side-effect-only, safe to drop in
 *     prod.
 *
 * The transform is intentionally conservative. It will not:
 *
 *  - Remove identifier *references* outside of the rules above. If
 *    your code calls `defineDevtoolsRenderTab(...)` inside a regular
 *    function body (i.e. not a top-level `ExpressionStatement`),
 *    the reference stays. After we drop the import the build will
 *    fail loud — that is the signal to gate the call behind
 *    `__KICKJS_DEVTOOLS__` (see `devtools-flag-plugin.ts`).
 *  - Touch files that don't import from devtools-kit at all.
 *  - Touch files in `node_modules` (Vite's plugin chain handles
 *    that already, but the transform short-circuits on a quick
 *    string check too).
 *
 * The dev path is unchanged: this transform only runs when Vite's
 * `command === 'build'`. In dev, devtools-kit imports stay live.
 *
 * Spec: docs/db/m3-plan.md §M3.C.
 */
interface StripDevtoolsOptions {
  /**
   * When `false`, skips files that don't import devtools-kit. The
   * default short-circuit is a substring check on the source text;
   * disable it only for tests where you want the visitor to run
   * unconditionally.
   *
   * @default true
   */
  fastReject?: boolean;
}
interface StripResult {
  /** Transformed source. Returns the original `code` when nothing was stripped. */
  code: string;
  /** `true` if the visitor removed at least one node. */
  changed: boolean;
}
/**
 * Strip devtools-kit imports and their dependent top-level calls
 * from a single TypeScript module. Pure — no I/O, no Vite, no
 * filesystem.
 */
declare function stripDevtoolsCode(source: string, filename: string, opts?: StripDevtoolsOptions): StripResult;
//#endregion
//#region src/index.d.ts
/**
 * Create the KickJS Vite plugin array.
 *
 * Returns an array of focused sub-plugins that together provide full
 * Vite integration for KickJS backend applications. Each sub-plugin
 * has a single responsibility and runs at the appropriate Vite lifecycle stage.
 *
 * @param options - Plugin configuration
 * @param options.entry - Path to app entry file (default: 'src/index.ts')
 * @returns Array of Vite plugins
 *
 * @example
 * ```ts
 * // vite.config.ts
 * import { defineConfig } from 'vite'
 * import { kickjsVitePlugin } from '@forinda/kickjs-vite'
 * import swc from 'unplugin-swc'
 *
 * export default defineConfig({
 *   plugins: [
 *     swc.vite({ tsconfigFile: 'tsconfig.json' }),
 *     kickjsVitePlugin(),
 *   ],
 * })
 * ```
 */
declare function kickjsVitePlugin(options?: KickJSPluginOptions): Plugin[];
//#endregion
export { type DevtoolsFlagOptions, type DevtoolsOptions, type DevtoolsStripOptions, type HmrInvalidationContext, type HmrOptions, type KickJSPluginOptions, type PluginContext, type StripDevtoolsOptions, type StripResult, type TypegenCliModule, type TypegenPluginOptions, devtoolsFlagPlugin, devtoolsStripPlugin, envWatchPlugin, kickjsTypegenPlugin, kickjsVitePlugin, resolveDevtoolsFlag, stripDevtoolsCode };
//# sourceMappingURL=index.d.mts.map