@hmcs/sdk 1.0.0

package/dist/commands.d.ts

@@ -0,0 +1,852 @@
+import { ZodType } from 'zod';
+import { EventSource } from 'eventsource';
+
+/**
+ * Mathematical types and interfaces for 3D graphics and spatial calculations.
+ *
+ * This module provides type definitions for common mathematical concepts used
+ * throughout the Desktop Homunculus SDK, including transforms, vectors, and
+ * domain-specific request/response types.
+ * These types are designed to be compatible with Bevy's math system.
+ *
+ * @example
+ * ```typescript
+ * // Working with transforms
+ * const transform: TransformArgs = {
+ *   translation: [0, 100, 0],
+ *   rotation: [0, 0, 0, 1],
+ *   scale: [1, 1, 1]
+ * };
+ *
+ * // Working with vectors
+ * const position: Vec3 = [10, 20, 30];
+ * const screenPos: Vec2 = [1920, 1080];
+ * ```
+ */
+/**
+ * Represents a 3D transformation containing position, rotation, and scale.
+ *
+ * This is the core type for positioning objects in 3D space. All spatial
+ * operations in Desktop Homunculus use this transform representation,
+ * which is compatible with Bevy's Transform component.
+ *
+ * @example
+ * ```typescript
+ * const identity: Transform = {
+ *   translation: [0, 0, 0],
+ *   rotation: [0, 0, 0, 1],
+ *   scale: [1, 1, 1]
+ * };
+ * ```
+ */
+interface Transform {
+    /**
+     * The position of the entity in world space.
+     * Format: [x, y, z] where Y is typically up in Bevy's coordinate system.
+     */
+    translation: [number, number, number];
+    /**
+     * The rotation of the entity in world space, represented as a quaternion.
+     * Format: [x, y, z, w] where [0, 0, 0, 1] represents no rotation (identity).
+     */
+    rotation: [number, number, number, number];
+    /**
+     * The scale of the entity in world space.
+     * Format: [x, y, z] where [1, 1, 1] represents normal size.
+     */
+    scale: [number, number, number];
+}
+/**
+ * Represents a 3D vector as [x, y, z].
+ * Used for 3D positions, directions, and mathematical calculations.
+ * Compatible with Bevy's Vec3 serialization format.
+ */
+type Vec3 = [number, number, number];
+/**
+ * Represents a quaternion rotation as [x, y, z, w].
+ * Compatible with Bevy's Quat serialization format.
+ */
+type Quat = [number, number, number, number];
+/** Transform arguments for API requests. Partial version of Transform. */
+interface TransformArgs {
+    translation?: Vec3;
+    rotation?: Quat;
+    scale?: Vec3;
+}
+
+/** Global viewport coordinates (screen-space position) as [x, y]. */
+type GlobalViewport = [number, number];
+
+/**
+ * Big Five personality traits (OCEAN model).
+ *
+ * @example
+ * ```typescript
+ * const ocean: Ocean = {
+ *   openness: 0.8,
+ *   conscientiousness: 0.6,
+ *   extraversion: 0.7,
+ * };
+ * ```
+ */
+interface Ocean {
+    /** Openness (0.0=conservative, 1.0=curious) */
+    openness?: number;
+    /** Conscientiousness (0.0=spontaneous, 1.0=organized) */
+    conscientiousness?: number;
+    /** Extraversion (0.0=introverted, 1.0=extroverted) */
+    extraversion?: number;
+    /** Agreeableness (0.0=independent, 1.0=cooperative) */
+    agreeableness?: number;
+    /** Neuroticism (0.0=stable, 1.0=sensitive) */
+    neuroticism?: number;
+}
+/**
+ * Persona data for a VRM character.
+ *
+ * @example
+ * ```typescript
+ * const persona: Persona = {
+ *   profile: "A cheerful virtual assistant",
+ *   personality: "Friendly and helpful",
+ *   ocean: { openness: 0.8, extraversion: 0.7 },
+ *   metadata: {},
+ * };
+ * ```
+ */
+interface Persona {
+    /** Character profile/background description. */
+    profile: string;
+    /** Personality description in natural language. */
+    personality?: string | null;
+    /** Big Five personality parameters. */
+    ocean: Ocean;
+    /** Extension metadata for MODs. */
+    metadata: Record<string, unknown>;
+}
+/** Override type for expression override settings. */
+type OverrideType = "none" | "blend" | "block";
+/**
+ * Information about a single VRM expression.
+ *
+ * @example
+ * ```typescript
+ * const vrm = await Vrm.findByName("MyAvatar");
+ * const { expressions } = await vrm.expressions();
+ * for (const expr of expressions) {
+ *   console.log(`${expr.name}: weight=${expr.weight}, binary=${expr.isBinary}`);
+ * }
+ * ```
+ */
+interface ExpressionInfo {
+    /** Expression name (e.g. "happy", "aa", "blink"). */
+    name: string;
+    /** Current weight value (0.0-1.0). */
+    weight: number;
+    /** Whether this expression is binary (snaps to 0 or 1). */
+    isBinary: boolean;
+    /** Override type for blink expressions. */
+    overrideBlink: OverrideType;
+    /** Override type for lookAt expressions. */
+    overrideLookAt: OverrideType;
+    /** Override type for mouth expressions. */
+    overrideMouth: OverrideType;
+}
+/** Response for VRM expression queries. */
+interface ExpressionsResponse {
+    expressions: ExpressionInfo[];
+}
+/** Spring bone physics properties. */
+interface SpringBoneProps {
+    stiffness: number;
+    dragForce: number;
+    gravityPower: number;
+    gravityDir: [number, number, number];
+    hitRadius: number;
+}
+/** A single spring bone chain. */
+interface SpringBoneChain {
+    entity: number;
+    joints: string[];
+    props: SpringBoneProps;
+}
+/** Response for spring bone chains query. */
+interface SpringBoneChainsResponse {
+    chains: SpringBoneChain[];
+}
+/** Repeat settings for VRMA playback. */
+interface VrmaRepeat {
+    type: "forever" | "never" | "count";
+    count?: number;
+}
+/** Request body for playing a VRMA animation. */
+interface VrmaPlayRequest {
+    asset: string;
+    transitionSecs?: number;
+    repeat?: VrmaRepeat;
+    waitForCompletion?: boolean;
+    /** If true, resets SpringBone velocities to prevent bouncing during animation transitions. */
+    resetSpringBones?: boolean;
+}
+/** State of a VRMA animation. */
+interface VrmaState {
+    playing: boolean;
+    repeat: string;
+    speed: number;
+    elapsedSecs: number;
+}
+/** Info about a VRMA animation entity. */
+interface VrmaInfo {
+    entity: number;
+    name: string;
+    playing: boolean;
+}
+/** Current look-at state of a VRM. */
+type LookAtState = {
+    type: "cursor";
+} | {
+    type: "target";
+    entity: number;
+};
+/**
+ * Snapshot of a VRM instance with full runtime state.
+ *
+ * @example
+ * ```typescript
+ * const snapshots = await Vrm.findAllDetailed();
+ * for (const s of snapshots) {
+ *   console.log(`${s.name}: ${s.state} at (${s.globalViewport?.[0]}, ${s.globalViewport?.[1]})`);
+ * }
+ * ```
+ */
+interface VrmSnapshot {
+    entity: number;
+    name: string;
+    state: string;
+    transform: Transform;
+    globalViewport: GlobalViewport | null;
+    expressions: ExpressionsResponse;
+    animations: VrmaInfo[];
+    lookAt: LookAtState | null;
+    linkedWebviews: number[];
+    persona: Persona;
+}
+/**
+ * Response from the VRM position endpoint.
+ *
+ * @example
+ * ```ts
+ * const vrm = await Vrm.findByName("MyCharacter");
+ * const pos = await vrm.position();
+ * console.log(`Screen: (${pos.globalViewport?.[0]}, ${pos.globalViewport?.[1]})`);
+ * console.log(`World: (${pos.world[0]}, ${pos.world[1]}, ${pos.world[2]})`);
+ * ```
+ */
+interface PositionResponse {
+    /** Global screen coordinates (multi-monitor origin at leftmost screen). Null if not visible. */
+    globalViewport: GlobalViewport | null;
+    /** Bevy world coordinates. */
+    world: Vec3;
+}
+interface SpawnVrmOptions {
+    transform?: TransformArgs;
+    persona?: Persona;
+}
+/**
+ * A single keyframe in a speech timeline.
+ */
+interface TimelineKeyframe {
+    /**
+     * Duration of this keyframe in seconds.
+     */
+    duration: number;
+    /**
+     * Expression targets to set during this keyframe.
+     * Keys are expression names (e.g. "aa", "ih", "happy"), values are weights (0.0-1.0).
+     */
+    targets?: Record<string, number>;
+}
+/**
+ * Options for the timeline speech API.
+ */
+interface SpeakTimelineOptions {
+    /**
+     * If true, the method will wait for the speech to complete.
+     * Defaults to true.
+     */
+    waitForCompletion?: boolean;
+    /**
+     * Duration in seconds for smoothstep blending between adjacent keyframes.
+     * Defaults to 0.05 (50ms). Clamped to 40% of each keyframe's duration.
+     */
+    transitionDuration?: number;
+}
+interface VrmPointerEvent {
+    /**
+     * The cursor position in the global viewport.
+     */
+    globalViewport: [number, number];
+}
+interface VrmDragEvent extends VrmPointerEvent {
+    /**
+     * The change in cursor position since the last event.
+     */
+    delta: [number, number];
+}
+type Button = "Primary" | "Secondary" | "Middle";
+interface VrmMouseEvent extends VrmPointerEvent {
+    /**
+     * The button that was pressed or released.
+     */
+    button: Button;
+}
+interface VrmStateChangeEvent {
+    /**
+     * The new state of the VRM.
+     */
+    state: string;
+}
+interface PersonaChangeEvent {
+    /**
+     * The updated persona.
+     */
+    persona: Persona;
+}
+type EventMap = {
+    "drag-start": VrmPointerEvent;
+    "drag": VrmDragEvent;
+    "drag-end": VrmPointerEvent;
+    "pointer-press": VrmMouseEvent;
+    "pointer-click": VrmMouseEvent;
+    "pointer-release": VrmMouseEvent;
+    "pointer-over": VrmPointerEvent;
+    "pointer-out": VrmPointerEvent;
+    "pointer-cancel": VrmPointerEvent;
+    "pointer-move": VrmPointerEvent;
+    "state-change": VrmStateChangeEvent;
+    "expression-change": VrmStateChangeEvent;
+    "vrma-play": VrmStateChangeEvent;
+    "vrma-finish": VrmStateChangeEvent;
+    "persona-change": PersonaChangeEvent;
+};
+interface VrmMetadata {
+    name: string;
+    entity: number;
+}
+type Bones = "hips" | "spine" | "chest" | "neck" | "head" | "leftShoulder" | "leftArm" | "leftForeArm" | "leftHand" | "rightShoulder" | "rightArm" | "rightForeArm" | "rightHand" | "leftUpLeg" | "leftLeg" | "leftFoot" | "rightUpLeg" | "rightLeg" | "rightFoot";
+declare class VrmEventSource implements Disposable {
+    readonly eventSource: EventSource;
+    constructor(eventSource: EventSource);
+    /**
+     * Registers an event listener for the specified event type.
+     */
+    on<K extends keyof EventMap>(event: K, callback: (event: EventMap[K]) => (void | Promise<void>)): void;
+    /**
+     * Closes the EventSource connection.
+     */
+    close(): void;
+    [Symbol.dispose](): void;
+}
+declare class Vrm {
+    readonly entity: number;
+    constructor(entity: number);
+    /**
+     * Returns an EventSource for receiving events related to this VRM entity.
+     */
+    events(): VrmEventSource;
+    /**
+     * Returns the current state of the VRM.
+     */
+    state(): Promise<string>;
+    /**
+     * Sets the state of the VRM.
+     *
+     * @param state The new state to set.
+     */
+    setState(state: string): Promise<void>;
+    /**
+     * Returns the persona of the VRM.
+     *
+     * @example
+     * ```typescript
+     * const vrm = await Vrm.findByName("MyAvatar");
+     * const persona = await vrm.persona();
+     * console.log(persona.profile);
+     * ```
+     */
+    persona(): Promise<Persona>;
+    /**
+     * Sets the persona of the VRM.
+     *
+     * @param persona The persona data to set.
+     *
+     * @example
+     * ```typescript
+     * const vrm = await Vrm.findByName("MyAvatar");
+     * await vrm.setPersona({
+     *   profile: "A cheerful assistant",
+     *   ocean: { openness: 0.8, extraversion: 0.7 },
+     *   metadata: {},
+     * });
+     * ```
+     */
+    setPersona(persona: Persona): Promise<void>;
+    /**
+     * Returns the name of the VRM avatar.
+     */
+    name(): Promise<string>;
+    /**
+     * Finds the entity ID of a bone by its name.
+     */
+    findBoneEntity(bone: Bones): Promise<number>;
+    /**
+     * Despawns this VRM entity.
+     */
+    despawn(): Promise<void>;
+    /**
+     * Gets the current position of this VRM in both screen and world coordinates.
+     *
+     * @example
+     * ```ts
+     * const vrm = await Vrm.findByName("MyCharacter");
+     * const pos = await vrm.position();
+     * console.log(`Screen: (${pos.globalViewport?.[0]}, ${pos.globalViewport?.[1]})`);
+     * console.log(`World: (${pos.world[0]}, ${pos.world[1]}, ${pos.world[2]})`);
+     * ```
+     */
+    position(): Promise<PositionResponse>;
+    /**
+     * Gets all expressions and their current weights, including metadata
+     * such as binary status and override settings.
+     *
+     * @example
+     * ```typescript
+     * const vrm = await Vrm.findByName("MyAvatar");
+     * const { expressions } = await vrm.expressions();
+     * for (const expr of expressions) {
+     *   console.log(`${expr.name}: ${expr.weight}`);
+     * }
+     * ```
+     */
+    expressions(): Promise<ExpressionsResponse>;
+    /**
+     * Sets expression weights, replacing all previous overrides.
+     * Expressions not included will return to VRMA animation control.
+     *
+     * @param weights A record of expression names to weight values (0.0-1.0).
+     *
+     * @example
+     * ```typescript
+     * const vrm = await Vrm.findByName("MyAvatar");
+     * await vrm.setExpressions({ happy: 1.0, blink: 0.5 });
+     * ```
+     */
+    setExpressions(weights: Record<string, number>): Promise<void>;
+    /**
+     * Modifies specific expression weights without affecting others (partial update).
+     * Existing overrides not mentioned remain unchanged.
+     *
+     * @param weights A record of expression names to weight values (0.0-1.0).
+     *
+     * @example
+     * ```typescript
+     * const vrm = await Vrm.findByName("MyAvatar");
+     * // Only modifies "happy", leaves other overrides intact
+     * await vrm.modifyExpressions({ happy: 1.0 });
+     * ```
+     */
+    modifyExpressions(weights: Record<string, number>): Promise<void>;
+    /**
+     * Clears all expression overrides, returning control to VRMA animation.
+     *
+     * @example
+     * ```typescript
+     * const vrm = await Vrm.findByName("MyAvatar");
+     * await vrm.clearExpressions();
+     * ```
+     */
+    clearExpressions(): Promise<void>;
+    /**
+     * Modifies mouth expression weights for lip-sync.
+     * Unspecified mouth expressions are reset to 0.0.
+     * Non-mouth expression overrides are preserved.
+     *
+     * @param weights A record of mouth expression names to weight values (0.0-1.0).
+     *
+     * @example
+     * ```typescript
+     * const vrm = await Vrm.findByName("MyAvatar");
+     * await vrm.modifyMouth({ aa: 0.8, oh: 0.2 });
+     * ```
+     */
+    modifyMouth(weights: Record<string, number>): Promise<void>;
+    /**
+     * Gets all spring bone chains.
+     */
+    springBones(): Promise<SpringBoneChainsResponse>;
+    /**
+     * Gets a single spring bone chain by entity ID.
+     *
+     * @param chainId The chain entity ID.
+     */
+    springBone(chainId: number): Promise<SpringBoneChain>;
+    /**
+     * Updates spring bone properties for a chain.
+     *
+     * @param chainId The chain entity ID.
+     * @param props Partial properties to update.
+     */
+    setSpringBone(chainId: number, props: Partial<SpringBoneProps>): Promise<void>;
+    /**
+     * Gets all VRMA animations for this VRM.
+     */
+    listVrma(): Promise<VrmaInfo[]>;
+    /**
+     * Plays a VRMA animation.
+     *
+     * @param options Play request options including asset, repeat, transition.
+     */
+    playVrma(options: VrmaPlayRequest): Promise<void>;
+    /**
+     * Stops a VRMA animation.
+     *
+     * @param asset The asset ID of the VRMA animation to stop.
+     */
+    stopVrma(asset: string): Promise<void>;
+    /**
+     * Gets the state of a VRMA animation.
+     *
+     * @param asset The asset ID of the VRMA animation to query.
+     */
+    vrmaState(asset: string): Promise<VrmaState>;
+    /**
+     * Sets the playback speed of a VRMA animation.
+     *
+     * @param asset The asset ID of the VRMA animation.
+     * @param speed The playback speed.
+     */
+    setVrmaSpeed(asset: string, speed: number): Promise<void>;
+    /**
+     * Speaks using pre-generated audio with a timeline of expression keyframes.
+     * This allows any TTS engine to be used — the engine receives WAV audio and
+     * frame-synchronized lip-sync data.
+     *
+     * @param audio - WAV audio data as ArrayBuffer or Uint8Array.
+     * @param keyframes - Timeline keyframes specifying expression targets and durations.
+     * @param options - Optional settings (e.g. waitForCompletion).
+     *
+     * @example
+     * ```typescript
+     * const vrm = await Vrm.findByName("MyAvatar");
+     * const wavData = await fetchWavFromTTS("Hello world");
+     * await vrm.speakWithTimeline(wavData, [
+     *   { duration: 0.1, targets: { aa: 1.0 } },
+     *   { duration: 0.05 },
+     *   { duration: 0.12, targets: { oh: 1.0, happy: 0.5 } },
+     * ]);
+     * ```
+     */
+    speakWithTimeline(audio: ArrayBuffer | Uint8Array, keyframes: TimelineKeyframe[], options?: SpeakTimelineOptions): Promise<void>;
+    /**
+     * Looks at the mouse cursor.
+     */
+    lookAtCursor(): Promise<void>;
+    /**
+     * Sets the VRM's look-at target to a specific entity.
+     *
+     * @param target The entity ID to look at.
+     */
+    lookAtTarget(target: number): Promise<void>;
+    /**
+     * Disables the VRM's look-at functionality.
+     */
+    unlook(): Promise<void>;
+    /**
+     * Spawns a new VRM instance from the given mod asset ID.
+     */
+    static spawn(asset: string, options?: SpawnVrmOptions): Promise<Vrm>;
+    /**
+     * Finds a VRM instance by its name.
+     *
+     * @param vrmName VRM avatar name
+     */
+    static findByName(vrmName: string): Promise<Vrm>;
+    /**
+     * Waits for a VRM instance to be spawned and initialized by its name.
+     *
+     * @param vrmName VRM avatar name
+     */
+    static waitLoadByName(vrmName: string): Promise<Vrm>;
+    /**
+     * Returns entity IDs of all currently loaded VRM instances.
+     *
+     * @example
+     * ```typescript
+     * const entities = await Vrm.findAllEntities();
+     * console.log(`Found ${entities.length} VRM entities`);
+     * ```
+     */
+    static findAllEntities(): Promise<number[]>;
+    /**
+     * Returns detailed snapshot of all VRM instances.
+     *
+     * @example
+     * ```typescript
+     * const snapshots = await Vrm.findAllDetailed();
+     * for (const s of snapshots) {
+     *   console.log(`${s.name}: ${s.state} at (${s.globalViewport?.[0]}, ${s.globalViewport?.[1]})`);
+     * }
+     * ```
+     */
+    static findAllDetailed(): Promise<VrmSnapshot[]>;
+    static streamMetadata(f: (vrm: VrmMetadata) => (void | Promise<void>)): EventSource;
+    /**
+     * Streams all currently existing VRM instances and any VRM instances that will be created in the future.
+     * @param f
+     */
+    static stream(f: (vrm: Vrm) => (void | Promise<void>)): EventSource;
+    /**
+     * Returns all VRM instances that are currently loaded.
+     */
+    static findAll(): Promise<Vrm[]>;
+    private fetch;
+    private post;
+    private put;
+    private patch;
+    private delete;
+}
+
+/**
+ * Command script utilities for Desktop Homunculus mods.
+ *
+ * This module provides helpers for parsing stdin input and writing structured
+ * output in mod command scripts (`bin/` scripts invoked via the HTTP command
+ * execution API).
+ *
+ * **Input:** {@link input.parse} / {@link input.parseMenu} / {@link input.read}
+ * **Output:** {@link output.succeed} / {@link output.fail} / {@link output.write} / {@link output.writeError}
+ *
+ * @remarks
+ * This module uses Node.js APIs (`process.stdin`, `fs.writeFileSync`) and is
+ * not browser-compatible. Import from `@hmcs/sdk/commands` — it is intentionally
+ * not re-exported from the main `@hmcs/sdk` entry point.
+ *
+ * @example
+ * ```typescript
+ * import { z } from "zod";
+ * import { input, output, StdinParseError } from "@hmcs/sdk/commands";
+ *
+ * const schema = z.object({ name: z.string() });
+ *
+ * try {
+ *   const data = await input.parse(schema);
+ *   output.succeed({ greeting: `Hello, ${data.name}!` });
+ * } catch (err) {
+ *   output.fail("GREET_FAILED", (err as Error).message);
+ * }
+ * ```
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Error thrown by {@link input.parse} when stdin is empty, contains invalid JSON,
+ * or fails Zod schema validation.
+ *
+ * @example
+ * ```typescript
+ * import { input, StdinParseError } from "@hmcs/sdk/commands";
+ *
+ * try {
+ *   const data = await input.parse(schema);
+ * } catch (err) {
+ *   if (err instanceof StdinParseError) {
+ *     console.error(JSON.stringify({ code: err.code, message: err.message }));
+ *     process.exit(1);
+ *   }
+ *   throw err;
+ * }
+ * ```
+ */
+declare class StdinParseError extends Error {
+    /** Structured error code identifying the failure stage. */
+    readonly code: "EMPTY_STDIN" | "INVALID_JSON" | "VALIDATION_ERROR";
+    /** For `VALIDATION_ERROR`, contains the `ZodError` instance. */
+    readonly details?: unknown | undefined;
+    readonly name = "StdinParseError";
+    constructor(
+    /** Structured error code identifying the failure stage. */
+    code: "EMPTY_STDIN" | "INVALID_JSON" | "VALIDATION_ERROR", message: string, 
+    /** For `VALIDATION_ERROR`, contains the `ZodError` instance. */
+    details?: unknown | undefined);
+}
+/**
+ * Input helpers for reading and parsing stdin in bin command scripts.
+ *
+ * @example
+ * ```typescript
+ * import { z } from "zod";
+ * import { input } from "@hmcs/sdk/commands";
+ *
+ * const data = await input.parse(
+ *   z.object({ name: z.string(), count: z.number() })
+ * );
+ * ```
+ */
+declare namespace input {
+    /**
+     * Read all of stdin as a UTF-8 string.
+     *
+     * Consumes the entire `process.stdin` stream via async iteration and returns
+     * the concatenated result. Useful when you need the raw string without JSON
+     * parsing or validation.
+     *
+     * @example
+     * ```typescript
+     * import { input } from "@hmcs/sdk/commands";
+     *
+     * const raw = await input.read();
+     * console.log("Received:", raw);
+     * ```
+     */
+    function read(): Promise<string>;
+    /**
+     * Read JSON from stdin and validate it against a Zod schema.
+     *
+     * Performs three steps:
+     * 1. Reads all of stdin via {@link input.read}
+     * 2. Parses the raw string as JSON
+     * 3. Validates the parsed object against the provided Zod schema
+     *
+     * @typeParam T - The output type inferred from the Zod schema
+     * @param schema - A Zod schema to validate the parsed JSON against
+     * @returns The validated and typed input object
+     * @throws {StdinParseError} With `code: "EMPTY_STDIN"` if stdin is empty or whitespace-only
+     * @throws {StdinParseError} With `code: "INVALID_JSON"` if stdin is not valid JSON
+     * @throws {StdinParseError} With `code: "VALIDATION_ERROR"` if the JSON does not match the schema
+     *
+     * @example
+     * ```typescript
+     * import { z } from "zod";
+     * import { input } from "@hmcs/sdk/commands";
+     *
+     * const data = await input.parse(
+     *   z.object({
+     *     entity: z.number(),
+     *     text: z.union([z.string(), z.array(z.string())]),
+     *     speaker: z.number().default(0),
+     *   })
+     * );
+     * ```
+     */
+    function parse<T>(schema: ZodType<T>): Promise<T>;
+    /**
+     * Parse menu command stdin and return the linked VRM instance.
+     *
+     * Menu commands receive `{ "linkedVrm": <entityId> }` on stdin from the
+     * menu UI. This helper validates the input and returns a ready-to-use
+     * {@link Vrm} instance.
+     *
+     * @returns A {@link Vrm} instance for the linked entity
+     * @throws {StdinParseError} With `code: "EMPTY_STDIN"` if stdin is empty
+     * @throws {StdinParseError} With `code: "INVALID_JSON"` if stdin is not valid JSON
+     * @throws {StdinParseError} With `code: "VALIDATION_ERROR"` if `linkedVrm` is missing or not a number
+     *
+     * @example
+     * ```typescript
+     * import { input } from "@hmcs/sdk/commands";
+     *
+     * const vrm = await input.parseMenu();
+     * await vrm.setExpressions({ happy: 1.0 });
+     * ```
+     */
+    function parseMenu(): Promise<Vrm>;
+}
+/**
+ * Output helpers for writing structured results and errors in bin command scripts.
+ *
+ * @example
+ * ```typescript
+ * import { output } from "@hmcs/sdk/commands";
+ *
+ * output.succeed({ count: 42, status: "done" });
+ * ```
+ */
+declare namespace output {
+    /**
+     * Write a JSON-serialized result to stdout (fd 1).
+     *
+     * Serializes `data` with `JSON.stringify` and writes it followed by a newline
+     * to file descriptor 1 using synchronous I/O. This ensures the output is
+     * flushed before the process exits.
+     *
+     * @param data - The value to serialize as JSON and write to stdout
+     *
+     * @example
+     * ```typescript
+     * import { output } from "@hmcs/sdk/commands";
+     *
+     * output.write({ count: 42, status: "done" });
+     * // stdout receives: {"count":42,"status":"done"}\n
+     * ```
+     */
+    function write(data: unknown): void;
+    /**
+     * Write a structured JSON error to stderr (fd 2).
+     *
+     * Serializes an object with `code` and `message` fields and writes it followed
+     * by a newline to file descriptor 2 using synchronous I/O.
+     *
+     * @param code - A machine-readable error code (e.g., `"NOT_FOUND"`, `"TIMEOUT"`)
+     * @param message - A human-readable error description
+     *
+     * @example
+     * ```typescript
+     * import { output } from "@hmcs/sdk/commands";
+     *
+     * output.writeError("NOT_FOUND", "Entity 42 does not exist");
+     * // stderr receives: {"code":"NOT_FOUND","message":"Entity 42 does not exist"}\n
+     * ```
+     */
+    function writeError(code: string, message: string): void;
+    /**
+     * Write a JSON result to stdout and exit the process with code 0.
+     *
+     * This is a convenience wrapper that calls {@link output.write} followed by
+     * `process.exit(0)`. Use this as the final call in a successful bin command.
+     *
+     * @param data - The value to serialize as JSON and write to stdout
+     *
+     * @example
+     * ```typescript
+     * import { input, output } from "@hmcs/sdk/commands";
+     *
+     * const data = await input.parse(schema);
+     * const result = await doWork(data);
+     * output.succeed({ processed: result.count });
+     * ```
+     */
+    function succeed(data: unknown): never;
+    /**
+     * Write a structured error to stderr and exit the process.
+     *
+     * This is a convenience wrapper that calls {@link output.writeError} followed by
+     * `process.exit(exitCode)`. Use this when a bin command encounters a fatal error.
+     *
+     * @param code - A machine-readable error code (e.g., `"NOT_FOUND"`, `"TIMEOUT"`)
+     * @param message - A human-readable error description
+     * @param exitCode - Process exit code (default: `1`)
+     *
+     * @example
+     * ```typescript
+     * import { output } from "@hmcs/sdk/commands";
+     *
+     * if (!response.ok) {
+     *   output.fail("API_ERROR", `Server returned ${response.status}`);
+     * }
+     * ```
+     */
+    function fail(code: string, message: string, exitCode?: number): never;
+}
+
+export { StdinParseError, input, output };