import { SpClientOptions, SpClientState, SpClient } from '@openape/cli-auth';
export { fmtTime, printJson, printLine, printNdjson } from '@openape/cli-auth';
import * as citty from 'citty';
import { CommandDef } from 'citty';

/**
 * The fields that differ between two proof-link CLIs (tasks, testrun, pr, …).
 * The shared command builders are parameterised entirely by this — each app's
 * `cli.ts` stays the composition root (it owns the command order and the
 * top-level meta), and only sources the shared command *bodies* from here.
 */
interface ProofCliDescriptor {
    /** Short app name, e.g. `tasks`. Surfaces in help text, the SP-token cache, and messages. */
    name: string;
    /** Default API endpoint, e.g. `https://tasks.openape.ai`. */
    endpoint: string;
    /** Env var that overrides the endpoint, e.g. `APE_TASKS_ENDPOINT`. */
    envVar: SpClientOptions['envVar'];
    /** SP audience for token exchange, e.g. `tasks.openape.ai`. */
    aud: SpClientOptions['defaultAud'];
    /** Config file under `~/.openape/`, e.g. `auth-tasks.json`. */
    configFile: SpClientOptions['configFile'];
}

/**
 * Build the shared SP client from a descriptor. Thin mapping over
 * `createSpClient` — the per-app `client.ts` becomes a one-liner that calls
 * this and re-exports the pieces its domain commands already import.
 *
 * `TState` lets an app widen the persisted state (e.g. tasks adds
 * `activeTeamId`) while keeping the generic endpoint/token handling shared.
 */
declare function createProofClient<TState extends SpClientState = SpClientState>(d: Pick<ProofCliDescriptor, 'endpoint' | 'envVar' | 'aud' | 'configFile'>): SpClient<TState>;

/** ULID: 10 time chars (unix ms) + 16 chars of randomness, Crockford base32. */
declare function ulid(nowMs?: number): string;
interface AttentionActor {
    /** DDISA subject of whoever runs the CLI. */
    actor: string;
    actorKind: 'human' | 'agent';
    /** Opaque work reference ("ape-tasks:<id>"); groups a task's whole chain. */
    taskRef: string;
}
interface VerdictBriefing {
    /** Headline — the PR title, so the card is readable without opening it. */
    title?: string;
    /** Executive summary of what the change does and why. */
    summary?: string;
    /** Short facts a reviewer wants up front (diff size, proofs, risks). */
    highlights?: string[];
}
/** The pair a finished PR upload raises: a verdict call and its proof. */
declare function verdictRequestedEvents(who: AttentionActor, prUrl: string, nowSeconds: number, briefing?: VerdictBriefing): ({
    type: string;
    payload: {
        highlights?: string[] | undefined;
        summary?: string | undefined;
        title?: string | undefined;
        kind: string;
        pr_url: string;
    };
    ts: number;
    actor: string;
    actor_kind: "human" | "agent";
    task_ref: string;
    id: string;
} | {
    type: string;
    payload: {
        url: string;
        kind: string;
    };
    ts: number;
    actor: string;
    actor_kind: "human" | "agent";
    task_ref: string;
    id: string;
})[];
/** A proof link the human should be able to open straight from the card. */
declare function proofAttachedEvent(who: AttentionActor, url: string, kind: 'pr' | 'testrun' | 'screenshot' | 'log', nowSeconds: number): {
    id: string;
    ts: number;
    actor: string;
    actor_kind: "human" | "agent";
    task_ref: string;
    type: string;
    payload: {
        url: string;
        kind: "pr" | "testrun" | "screenshot" | "log";
    };
};
/**
 * Lifecycle of a piece of work — no card, no buzz. These are what the metrics
 * (waiting time, autonomy rate) are later computed from.
 */
declare function lifecycleEvent(who: AttentionActor, type: 'work.started' | 'task.shipped', nowSeconds: number): {
    id: string;
    ts: number;
    actor: string;
    actor_kind: "human" | "agent";
    task_ref: string;
    type: "work.started" | "task.shipped";
    payload: {};
};
/**
 * Post events to troop's inbox. Best-effort by design: a troop outage must
 * never fail the command the user actually ran, so failures warn and return
 * the count that got through.
 */
declare function emitAttentionEvents(events: Array<Record<string, unknown>>, onWarn?: (message: string) => void): Promise<number>;

/**
 * Stub login command. Proof-link CLIs no longer manage their own login flow —
 * auth is shared across all OpenApe CLIs via `@openape/cli-auth`, which reads
 * the IdP token written by `apes login` (`~/.config/apes/auth.json`). The
 * message stays app-agnostic so no per-app CLI name can drift out of sync.
 */
declare function makeLoginCommand(_d?: Pick<ProofCliDescriptor, 'name'>): citty.CommandDef<{
    email: {
        type: "positional";
        required: false;
        description: string;
    };
}>;

/**
 * Drop the cached SP-token for this app's endpoint. Doesn't touch the IdP
 * session — that's owned by `apes login` / `apes logout`. `--legacy` also
 * deletes the pre-1.0 `~/.openape/<configFile>` if it's still around.
 */
declare function makeLogoutCommand(d: Pick<ProofCliDescriptor, 'name' | 'aud' | 'configFile'>, client: SpClient<SpClientState>): citty.CommandDef<{
    endpoint: {
        type: "string";
        description: string;
    };
    legacy: {
        type: "boolean";
        description: string;
    };
}>;

/**
 * Print the current caller identity as seen by the server.
 *
 * EXAMPLE
 *   $ ape-<app> whoami
 *   patrick@example.com (human)  endpoint https://<app>.openape.ai
 */
declare function makeWhoamiCommand(d: Pick<ProofCliDescriptor, 'name'>, client: SpClient<SpClientState>): citty.CommandDef<{
    json: {
        type: "boolean";
        description: string;
    };
    endpoint: {
        type: "string";
        description: string;
    };
}>;

/**
 * Print bundled documentation. The mechanism (list topics / print one) is
 * shared; the topic set and Markdown content are app-specific, so the app
 * passes its own `docs` map (its `cli.ts` imports the `.md` files via the
 * bundler and hands them in).
 */
declare function makeDocsCommand(d: Pick<ProofCliDescriptor, 'name'>, docs: Record<string, string>): citty.CommandDef<{
    topic: {
        type: "positional";
        required: false;
        description: string;
    };
}>;

/**
 * Run a proof-link CLI: same error handling for every app. Maps the
 * `{ title, detail, status }` shape thrown by `@openape/cli-auth`'s `ApiError`
 * to a clean stderr message + non-zero exit.
 */
declare function runProofCli(main: CommandDef): Promise<void>;

interface OutputOptions {
    json?: boolean;
    quiet?: boolean;
}
declare function info(msg: string, opts?: OutputOptions): void;
declare function error(msg: string): void;

export { type AttentionActor, type OutputOptions, type ProofCliDescriptor, type VerdictBriefing, createProofClient, emitAttentionEvents, error, info, lifecycleEvent, makeDocsCommand, makeLoginCommand, makeLogoutCommand, makeWhoamiCommand, proofAttachedEvent, runProofCli, ulid, verdictRequestedEvents };