export { SYNTHETIC_EVENT_TYPES, type SyntheticEventType } from "./lib/catalog-types.js";
import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
import { type ContextGovernor } from "./context-governor.js";
/** Payload for the init-complete synthetic event. */
export interface InitCompleteEvent {
    type: "init-complete";
    /** Project prefix from .forge/config.json project.prefix */
    projectPrefix: string;
    /** Absolute path to the project root (process.cwd() at init time). */
    cwd: string;
}
/**
 * Payload for the sprint-collate-complete synthetic event (FORGE-S21-T05).
 *
 * Emitted by run-sprint.ts after the sprint's collate phase completes
 * successfully. Consumed by hooks/post-sprint-hook.ts to trigger
 * /forge:rebuild --enrich.
 *
 * Sprint-ID shape gate: `^[A-Z]+-S\d+$` — bug IDs (FORGE-BUG-015,
 * BUG-031, etc.) are excluded so bug-fix collate runs do NOT trigger
 * sprint-level enhancement. Parity with forge/forge/hooks/post-sprint.cjs
 * trigger regex `\S*-S\d+`.
 */
export interface SprintCollateCompleteEvent {
    type: "sprint-collate-complete";
    /** Sprint ID — must match ^[A-Z]+-S\d+$ */
    sprintId: string;
    /** Absolute path to the project root (process.cwd() at emit time). */
    cwd: string;
}
/**
 * Payload for the migration-applied synthetic event (FORGE-S23-T01).
 *
 * Emitted by forge-update-command.ts after runMigrations() completes
 * successfully. Enables future hook handlers to react to migration completion
 * (e.g. trigger /forge:health checks, update-check resets).
 *
 * NOTE: No emitSyntheticEvent call is wired in this task — the event type is
 * added to the union for forward compatibility. The interim emit path uses
 * `store-cli emit SYS-migration` directly from forge-update-command.ts.
 * event.schema.json is NOT modified in this task (system-migration type deferred
 * to a follow-on task per PLAN.md §1D).
 */
export interface MigrationAppliedEvent {
    type: "migration-applied";
    /** Version the user was running before migration */
    fromVersion: string;
    /** Version the user upgraded to */
    toVersion: string;
    /** Number of migration entries applied */
    appliedCount: number;
    /** Absolute path to the project root */
    cwd: string;
}
/** Union of all synthetic event payloads. Extend here as new events are added. */
export type SyntheticEvent = InitCompleteEvent | SprintCollateCompleteEvent | MigrationAppliedEvent;
/**
 * Handler signature for synthetic events.
 * ctx is the ExtensionCommandContext of the emitting phase — callers must
 * forward the context object they received from pi at handler invocation time.
 */
export type SyntheticEventHandler<T extends SyntheticEvent = SyntheticEvent> = (event: T, ctx: ExtensionCommandContext) => void | Promise<void>;
/**
 * Register a handler for a synthetic event type.
 * Handlers are called in registration order when emitSyntheticEvent fires.
 * Exported for use by hooks/post-init-hook.ts and future hook modules.
 */
export declare function onSyntheticEvent<T extends SyntheticEvent>(eventType: T["type"], handler: SyntheticEventHandler<T>): void;
/**
 * Emit a synthetic event, invoking all registered handlers sequentially.
 * Each handler error is caught and logged to stderr (fail-open) — a
 * misbehaving hook MUST NOT block the emitting phase.
 */
export declare function emitSyntheticEvent(event: SyntheticEvent, ctx: ExtensionCommandContext): Promise<void>;
/**
 * Reset the synthetic handler registry.
 * Exported for use in unit tests — do NOT call in production code.
 */
export declare function _resetSyntheticHandlers(): void;
/** Parsed representation of a store-cli invocation intercepted from a bash command. */
export interface StoreCLICall {
    /** Subcommand: write or update-status */
    subcmd: "write" | "update-status";
    /** Entity type: "task" | "sprint" | "bug" | "event" | ... */
    entity: string;
    /** For "write": parsed JSON payload. For "update-status": { field: string, value: string } */
    payload: unknown;
}
/**
 * Parses a bash command string to detect a store-cli write or update-status invocation.
 *
 * Handles forms produced by Forge workflows:
 *   node "$FORGE_ROOT/tools/store-cli.cjs" write task '{"taskId":"X",...}'
 *   node "/abs/path/to/store-cli.cjs" update-status task X status Y
 *
 * Returns null if the command does not invoke store-cli.cjs.
 *
 * NOTE (T02 scope): extraction only — no validation performed here.
 * T03 imports this function and layers schema validation on the returned payload.
 */
export declare function parseStoreCLIInvocation(command: string, _forgeRoot: string): StoreCLICall | null;
/**
 * Wire Forge hook semantics onto pi's tool_call and tool_result events.
 *
 * @param pi        The ExtensionAPI instance provided by pi at extension init.
 * @param forgeRoot Absolute path to the Forge plugin root (from .forge/config.json).
 *
 * AC#1: Both tool_call and tool_result handlers are registered.
 * AC#2: write calls validated via store-validator; blocked on schema violation.
 * AC#3: update-status calls checked via transition-guard; blocked on illegal transition.
 * AC#4: FORGE_HOOK_AUDIT=1 — all decisions logged, nothing blocked.
 * AC#5 (S30-T03): optional governor arg; no-op by default; called at tail of both chains.
 */
export declare function registerHookDispatcher(pi: ExtensionAPI, forgeRoot: string, governor?: ContextGovernor): void;