import { FlagSchema } from "../../schema/flag.mjs";
import { CommandSchema } from "../../schema/command.mjs";
import "../../schema/index.mjs";
//#region src/core/completion/shells/shared.d.ts
/**
 * Format a version tag for generated completion script headers.
 *
 * Produces e.g. `"@kjanat/dreamcli v0.9.1 (f9b5f1a)"` when built, or
 * `"@kjanat/dreamcli"` when running unbundled in development.
 *
 * @internal
 */
declare function versionTag(): string;
/**
 * Options for completion script generation.
 *
 * Passed to individual shell generators alongside the CLI schema.
 *
 * These options affect the generated script text, not runtime completion
 * behavior after installation.
 */
interface CompletionOptions {
  /**
   * Override the generated shell function name prefix.
   *
   * Defaults to the CLI name from the schema. This is mainly useful when
   * embedding multiple generated scripts in the same environment and you want
   * deterministic, collision-free helper names.
   *
   * @example
   * ```ts
   * generateCompletion(schema, 'bash', { functionPrefix: 'acme' });
   * ```
   */
  readonly functionPrefix?: string;
  /**
   * Where the built-in shell completion is exposed.
   *
   * - `'command'` registers a `completions` subcommand (the default).
   * - `'flag'` exposes an eager `--completions <shell>` flag on the CLI root
   *   instead, keeping the root free of a `completions` subcommand.
   *
   * @defaultValue `'command'`
   */
  readonly as?: 'command' | 'flag';
  /**
   * Controls which root-level surface shell completion exposes when a
   * default command exists.
   *
   * - `'subcommands'` keeps hybrid CLIs command-centric at the root while
   *   still exposing default-command flags for a single visible default
   *   command.
   * - `'surface'` exposes the default command's root-usable flags at the
   *   root whenever a visible default command exists.
   *
   * @defaultValue `'subcommands'`
   */
  readonly rootMode?: 'subcommands' | 'surface';
}
/**
 * Normalized root completion surface consumed by shell generators.
 *
 * @internal
 */
interface RootCompletionSurface {
  readonly visibleCommands: readonly CommandSchema[];
  readonly visibleDefaultCommand: CommandSchema | undefined;
  readonly rootFlags: Readonly<Record<string, FlagSchema>>;
  readonly defaultFlags: Readonly<Record<string, FlagSchema>>;
  readonly includeDefaultFlags: boolean;
}
/**
 * Schema shape needed to compute the root completion surface.
 *
 * @internal
 */
interface RootCompletionSchemaLike {
  readonly commands: ReadonlyArray<{
    readonly schema: CommandSchema;
  }>;
  readonly defaultCommand: {
    readonly schema: CommandSchema;
  } | undefined;
  readonly version: string | undefined;
}
/**
 * Resolve the root-level completion surface from the CLI schema and policy.
 *
 * @internal
 */
declare function resolveRootCompletionSurface(schema: RootCompletionSchemaLike, rootMode?: CompletionOptions['rootMode']): RootCompletionSurface;
/**
 * A flattened node from the command tree, carrying its ancestry context.
 *
 * Used by both bash and zsh generators to produce completions at every
 * nesting level with correct propagated flag inheritance.
 *
 * @internal
 */
interface CommandNode {
  /** Name path from root: `['db', 'migrate']` */
  readonly path: readonly string[];
  /** The command schema at this node */
  readonly schema: CommandSchema;
  /** Propagated flags inherited from ancestors (excludes own flags) */
  readonly propagatedFlags: Readonly<Record<string, FlagSchema>>;
  /** Merged flags: propagated + own (own shadows propagated) */
  readonly mergedFlags: Readonly<Record<string, FlagSchema>>;
  /** Visible child command schemas (for subcommand completion) */
  readonly children: readonly CommandSchema[];
}
/**
 * Walk the command tree depth-first, producing a flat list of
 * {@link CommandNode}s with propagated flag context.
 *
 * @param topLevel - Top-level visible command schemas.
 * @param ancestorSchemas - Schema path from root (for propagation calculation).
 * @returns Flat list of all visible nodes in the tree.
 *
 * @internal
 */
declare function walkCommandTree(topLevel: readonly CommandSchema[], ancestorSchemas?: readonly CommandSchema[]): readonly CommandNode[];
/**
 * Effective negated long-form spelling for user-facing suggestion lists.
 *
 * Returns the negated spelling without the `--` prefix (e.g. `no-verbose`)
 * when the flag is negatable and the negation is not hidden; `undefined`
 * otherwise. Negated spellings are long-only and take no value, so they only
 * belong in suggestion lists — never in value-flag (operand-skip) patterns.
 *
 * @internal
 */
declare function getVisibleNegatedName(name: string, schema: FlagSchema): string | undefined;
/**
 * Sanitize a string for use as a shell function identifier.
 * Replaces non-alphanumeric/underscore characters with underscores.
 * When sanitization changes the name, appends a short stable hash suffix so
 * distinct originals cannot collide on the same helper identifier.
 * Used by both bash and zsh generators.
 *
 * @internal
 */
declare function sanitizeShellIdentifier(name: string): string;
/**
 * Quote a string for safe interpolation into a shell script.
 *
 * Uses single-quote wrapping with the standard `'\''` idiom for
 * embedded single quotes. This prevents shell injection from CLI
 * names containing spaces, semicolons, backticks, or other
 * special characters.
 *
 * Returns the input unquoted if it consists only of shell-safe
 * characters (`[a-zA-Z0-9_\-.]`), avoiding unnecessary noise
 * in generated scripts for common CLI names like `my-cli` or `app.v2`.
 *
 * @internal
 */
declare function quoteShellArg(value: string): string;
//#endregion
export { type CommandNode, type CompletionOptions, type RootCompletionSurface, getVisibleNegatedName, quoteShellArg, resolveRootCompletionSurface, sanitizeShellIdentifier, versionTag, walkCommandTree };