/**
 * Phase F-2-D (D1+D2+D3): `olam host-cp <subcommand>` — operator-facing
 * lifecycle for the host CP container.
 *
 * Subcommands:
 *   start  — generate token, audit port 19000, docker compose up, write PID
 *   stop   — docker compose down, remove PID + token
 *   status — diagnostic probe (with optional --json flag)
 *
 * Wraps the compose stack at `packages/host-cp/compose.yaml`. Token
 * lives at `~/.olam/host-cp.token` (chmod 600). PID file at
 * `~/.olam/host-cp.pid`. Both are operator-state files, not repo state.
 */
import type { Command } from 'commander';
/** Default host CP port. Matches packages/host-cp/compose.yaml. */
export declare const HOST_CP_PORT = 19000;
/** Path to the compose stack. Checked in order:
 *  1. Bundled-package path — used when installed via `npm install -g @pleri/olam-cli`.
 *  2. Monorepo cwd — used in source-mode dev (`pnpm dev:olam`).
 *  3. Monorepo parent cwd — fallback for nested cwd inside the repo.
 */
export declare function findComposeFile(): string;
/**
 * Path to the operator-state shared auth-service secret.
 *
 * Created by `olam auth up` when the auth-service container first
 * starts. Both the auth-service container and host-cp container must
 * use the same secret value as their `X-Olam-Secret` so host-cp's
 * `/credentials/*` calls authenticate correctly.
 *
 * Honors OLAM_HOME for tests (matches `olamHome()`).
 */
export declare function authSecretPath(): string;
/**
 * Read the shared auth-service secret from `~/.olam/auth-secret`.
 *
 * Returns null when the file is missing (auth-service was never started
 * or the file was deleted). Returns null instead of throwing because
 * `host-cp start` should still bring host-cp up — but it then logs a
 * loud warning so the operator notices that credential surfaces will
 * 401 until they run `olam auth up` to regenerate the secret.
 *
 * Empty/whitespace files are treated as "not set" (null) — a 0-byte
 * file would otherwise round-trip to compose as an empty env var,
 * which is exactly the silent-failure mode this whole helper exists
 * to prevent.
 */
export declare function readAuthSecret(): string | null;
export interface R2Credentials {
    account_id: string;
    bucket: string;
    access_key_id: string;
    secret_access_key: string;
    public_url_base: string;
}
/** Path to `~/.olam/r2-credentials.json`. Honors OLAM_HOME for tests. */
export declare function r2CredentialsPath(): string;
/**
 * Read R2 credentials from `~/.olam/r2-credentials.json`.
 *
 * Returns null when the file is missing — callers should print a clear
 * "operator must configure" error rather than throwing. Returns null for
 * malformed JSON so callers can surface a useful message instead of a
 * raw parse stack trace.
 */
export declare function readR2Credentials(): R2Credentials | null;
/**
 * Generate a fresh 32-byte hex token and write it to `tokenPath()` with
 * mode 0600. Creates the parent directory if missing. Idempotent: if a
 * token already exists, this overwrites it (each `start` regenerates).
 */
export declare function writeToken(): string;
export declare function readToken(): string | null;
export declare function removeToken(): boolean;
export declare function writePid(pid: number): void;
export declare function readPid(): number | null;
export declare function removePid(): boolean;
interface ContainerInfo {
    readonly id: string;
    readonly name: string;
    readonly state: string;
    readonly status: string;
}
export declare function findHostCpContainer(): Promise<ContainerInfo | null>;
/**
 * Phase host-cp-reliability: Probe for a running host CP, supporting
 * both bare-node (process on host) and container deployments.
 *
 * Strategy:
 *   1. HTTP probe: try http://127.0.0.1:19000/api/bootstrap. If the
 *      token file exists and the endpoint returns 200, host-cp is running.
 *      Mode is 'bare' if no docker container found, 'container' otherwise.
 *   2. Docker fallback: if HTTP probe fails, look for the docker container.
 *      If found+running, probe its port.
 *
 * Returns null if both fail, along with probe diagnostics in the
 * returned ProbeFailure for fail-loud error messages.
 *
 * @returns {Promise<{ url: string; mode: 'bare' | 'container' } | null>}
 *   Result on success, null on failure.
 */
export declare function probeHostCp(): Promise<{
    url: string;
    mode: 'bare' | 'container';
} | null>;
/**
 * Gather probe failure diagnostics for fail-loud error messages.
 * Returns structured info about what was tried and why it failed.
 */
export declare function gatherProbeFailureDiagnostics(): Promise<{
    bootstrapStatus: string;
    containerStatus: string;
}>;
/**
 * The compose service name that `olam host-cp start` pre-pulls before
 * `compose up`. Named as a constant so tests can assert this is NEVER
 * the host-cp service itself (which was already digest-pinned by
 * `olam bootstrap`; re-pulling it would bypass the digest-verification
 * step and potentially fetch a different image from the registry).
 *
 * Regression guard: if this is changed to a bare compose pull (no
 * service specified), `docker compose pull` would try to pull ALL
 * services — including `olam-host-cp`, which before PR #302 was a bare
 * image name that Docker resolved via Docker Hub → "pull access denied
 * for olam-host-cp, repository does not exist".
 */
export declare const SIDECAR_PULL_SERVICE = "docker-socket-proxy";
export interface ComposeResult {
    readonly ok: boolean;
    readonly stdout: string;
    readonly stderr: string;
}
export declare function runCompose(args: readonly string[], composeFile: string, extraEnv?: Record<string, string>): ComposeResult;
/**
 * Build the extra env vars to pass to `docker compose up`. Pure helper
 * extracted so the env-merge contract is unit-testable without spawning
 * docker. Returns an object with only the keys we set; absent values
 * are omitted so process.env defaults can win when the secret file is
 * missing (and the boot warning surfaces the gap).
 *
 * Exported for tests.
 */
export declare function buildComposeEnv(authSecret: string | null, ghToken?: string | null): Record<string, string>;
/**
 * Capture the operator's GitHub token by running `gh auth token` on the
 * host. Returns the token string on success, null when gh is not installed
 * or the operator is not authenticated.
 *
 * Never throws — callers that need a token should check for null and warn,
 * but must not block host-cp from starting.
 *
 * Exported for tests.
 */
export declare function captureGhToken(): string | null;
/** Exported for `olam begin` (D1) to delegate start logic without CLI re-parse. */
export declare function startHostCp(opts: {
    showToken: boolean;
}): Promise<void>;
/** Exported for `olam stop` (D2) to delegate stop logic without CLI re-parse. */
export declare function stopHostCp(): Promise<void>;
export declare function registerHostCp(program: Command): void;
/**
 * Phase D6 (olam-dogfood-vision): open a Host CP URL in the operator's
 * default browser.
 *
 * D-phase audit follow-up (HIGH-1): the helper now lives in
 * `@olam/core/src/util/open-url.ts` so both this CLI and the MCP
 * server can import it statically. Earlier shape duplicated the
 * helper here and required @olam/mcp-server to dynamic-import the
 * compiled CLI dist — fragile under stale-build conditions. Static
 * import via @olam/core (already a declared dep on both packages)
 * removes the cross-package dynamic-import + as-never-cast pattern.
 *
 * Re-exported here so existing callers don't need to update their
 * imports.
 */
export { openUrl as openHostCpUrl } from '@olam/core/src/util/open-url.js';
/**
 * Phase C8 (olam-dogfood-vision): generic host-cp proxy caller for
 * `/api/world/<id>/*` routes. Used by `olam lanes` subcommands to
 * reach the per-world CP through host-cp's auth-injecting proxy
 * (host-cp injects X-Olam-Secret server-side; the operator only
 * sees the Bearer token).
 *
 * Returns the parsed JSON body on success, or {ok:false, error} on
 * any failure (token missing, network error, non-2xx response).
 *
 * @param method
 * @param worldId
 * @param path  the per-world CP path including leading slash, e.g.
 *              '/lanes', '/lanes/foo', '/lanes/foo/dispatch'
 * @param body  optional JSON body for POST/DELETE
 */
export declare function callHostCpProxy(method: 'GET' | 'POST' | 'DELETE', worldId: string, path: string, body?: unknown): Promise<{
    ok: true;
    status: number;
    data: unknown;
} | {
    ok: false;
    status: number;
    error: string;
}>;
/**
 * POST/DELETE the host-cp admin registry endpoint. Exported so other
 * commands (create, destroy) can auto-register without re-implementing
 * the fetch dance.
 */
export declare function callHostCpRegistry(method: 'POST' | 'DELETE', body: {
    id: string;
    port?: number;
}): Promise<{
    ok: boolean;
    status: number;
    error?: string;
}>;
//# sourceMappingURL=host-cp.d.ts.map