@ovrdev/cli 0.1.0-alpha.16

package/dist/core/core.d.ts

@@ -0,0 +1,748 @@
+export { waitHttp, waitTcp, waitUntil, type WaitOptions } from "../util/ready.js";
+export { CONFIG_DIR, CONFIG_PATH } from "./config.js";
+export { randomString, randomPassword, randomHex } from "../util/random.js";
+export { parseDotenv } from "../util/dotenv.js";
+export { dotenv, type DotenvOptions } from "../env/dotenv-plugin.js";
+declare const REF: unique symbol;
+export type RefTarget = {
+    repo: string;
+    service: string;
+    key: string;
+};
+/** Any JSON-serializable value — what an export (and therefore a resolved ref) may carry. */
+export type JsonValue = string | number | boolean | null | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+declare const REF_T: unique symbol;
+export type Ref<T = JsonValue> = {
+    readonly [REF]: RefTarget;
+    readonly [REF_T]?: T;
+};
+export declare const isRef: (v: unknown) => v is Ref;
+export declare const refTarget: (r: Ref) => RefTarget;
+/** Collect every service a spec references (deduped by repo.service). */
+export declare function collectRefTargets(spec: unknown, out?: RefTarget[]): RefTarget[];
+/**
+ * Deep-clone a spec, replacing each Ref via `resolve` (which may yield any JSON value). A Ref
+ * that resolves to `undefined` drops its object key entirely (so the env var is left unset →
+ * Infisical wins). `null` is a real resolved value and is kept.
+ */
+export declare function resolveRefs(spec: unknown, resolve: (t: RefTarget) => JsonValue | undefined): unknown;
+/**
+ * Coerce resolved values into process-env strings (env vars are strings): primitives → `String`,
+ * arrays/objects → `JSON.stringify`. `undefined`/`null` drop the key (the env var stays unset).
+ */
+export declare function coerceEnv(obj: Record<string, unknown>): Record<string, string>;
+export type EnvMap = Record<string, string | Ref>;
+/** A process-env map — self-contained (no @types/node) so configs type-check without it. */
+export type EnvRecord = Record<string, string | undefined>;
+/** Minimal readable-stream shape; Node's `Readable` satisfies it (avoids a hard @types/node dep). */
+export type ReadableLike = {
+    on(event: string, listener: (...args: any[]) => void): unknown;
+};
+/** The value a provider publishes for others to reference. Ports are known at start time. */
+export type ExportsFn = (ctx: {
+    host: string;
+    port: number;
+    ports: Record<string, number>;
+}) => Record<string, string>;
+/** A payload a consumer announces to a provider (allowlist URL, CORS flag, …) — JSON values. */
+export type AnnouncePayload = Record<string, JsonValue>;
+/** What `service.announce(payload)` produces: the target `repo.service` + the payload. */
+export type Announcement = {
+    to: string;
+    payload: AnnouncePayload;
+};
+/** What a provider's `discovery` receives: each live announcement + who sent it (`repo.service`). */
+export type IncomingAnnouncement = {
+    from: string;
+    payload: AnnouncePayload;
+};
+/** The `.announce` member on a service node — callable, and (phantom) a Ref so the index accepts it. */
+type Announcer = Ref & ((payload: AnnouncePayload) => Announcement);
+export type ServiceExports = Ref & {
+    readonly announce: Announcer;
+    readonly [key: string]: Ref;
+};
+export type ServicesProxy = {
+    [service: string]: ServiceExports;
+};
+export type ReposProxy = {
+    [repo: string]: {
+        services: ServicesProxy;
+    };
+};
+export type WorkspaceContext = {
+    name: string;
+    /** This repo's own services: `workspace.services.<svc>.<key>`. */
+    services: ServicesProxy;
+    /** Cross-repo: `workspace.repos['<repo>'].services.<svc>.<key>`. */
+    repos: ReposProxy;
+};
+export type ConfigContext = {
+    workspace: WorkspaceContext;
+    /** Built-in kinds (no plugins in the single-arg form) — so `kind.shell` is always available. */
+    kind: {
+        shell: import("../plugins/shell.js").ShellKind<PrepareCtx>;
+    };
+};
+/** A provisioning step for a fresh worktree — a command, or a function of the repo context. */
+export type SetupStep = string | ((ctx: {
+    workspace: string;
+    repo: string;
+    dir: string;
+}) => string);
+export type RepoConfig = {
+    setup?: SetupStep[];
+    services: Record<string, ServiceDef>;
+    /** Config-level plugins (from the two-arg defineConfig head), provided once per run. */
+    plugins?: OvrPlugin[];
+    /** Config-declared environment actions (the `all` tab's menu) — seeds, one-offs. */
+    actions?: ServiceAction[];
+};
+export type ConfigFactory = (ctx: ConfigContext) => RepoConfig;
+/** Build the `{ workspace, kind }` context handed to a single-arg config factory (Ref-minting). */
+export declare function makeContext(workspaceName: string, repo: string): ConfigContext;
+/** A `workspace` whose leaves resolve to real export values — handed to `prepare` at start time. */
+export declare function resolvingWorkspace(name: string, ownRepo: string, resolve: (t: RefTarget) => JsonValue | undefined): WorkspaceContext;
+/** A `workspace` that records every ref its leaves are asked for (returns "") — for dry-run discovery. */
+export declare function recordingWorkspace(name: string, ownRepo: string): {
+    workspace: WorkspaceContext;
+    taken(): RefTarget[];
+};
+/** What the head's `plugins` factory receives — everything known before services exist. */
+export type HeadCtx = {
+    workspace: {
+        name: string;
+    };
+    repo: string;
+    dir: string;
+};
+export type ProvideCtx = {
+    /** Where the plugin is provided: env scope (`service` unset) or one service. */
+    scope: {
+        workspace: string;
+        repo: string;
+        dir: string;
+        service?: string;
+    };
+    /** Reserve a sticky port under a plugin-chosen key (e.g. a route name → stable URL). */
+    allocPort(key: string, label?: string): Promise<number>;
+    log(line: string): void;
+};
+export type InputOptionsCtx = {
+    exports: Record<string, string>;
+    helpers: Record<string, unknown>;
+};
+/** Choice options: a static list, or a resolver run when the form opens (autocomplete/dynamic). */
+export type ChoiceOptions = readonly string[] | ((ctx: InputOptionsCtx) => Promise<readonly string[]> | readonly string[]);
+export type ActionInput = {
+    kind: "text";
+    label: string;
+    default?: string;
+    placeholder?: string;
+} | {
+    kind: "choice";
+    label: string;
+    options: ChoiceOptions;
+    default?: string;
+} | {
+    kind: "confirm";
+    label: string;
+    default?: boolean;
+};
+/** Builders for action inputs (mirrors `ask.*`, but choice options may be dynamic). Each returns
+ * its SPECIFIC kind (not the widened union) so `action.*` can infer the value type per input. */
+export declare const input: {
+    text: (label: string, opts?: {
+        default?: string;
+        placeholder?: string;
+    }) => {
+        kind: "text";
+        label: string;
+        default?: string;
+        placeholder?: string;
+    };
+    choice: <const T extends ChoiceOptions>(label: string, options: T, opts?: {
+        default?: string;
+    }) => {
+        kind: "choice";
+        label: string;
+        options: T;
+        default?: string;
+    };
+    confirm: (label: string, opts?: {
+        default?: boolean;
+    }) => {
+        kind: "confirm";
+        label: string;
+        default?: boolean;
+    };
+};
+/** Collected input values, keyed by the `inputs` record key. */
+export type InputValues = Record<string, string | boolean>;
+/** The value type a single input yields (text→string, choice→its option union, confirm→boolean). */
+type InputValue<I> = I extends {
+    kind: "text";
+} ? string : I extends {
+    kind: "confirm";
+} ? boolean : I extends {
+    kind: "choice";
+    options: infer T;
+} ? T extends readonly string[] ? T[number] : string : string | boolean;
+/** Map an `inputs` record to its typed values — what `run`/`command`/`args`/`env` receive. */
+export type InputsValues<R extends Record<string, ActionInput>> = {
+    [K in keyof R]: InputValue<R[K]>;
+};
+/** Context handed to a `function` action's `run` — inputs + the service's exports + helpers. */
+export type ActionRunCtx = {
+    inputs: InputValues;
+    exports: Record<string, string>;
+    /** Capability helpers for this scope (what a plugin's `provide` returned), keyed by name. */
+    helpers: Record<string, unknown>;
+    service: string;
+    scope: {
+        workspace: string;
+        repo: string;
+        service: string;
+        dir: string;
+    };
+    log(line: string): void;
+};
+/** A plugin health/config check result, surfaced in the TUI's diagnostics panel. */
+export type Diagnostic = {
+    id: string;
+    status: "ok" | "warn" | "error";
+    message: string;
+    /** Id of one of this plugin's actions that fixes the problem (panel: enter runs it). */
+    fix?: string;
+};
+export type OvrPlugin<H = unknown> = {
+    name: string;
+    /** Service-kind constructors contributed to the factory's `kind.<name>` namespace. */
+    kinds?: Record<string, unknown>;
+    /** Action builders contributed to the factory's `action.<name>.*` namespace — plugin-scoped
+     * counterparts to action.session/fn. Each is a pure spec-constructor returning a ServiceAction;
+     * the plugin's provided helper reaches it at run via `ActionRunCtx.helpers`. */
+    actionKinds?: Record<string, unknown>;
+    /** Provision resources; the returned helpers appear in prepare ctx under `name`. */
+    provide?(ctx: ProvideCtx): H | Promise<H>;
+    /** Effect-free stand-in for the helpers, used while dry-running `prepare` for refs. */
+    stub?(): H;
+    /** Release provisioned resources (run end; service stop/restart when service-scoped). */
+    teardown?(helpers: H): void | Promise<void>;
+    /** Actions contributed at this plugin's scope. */
+    actions?(helpers: H): ServiceAction[];
+    /** Health/config checks — run after provide and on panel refresh; non-ok notify the user. */
+    diagnose?(helpers: H): Diagnostic[] | Promise<Diagnostic[]>;
+    /** A base-env source this plugin contributes (Infisical, dotenv, …), merged for each repo. */
+    envSource?: EnvSource;
+};
+/**
+ * Return types for plugin factories. The surfaces must be REQUIRED (not optional) on the
+ * returned type — `ContextOf`/`KindsOf` match `extends { provide/kinds: … }`, and an
+ * optional property never satisfies that.
+ */
+export type CapabilityPlugin<N extends string, H> = OvrPlugin<H> & {
+    name: N;
+    provide(ctx: ProvideCtx): H | Promise<H>;
+};
+export type KindsPlugin<N extends string, K> = OvrPlugin & {
+    name: N;
+    kinds: K;
+};
+/** A plugin contributing action builders under `action.<N>.*`. `A` must be REQUIRED so `ActionsOf`
+ * matches `extends { actionKinds: … }`. Combine with `CapabilityPlugin` when the builders read a
+ * provided helper: `CapabilityPlugin<"pg", PgApi> & ActionsPlugin<"pg", typeof actionKinds>`. */
+export type ActionsPlugin<N extends string, A> = OvrPlugin & {
+    name: N;
+    actionKinds: A;
+};
+type UnionToIntersection<U> = (U extends unknown ? (x: U) => void : never) extends (x: infer I) => void ? I : never;
+/** The prepare-ctx helpers a plugins tuple contributes, keyed by plugin name. */
+export type ContextOf<P extends readonly OvrPlugin[]> = UnionToIntersection<P[number] extends infer Pl ? Pl extends {
+    name: infer N extends string;
+    provide(ctx: ProvideCtx): infer R;
+} ? {
+    [K in N]: Awaited<R>;
+} : never : never> extends infer C ? C extends object ? C : object : object;
+/** What every service's `prepare` receives (capabilities merge in on top). */
+/** Options for a sticky secret: length, whether to include symbols, or hex encoding. */
+export type SecretOptions = {
+    length?: number;
+    symbols?: boolean;
+    hex?: boolean;
+};
+export type PrepareCtx = {
+    workspace: WorkspaceContext;
+    scope: {
+        workspace: string;
+        repo: string;
+        service: string;
+        dir: string;
+    };
+    /** Builtins live under namespaces so plugin names can't collide with them. */
+    ports: {
+        alloc(label?: string): Promise<number>;
+    };
+    /**
+     * Sticky secrets — a generated password/token that STAYS STABLE across runs and restarts
+     * (persisted per workspace/service/key, like ports). Use for a value a service stores, e.g.
+     * `prepare: async ({ secrets }) => ({ pw: secrets.get("db-password") })`.
+     */
+    secrets: {
+        get(key: string, opts?: SecretOptions): string;
+    };
+    /**
+     * Sticky data paths — a per-environment directory unique to this (workspace, service), created
+     * on ask and stable across runs (so a file-backed service keeps its data). Non-clashing across
+     * workspaces/forks by construction. Labels may nest: `paths.get("surrealkv/data")`.
+     */
+    paths: {
+        get(label?: string): string;
+    };
+    /** Ephemeral per-run dir (wiped each run) — build artifacts/fixtures you do NOT want to keep. */
+    scratch: {
+        get(label?: string): string;
+    };
+    /**
+     * Render a `{{var}}` template into a file, return its path. `template` is inline or `{ from }`
+     * (relative to the repo); output lands in the data dir unless `out` is given. For a config file
+     * a service needs with dynamic ports/paths baked in.
+     */
+    files: {
+        render(template: string | {
+            from: string;
+        }, vars?: Record<string, string | number>, opts?: {
+            name?: string;
+            out?: string;
+        }): string;
+    };
+    /** Run a side-effect once per environment (marker under the data dir; re-armed by `--reset-data`). */
+    once(key: string, fn: () => void | Promise<void>): Promise<void>;
+    /** Base env (env source + process env) with a fail-fast `require`. */
+    env: {
+        get(key: string, fallback?: string): string | undefined;
+        require(key: string): string;
+    };
+    /**
+     * Sticky cryptographic keys — a keypair generated once and persisted (like secrets), so a
+     * signing key (JWT/OIDC, SSH) stays stable across restarts. Returns PEM strings + `write()` to
+     * drop them in the data volume as files (for `--key-file`-style tools). ed25519 by default.
+     */
+    keys: {
+        pair(name: string, opts?: {
+            type?: "ed25519" | "rsa" | "ec";
+            modulusLength?: number;
+            curve?: string;
+        }): {
+            type: "ed25519" | "rsa" | "ec";
+            privateKey: string;
+            publicKey: string;
+            /** Public key as a JWK Set, for a `/.well-known/jwks.json` verify endpoint. */
+            jwks(opts?: {
+                use?: string;
+            }): {
+                keys: Record<string, string>[];
+            };
+            /** OpenSSH form: `publicKey` is an authorized_keys line; `privateKey` stays PEM (ed25519). */
+            ssh(opts?: {
+                comment?: string;
+            }): {
+                publicKey: string;
+                privateKey: string;
+            };
+            write(opts?: {
+                name?: string;
+            }): {
+                privateKeyPath: string;
+                publicKeyPath: string;
+            };
+        };
+    };
+};
+/** A service is "ready" (dependents may start) when this resolves. `bag` = prepare's return. */
+export type ReadyFn<Bag = unknown> = (bag: Bag) => Promise<void>;
+/** Context for a provider's `discovery` reconcile — log + a self-restart (e.g. supabase reloading). */
+export type DiscoveryCtx = {
+    log(line: string): void;
+    restart(): void;
+};
+/** A provider's reconcile over the LIVE set of announcements targeting it (called on every change). */
+export type DiscoveryFn = (announcements: IncomingAnnouncement[], ctx: DiscoveryCtx) => void | Promise<void>;
+/** The engine-recognized envelope on every kind's spec (the rest stays plugin-opaque). */
+export type ServiceEnvelope = {
+    prepare?: (ctx: never) => unknown;
+    plugins?: readonly OvrPlugin[];
+    /** Config-declared actions, merged into the service's TUI menu after the plugin's own. */
+    actions?: ServiceAction[];
+    /** Resolves when the service is up; gates dependents. Use waitHttp/waitTcp or any async fn. */
+    ready?: ReadyFn;
+    /** Services this one needs UP before it starts — typed readiness refs (`x.ready`). */
+    waitFor?: readonly Ref[];
+    /** Announcements this service pushes to others (`svc.announce({...})`) — a function of the bag. */
+    announce?: (bag: never) => Announcement[];
+    /** Reconcile the live set of announcements targeting this service (allowlist/CORS/redirect). */
+    discovery?: DiscoveryFn;
+};
+export type AskSpec = {
+    kind: "choice";
+    question: string;
+    options: readonly string[];
+    default?: string;
+} | {
+    kind: "confirm";
+    question: string;
+    default?: boolean;
+};
+export declare const ask: {
+    /** A one-of choice (numbered prompt). */
+    choice: <const O extends readonly string[]>(question: string, options: O, opts?: {
+        default?: O[number];
+    }) => {
+        kind: "choice";
+        question: string;
+        options: O;
+        default?: O[number];
+    };
+    /** A yes/no confirmation. */
+    confirm: (question: string, opts?: {
+        default?: boolean;
+    }) => {
+        kind: "confirm";
+        question: string;
+        default?: boolean;
+    };
+};
+type AnswerOf<A> = A extends {
+    kind: "choice";
+    options: infer O extends readonly string[];
+} ? O[number] : A extends {
+    kind: "confirm";
+} ? boolean : never;
+export type AnswersOf<A> = {
+    [K in keyof A]: AnswerOf<A[K]>;
+};
+export type Answers = Record<string, string | boolean>;
+/** Fill unanswered asks from spec defaults; a missing default is a hard, actionable error. */
+export declare function applyAskDefaults(asks: Record<string, AskSpec>, answers: Answers, repo: string): Answers;
+/**
+ * Augmentable kind registry: a kind-contributing plugin module declares
+ * `interface KindRegistry<Ctx> { <name>: <ItsKinds<Ctx>> }` so `kind.<name>.*` is typed
+ * with the config's capability context. Presence stays sound — a plugin's kinds only
+ * appear when its factory is actually in the `plugins` tuple.
+ */
+export interface KindRegistry<Ctx> {
+}
+type KindsOf<P extends readonly OvrPlugin[], Ctx> = UnionToIntersection<P[number] extends infer Pl ? Pl extends {
+    name: infer N extends string;
+    kinds: infer K;
+} ? N extends keyof KindRegistry<Ctx> ? Pick<KindRegistry<Ctx>, N> : {
+    [Key in N]: K;
+} : never : never> extends infer M ? M extends object ? M : object : object;
+/** The action builders a plugins tuple contributes, keyed by plugin name — exposed as `action.<name>.*`. */
+type ActionsOf<P extends readonly OvrPlugin[]> = UnionToIntersection<P[number] extends infer Pl ? Pl extends {
+    name: infer N extends string;
+    actionKinds: infer A;
+} ? {
+    [K in N]: A;
+} : never : never> extends infer M ? M extends object ? M : object : object;
+/** What the config factory receives in the two-arg form. */
+export type FactoryCtx<P extends readonly OvrPlugin[]> = {
+    workspace: WorkspaceContext;
+    kind: {
+        shell: import("../plugins/shell.js").ShellKind<PrepareCtx & ContextOf<P>>;
+    } & KindsOf<P, PrepareCtx & ContextOf<P>>;
+    /** action.session/fn/handover plus each plugin's `action.<name>.*` builders. */
+    action: typeof action & ActionsOf<P>;
+};
+declare const FACTORY: unique symbol;
+declare const HEAD: unique symbol;
+/** Internal evaluated-config factory: receives full identity, returns the config + plugins. */
+type EvalFactory = (ctx: {
+    workspace: string;
+    repo: string;
+    dir: string;
+    answers?: Answers;
+}) => RepoConfig;
+export type ConfigModule = {
+    [FACTORY]: EvalFactory;
+    [HEAD]?: {
+        asks: Record<string, AskSpec>;
+    };
+};
+/** The asks a config module declares (modes included) — the loader resolves them pre-eval. */
+export declare const configAsks: (mod: unknown) => Record<string, AskSpec>;
+/** The body a two-arg factory returns (plugins come from the head). */
+export type RepoConfigBody = {
+    setup?: SetupStep[];
+    services: Record<string, ServiceDef>;
+    /** Environment-wide actions (the `all` tab's menu) — seeds, provisioning, one-offs. */
+    actions?: ServiceAction[];
+};
+/**
+ * Author a repo's services.
+ * - `defineConfig(factory)` / `defineConfig(config)` — the plugin-less form.
+ * - `defineConfig({ plugins }, ({ workspace, kind }) => body)` — plugins (or a factory of
+ *   HeadCtx returning them) thread their capabilities into every prepare ctx and their
+ *   kinds into `kind.*`, fully typed from the tuple.
+ */
+export declare function defineConfig(input: ConfigFactory | RepoConfig): ConfigModule;
+export declare function defineConfig<const P extends readonly OvrPlugin[], const M extends readonly string[] = readonly string[], const A extends Record<string, AskSpec> = Record<never, AskSpec>>(head: {
+    plugins?: P | ((ctx: HeadCtx) => P);
+    /** Named run modes — sugar for an `asks.mode` choice; lands as `mode` in the factory ctx. */
+    modes?: M;
+    /** Mode used without prompting when nothing was answered yet. */
+    defaultMode?: M[number];
+    /** Interactive inputs, resolved once before the factory runs; sticky per workspace. */
+    asks?: A;
+}, factory: (ctx: FactoryCtx<P> & {
+    mode: M[number];
+    answers: AnswersOf<A>;
+}) => RepoConfigBody): ConfigModule;
+export declare const isConfigModule: (v: unknown) => v is ConfigModule;
+/** Evaluate a loaded config module (or bare factory/plain object) into a RepoConfig. */
+export declare function evalConfig(mod: unknown, workspace: string, repo: string, dir?: string, answers?: Answers): RepoConfig;
+/** What every plugin helper returns. `spec` is opaque to the engine (Refs aside). */
+export type ServiceDef = {
+    plugin: Plugin;
+    spec: unknown;
+};
+export type Registry = {
+    register(name: string, value: string): void;
+    discover(name: string): string | undefined;
+};
+export type StartCtx = {
+    scope: {
+        workspace: string;
+        repo: string;
+        service: string;
+        dir: string;
+    };
+    /**
+     * Reserve a port. Sticky per service slot: the same slot gets the same port across
+     * starts AND restarts (re-discovered only if taken), so exports stay stable. Unlabeled
+     * calls slot by call ordinal; multi-port plugins should pass a label (`allocPort("db")`)
+     * so slots survive call-order changes.
+     */
+    allocPort(label?: string): Promise<number>;
+    /**
+     * Resolve a cross-service Ref to its value (local export, or undefined when it bubbles to
+     * the env source). The engine pre-resolves refs in the static spec; plugins with
+     * function-valued fields (e.g. shell's `env`) resolve refs in the function's output here.
+     */
+    resolve(target: RefTarget): JsonValue | undefined;
+    /**
+     * A `workspace` whose refs resolve to real sibling values — handed to `prepare` so it can
+     * read a started sibling's export (a local override; a bubbled ref reads as undefined,
+     * since that value lives in the env source, not ovr's resolver).
+     */
+    workspace: WorkspaceContext;
+    /** The value `prepare` returned (undefined when the spec has none) — engine-run. */
+    bag: unknown;
+    /** Base env from the env source (e.g. Infisical); the plugin merges its resolved spec.env on top. */
+    env: EnvRecord;
+    /** Multiplexed, prefixed log sink for this service. */
+    log(line: string): void;
+    /** Line-split a child stream into the prefixed log sink; `map` rewrites each line. */
+    pipe(stream: ReadableLike | null, map?: (line: string) => string): void;
+    /**
+     * A named child stream of this service — its own pane/row in the TUI (nested under the
+     * service; the parent pane shows all children merged). Lifecycle stays with the parent;
+     * subs carry logs, a status dot, and optionally their own actions. Idempotent per name.
+     */
+    sub(name: string, opts?: {
+        actions?: ServiceAction[];
+    }): SubStream;
+    registry: Registry;
+};
+/** What `StartCtx.sub()` hands back — a scoped sink for one child stream. */
+export type SubStream = {
+    log(line: string): void;
+    pipe(stream: ReadableLike | null, map?: (line: string) => string): void;
+    setStatus(status: "running" | "exited" | "failed"): void;
+};
+/**
+ * A source of base (hosted) env — Infisical today, but pluggable (doppler, dotenv, …). The
+ * engine asks the configured source for the base env before starting services; overridden
+ * services then override specific keys via their resolved refs.
+ */
+export type EnvSource = {
+    name: string;
+    /**
+     * Load base env for one repo. `env` is the abstract environment NAME the workspace is running
+     * as (dev/prod/staging — sticky per workspace, set by `ovr run --env <name>`); each source
+     * translates it (infisical → a slug; dotenv → `.env.<name>`). Undefined → the source's default.
+     */
+    load(ctx: {
+        workspace: string;
+        repo: string;
+        dir: string;
+        env?: string;
+    }): Promise<Record<string, string>> | Record<string, string>;
+};
+/**
+ * A plugin-contributed, per-service action (surfaced in the TUI's action menu).
+ * - session (DEFAULT): a declarative command spec — the TUI runs it in a PTY-backed
+ *   session tab (full terminal emulation: attach/detach, background, concurrent).
+ * - handover: explicit opt-in for programs that must own the real terminal; `run()`
+ *   blocks until done.
+ */
+/** Fields common to every action variant. */
+type ActionBase = {
+    id: string;
+    label: string;
+    /** Menu grouping (e.g. plugin name, or a custom "Tasks" group). Ungrouped if omitted. */
+    category?: string;
+    /** A form the TUI collects before running; values thread into command/args/env or run. */
+    inputs?: Record<string, ActionInput>;
+};
+/** A field that is a value or a (pure) function of the collected inputs. */
+type OrInputs<T> = T | ((values: InputValues) => T);
+export type ServiceAction = (ActionBase & {
+    mode?: "session";
+    command: OrInputs<string>;
+    args?: OrInputs<string[]>;
+    /** Working directory; config-declared actions default to the repo's dir. */
+    cwd?: string;
+    /**
+     * Run through your login shell (`$SHELL -lic`) so it sources your profile
+     * (`~/.zshrc`, `~/.zprofile`, …). Use when the command isn't on the engine's PATH —
+     * `bunx`, `nvm`/`rbenv`/`pyenv` shims, Homebrew paths. Default: exec the command directly.
+     */
+    login?: boolean;
+    env?: Record<string, string | Ref | undefined> | ((values: InputValues) => EnvRecord);
+    /** Tab title; defaults to the action id. */
+    title?: string;
+    /**
+     * Remove the session tab after a CLEAN exit once it's no longer being viewed
+     * (default). Failures always stay for inspection. Set false for sessions whose
+     * output should persist as a record.
+     */
+    autoclose?: boolean;
+}) | (ActionBase & {
+    mode: "handover";
+    run(values: InputValues): void;
+}) | (ActionBase & {
+    /** A JS action — no process. Gets inputs + the service's exports + plugin helpers. */
+    mode: "function";
+    run(ctx: ActionRunCtx): void | Promise<void>;
+});
+/** Fields shared by every `action.*` builder — the base + typed `inputs`. */
+type ActionSpecBase<R extends Record<string, ActionInput>> = {
+    id: string;
+    label: string;
+    /** Menu grouping (e.g. plugin name, or a custom "Tasks" group). Ungrouped if omitted. */
+    category?: string;
+    /** A form the TUI collects before running; each key's value type flows into the callbacks. */
+    inputs?: R;
+};
+/**
+ * Builders for actions — the typed counterpart to raw `ServiceAction` literals. Their payoff is
+ * INFERENCE: `inputs` value types thread into `command`/`args`/`env` (session) and `run` (fn/
+ * handover), so `ctx.inputs.kind` is the choice's option union, not `string | boolean`. The
+ * engine still consumes plain `ServiceAction` — these just build one.
+ */
+export declare const action: {
+    /** A PTY command (default). Set `login` to source your shell profile (bunx, nvm, …). */
+    session: <const R extends Record<string, ActionInput> = Record<never, ActionInput>>(spec: ActionSpecBase<R> & {
+        command: string | ((values: InputsValues<R>) => string);
+        args?: string[] | ((values: InputsValues<R>) => string[]);
+        env?: Record<string, string | Ref | undefined> | ((values: InputsValues<R>) => EnvRecord);
+        cwd?: string;
+        login?: boolean;
+        title?: string;
+        autoclose?: boolean;
+    }) => ServiceAction;
+    /** A JS action — `run(ctx)` gets typed `inputs` + the service's exports + plugin helpers. */
+    fn: <const R extends Record<string, ActionInput> = Record<never, ActionInput>>(spec: ActionSpecBase<R> & {
+        run: (ctx: Omit<ActionRunCtx, "inputs"> & {
+            inputs: InputsValues<R>;
+        }) => void | Promise<void>;
+    }) => ServiceAction;
+    /** An action that owns the real terminal — `run(values)` blocks until done. */
+    handover: <const R extends Record<string, ActionInput> = Record<never, ActionInput>>(spec: ActionSpecBase<R> & {
+        run: (values: InputsValues<R>) => void;
+    }) => ServiceAction;
+};
+export type Started = {
+    /** Named values other services reference (ports now known). Any JSON value. */
+    exports?: Record<string, JsonValue>;
+    /** Short display hint for UIs (e.g. ":52662"). */
+    info?: string;
+    /** Actions the TUI offers for this service (shell into container, etc.). */
+    actions?: ServiceAction[];
+    /** Resolves when healthy; gates dependents. */
+    ready?: Promise<void>;
+    /** Resolves when the service's process exits (lets the engine end cleanly). */
+    exited?: Promise<void>;
+    /**
+     * A persistable identity of the running instance (e.g. `{ pid }`, a container name) — recorded
+     * in the running-services registry so another session can check liveness (`Plugin.status`) and,
+     * later, reuse it. Omit for kinds with no external instance to track.
+     */
+    handle?: JsonValue;
+    stop(): void | Promise<void>;
+};
+/** Dry-run tools handed to `Plugin.refs` for discovering refs inside function/prepare fields. */
+export type RefTools = {
+    /** A recording workspace + a getter for the refs it logged (for dry-running `prepare`). */
+    recordWorkspace(): {
+        workspace: WorkspaceContext;
+        taken(): RefTarget[];
+    };
+    /** Stub port allocator (returns a placeholder; no real reservation during discovery). */
+    allocPort(label?: string): Promise<number>;
+    scope: StartCtx["scope"];
+};
+/** Context for `Plugin.plan` — enough to run prepare+exports with real ports, no runtime. */
+export type PlanCtx = {
+    scope: StartCtx["scope"];
+    /** Real sticky allocation (same ports the eventual start will reuse). */
+    allocPort(label?: string): Promise<number>;
+    /** Real sticky secret (same value the eventual start will reuse). */
+    secret(key: string, opts?: SecretOptions): string;
+    /** Real sticky data dir (same path the eventual start will reuse). */
+    path(label?: string): string;
+    /** A workspace resolving already-planned sibling exports; unknown → the pending sentinel. */
+    workspace: WorkspaceContext;
+    /** Effect-free capability helpers (stubs) for prepare. */
+    caps: Record<string, unknown>;
+    /** Marker returned for anything not resolvable in the plan phase (→ the export is runtime). */
+    pending: string;
+};
+export type Plugin<Spec = unknown> = {
+    name: string;
+    start(spec: Spec, ctx: StartCtx): Promise<Started>;
+    /**
+     * Surface the refs this spec consumes. Optional — omit it and the engine deep-walks the
+     * spec (correct for static specs). A plugin with ref-bearing function fields implements
+     * this: invoke `env` with a placeholder bag and/or dry-run `prepare` with `tools`'
+     * recording workspace + stub caps, then return the refs collected/recorded.
+     */
+    refs?(spec: Spec, tools: RefTools): RefTarget[] | Promise<RefTarget[]>;
+    /**
+     * Compute the exports knowable BEFORE start (ports/routes allocated in prepare) — so a ref
+     * to one of them resolves from the plan and never gates start-ordering. Return only clean,
+     * plan-resolvable values; drop (or leave `pending`-tainted) anything that needs the service
+     * running (e.g. a key read from a live process). Omit the method → all exports are treated
+     * as runtime (dependents wait for readiness). Not port-specific: a portless `url` is just as
+     * plan-resolvable as a numeric port.
+     */
+    plan?(spec: Spec, ctx: PlanCtx): Record<string, JsonValue> | Promise<Record<string, JsonValue>>;
+    /**
+     * Authoritative liveness for a persisted instance `handle` (from a prior `Started.handle`) —
+     * how THIS kind checks whether its instance is still running (shell: is the pid alive; docker:
+     * is the container up). Omit → the engine falls back to a generic pid check on the handle/owner.
+     */
+    status?(handle: JsonValue): "up" | "down" | Promise<"up" | "down">;
+    /**
+     * Stop an instance from its persisted `handle` — used when the LAST consumer of a shared
+     * service is not the run that started it (so there's no in-memory `Started` to call `stop()`
+     * on). shell kills the process group; docker stops the container. Omit → the shared service
+     * can't be torn down from a handle (it lingers until its owner exits or `ovr stop`).
+     */
+    stop?(handle: JsonValue): void | Promise<void>;
+};
+/** Refs a service consumes — plugin-provided (function/prepare fields) or a static spec walk. */
+export declare function serviceRefs(def: ServiceDef, tools: RefTools): Promise<RefTarget[]>;